Colombia - Bre-B

Overview

Bre-B is Colombia's instant account-to-account payment rail, operated by Banco de la República (the Colombian central bank) under regulation DSP-465. It enables 24/7/365 transfers between bank accounts using Bre-B keys — short customer-chosen identifiers that route money to a bank account without exposing the account number.

The four Bre-B key types are:

PayRetailers offers Bre-B as payin (customers pay merchants) and as payout (merchants send funds to customers) for shops operating in Colombia. Funds settle on the rail typically in under 20 seconds.

Why use Bre-B

Country, currency, and verticals

Limits

Regulatory cap (per transaction)

1,000 UVB per transaction, set annually by Colombian authorities. In 2026, 1 UVB = COP 12,110, so the per-transaction cap is COP 12,110,000. Updated each January when the new UVB takes effect.

Operational caps (per banking app)

Each Colombian banking app sets its own per-day or per-transaction operational cap, independent of the rail's regulatory cap. Reported caps as of launch:

These caps are set by the banks (not by PayRetailers and not enforced centrally by the rail). Banks may change them without notice. PayRetailers reports the figures observed at launch as a guideline.

Customer experience

The Bre-B payin customer experience has two paths depending on the banking app. PayRetailers' landing page renders both options so the customer chooses the path their app supports.

Path A — QR scan

The customer opens their banking app (Nequi, BBVA, Banco de Bogotá, Banco Popular, Scotiabank Colpatria, and others), selects "Bre-B" or "Pay via QR", and scans the QR shown on the landing page. The amount is locked in the QR; the customer confirms and pays.

Path B — Manual key entry

The customer opens their banking app (Bancolombia, Davivienda, DaviPlata, and others), selects "Bre-B" or "Transfer to a Bre-B key", enters the Bre-B key shown on the landing page (a copy-to-clipboard button is provided), and enters the amount as displayed.

Why two paths? Not all Colombian banking apps reliably support scanning Bre-B QRs in every key format (notably Bancolombia and Davivienda do not reliably scan alphanumeric-key QRs, and DaviPlata does not scan QRs at all). The manual-key path serves those customers. Together, the two paths support every Colombian bank from day one without per-bank UX branching on the merchant side.

Merchants using PayRetailers' hosted landing page get this behavior automatically. Merchants rendering their own landing page should consume the Get Landing Info endpoint and render both surfaces concurrently.

How payins work (technical flow)

1. Create the payment

Endpoint: POST https://api.payretailers.com/payments/v2/transactions

{
  "paymentMethodTagName": "BREB",
  "amount": "50000",
  "currency": "COP",
  "description": "Order #12345",
  "trackingId": "ORD-12345",
  "notificationUrl": "https://merchant.example.com/payretailers/webhook",
  "returnUrl": "https://merchant.example.com/checkout/return",
  "language": "ES",
  "customer": {
    "firstName": "Maria",
    "lastName": "Gomez",
    "email": "[email protected]",
    "country": "CO",
    "personalId": "1XXXXXXXX0",
    "city": "Bogotá",
    "address": "Carrera 7 # 12-34",
    "ip": "200.118.10.10"
  }
}

Use "paymentMethodTagName": "BREB" to select Bre-B (the tag name is fixed; uppercase).

The response includes a uid (transaction UID), status PENDING, and a form.action (the URL that takes the customer to the PayRetailers landing page).

2. Land the customer

Redirect the customer to form.action (PayRetailers' hosted landing). Alternatively, render your own landing using the data returned by Get Landing Info.

The landing-info response contains the typed buckets needed to render the page:

3. Customer pays

The customer scans the QR or enters the Bre-B key in their banking app and confirms.

4. PayRetailers receives the partner notification

The Bre-B rail confirms the transfer (typically within seconds). PayRetailers receives a signed notification from the partner, validates it, and updates the transaction status.

5. Webhook to the merchant

PayRetailers sends a webhook to the merchant's notificationUrl with the final status (APPROVED or REJECTED) and the payer block.

For Bre-B, the payer block contains:

Other sub-fields documented in the global payer block (e.g., accountNumber, accountAgencyNumber, bankTrackingID, maskCardNumber) are not populated for Bre-B — the rail routes by key, not by account number, and the bank does not expose account-level details.

Webhook example (APPROVED):

{
  "uid": "9e016e99-f83f-7de7-b64a-f1e934ac5df4",
  "type": "payment",
  "status": "APPROVED",
  "amount": 50000,
  "currency": "COP",
  "trackingId": "ORD-12345",
  "createdAt": "2026-06-05T14:00:00Z",
  "updatedAt": "2026-06-05T14:00:08Z",
  "customer": {
    "firstName": "Maria",
    "lastName": "Gomez",
    "email": "[email protected]",
    "country": "CO",
    "personalId": "1XXXXXXXX0"
  },
  "payer": {
    "name": "Maria",
    "lastName": "Gomez",
    "personalId": "1XXXXXXXX0",
    "bankName": "Bancolombia"
  }
}

Error semantics

Most common errors merchants will see

For the full list, see Transaction Error Messages.

Recommended UX patterns

For merchants rendering their own Bre-B landing page (consuming the Get Landing Info endpoint):

1. Show both surfaces concurrently. Render the QR code AND the Bre-B key with a copy-to-clipboard affordance. A meaningful portion of Colombian customers will use each path; do not force a choice or hide one.
2. Display the beneficiary name as a trust signal. Use bankInfoFields[type=BENEFICIARY]. Customers paying to an unfamiliar Bre-B key benefit from seeing the merchant name confirmed.
3. Localize. The instructions array in the Get Landing Info response is already localized. Use it instead of writing your own instruction copy.
4. Be honest about timing. Bre-B is typically just seconds end-to-end, but occasionally takes longer if a participating bank is degraded. Avoid promising "instant"; communicate "usually a few seconds".

Onboarding and going live

To offer Bre-B as a payment method:

1. Confirm Colombia (CO) is in your country scope with PayRetailers.
2. Confirm your vertical is supported (most are; gambling have additional requirements).
3. Confirm with PayRetailers which Bre-B features are activated for your account (3PP validation).
4. Test in PayRetailers' staging environment with the credentials provided — payin flow today; payout flow when the API extension lands.
5. Coordinate go-live with PayRetailers support.

Cross-references

• API reference: Create Transaction · Get Landing Info · Create Payout · Notifications
• Error catalogue: Transaction Error Messages
• Country page: Colombia