Receiving a Bre-B Payment
Overview
This document outlines the lifecycle of enabling a potential buyer to send the Merchant a Payment using a QR Code within the Colombia Bre-B ecosystem. It is recommended to commence each Payment by presenting a QR Code as a user friendly manner to convert the necessary information to initiate the transfer.
Intended for:
- Technical teams implementing API integrations.
- Product teams evaluating user experience.
- Business stakeholders assessing real-time payment strategies.
Flow Overview
The image below summarizes the steps from the QR Code generation request, through to the Merchant Webhook confirmation. The key steps to consider in this page are the inbound notifications and information that will be received for the PaaS Platform when a Payment for a Merchant arrives at the Sponsor Bank.
Transaction Diagram Flow
QR Code Payment Steps
| Step | Action | From | To |
|---|---|---|---|
| 1 | QR Request | PoS / Backend | PaaS Platform |
| 2 | QR Generation | PaaS Platform | Bre-B Node |
| 3 | QR Presented to Customer | PoS | Buyer |
| 4 | Payment Initiated | Buyer | Customer's Bank |
| 5 | Payment Routed | Customer's Bank | Bre-B Node -> Bank Sponsor |
| 6 | Incoming Payment Notification | Bank Sponsor | PaaS Platform |
| 7 | Webhook Sent to the PoS | PaaS Platform | PoS |
Flow Description
The page QR Code Payment Lifecycle explains the QR Code process in this diagram, so the following descriptions will focus on Step 4 onwards. The previous steps were giving context to how the inbound payment fits into a larger lifecycle.
Step 4: Payment Initiation
The originating Financial Entity will extract relevant Payment information and present that to their Customer within the respective digital channel - a mobile banking app (perhaps it scanned the QR Code), or a digital website (where the Customer manually entered the Bre-B Key and payment amount).
The Financial Entity will resolve the Bre-B Key - similar to the endpoints that the PaaS Platform exposes - in order to convert the friendly alias into routing information that the network uses to ensure the Payment reaches the desired receiver.
Step 5: Payment Routing
Once the Customer approves the receiver and confirms the sending of the Payment, the originating Financial Entity routes the payment message through the Bre-B network:
Financial Entity -> Originating Node -> Banco de la República -> Receiving Node -> Receiving Financial Entity
The network messages manage the identification of which Financial Entity is connected to which Bre-B Node and ensures the appropriate direction of travel.
Step 6: Incoming Payment Notification
The Receiving Financial Entity accepts the inbound payment request assuming the payment passes relevant AML and financial checks (does the Account exist, has it been closed, is the receipient on a watch list).
- At this stage, the payment is in
ACCEPTEDstatus as the Sponsor Bank accepts the Payment after completing initial Fraud Monitoring and Anti Money Laundering steps - The Inbound Payment messages are translated by the PaaS platform and prepared to be shared with the appropriate Developer who owns the receiving Bank Account.
Being so early in the Bre-B service lifecycle, there are known base information as well as information that is due to be included in the coming months (as of time of writing in October 2025).
For example, an inbound payment will always include information regarding the receiver (Name, Identification Number), the Bank Account (Account Type and Account Number) and the Participant (the Financial Entity ID Number). This is what many of the Financial Entities certified against and passed.
The qr_code_reference that was mentioned in the QR Code Payment lifecycle will be included in the Payment information, however it is not mandatory at launch (although some Financial Entities have implemented it) but will be mandatory within 3 months after launch.
Also, within 3 months after launch, the Bre-B Key that the sender used to initiate the payment should be present in the Payment body - this is to help fight fraud, but also create more innovative opportunities for Payment Providers and Brands within Colombia.
Step 7: Webhook Confirmation
The PaaS Platform sends a webhook to the Merchant notifying of the inbound payment. There are two webhooks - one for the inbound payment arriving at the Sponsor Bank, and one for when the money settles at the Banco de la República.
- Once the Banco de la República transfers the funds between the Financial Entities, then the Payment has been
SETTLEDand a webhook is sent (typically 7 seconds after the inbound payment notification).
Payment Identification
While the Bre-B ecosystem is still young and growing, it is unclear if every Financial Entity has implemented the mandatory fields (as it is self certification for most), nor if the optional fields have also been implemented.
Passport proposes three mechanisms to identify an inbound Payment and match up to a pending sale deposit / transfer within the Developer ecosystem.
Option 1: qr_code_reference
If a QR Code has been used to initiate the inbound Payment (such as from the Point of Sale examples given on the QR Code Payment Lifecycle page) then the senders Financial Entity is mandated to provide that through to the receivers Financial Entity.
If provided, this will be present in the Inbound Payment Notification and can be used to reconcile to a pending sale or expected deposit.
The qr_code_reference field is tested during the certification process with the initial Financial Entities, however not all Financial Entities go through that process and therefore it is not guaranteed that it will be present on all inbound payments.
Option 2: Key Identifiers
If the Customer Experience allows, a unique Key can be created for each inbound Payment.
Opposed to creating a unique QR Code to commence the payment lifecycle, a unique Bre-B Key could be created for each known buyer. This could be useful for services where the buyer could receive a unique Key to send funds to.
If the Developer only has one Merchant Account at the Sponsor Bank, while there are no limits on the number of Keys can be created, the Key will always be resolved to the Merchant Name as the Owner.
So if Passport Software SaS created the alphanumeric key @testuserpurchase1234 - the sender will still see Passport Software SaS as the recipient within their mobile banking application.
Unfortunately, it is only an optional field for the first few months of the Bre-B service, it is not expected to become mandatory until 3 months after official launch - early January 2026 at the time of writing.
Option 3: Payment Meta-Data
As a last option, certain business models could use the basic information that is provided on the inbound Payment notification. This includes:
- Owner Full Name
- Owner Identification Type and Number
- Bank Account Number and Type
- Bank Identification Number
- Payment Amount and Timestamp
If the Developer has registered users, then their service may already have some of that information and could be used to cross reference with anticipated inbound payments.
For example, if a Platform is expecting a payment from Test User, with Identification Number 123456789, for $100,000 COP on the 8th September 2025 at 14:30:15, and a Payment arrives from a Test User at 8th September at 14:30:35 then it is likely to match.
This is the most basic manner to identify inbound payments, however it does assume that the Developer has information available that can be used to identify with. For scenarios at physical retail stores for example, that may not be the case and may have to revert to the amount and date of the inbound payment.