Bre-B (Colombia)

Bre-B is Colombia's first government-mandated real-time payment rail, launched October 6, 2025 by Banco de la República. For the first time, all licensed banks, eWallets, and PSPs in the country share a single instant, interoperable infrastructure — similar to how Pix transformed Brazil.

Bre-B introduces instant account-to-account (A2A) transfers under 20 seconds, 24/7/365 availability, and alias-based payments (called llaves) that eliminate the need to share full account numbers. Participation is mandatory for all regulated financial institutions, making Bre-B the fastest-growing payment rail Colombia has ever seen.

Localpayment supports Bre-B for both receiving and sending payments:

Flow	Method	Payment Code	Currency	Max Amount
Payin (receiving)	Virtual Account	`2006`	COP	COP 12,110,000
Payout (sending)	Bank Transfer	`0062`	COP	COP 11,552,000

Overview

Bre-B vs. PSE: When to Use Each

Colombia already has PSE as an established A2A payment option. Bre-B doesn't replace it — it adds a faster, always-on alternative. Use this table to choose the right method for your use case:

	PSE	Bre-B
Settlement	Batch cycles — depends on banking cut-offs	Instant, anytime — no clearing delays
Availability	Banking hours only (typically 8–5, Mon–Fri)	24/7/365, including nights, weekends, and holidays
Checkout experience	Full account details required + bank redirect	No redirect — payer uses an alias (llave) or QR
Interoperability	Participating banks only, flow varies	Mandatory for all licensed banks, wallets, and PSPs
Confirmation speed	Hours to days depending on timing	Under 20 seconds, guaranteed
Ideal for	Established flows with existing PSE integration	New integrations, real-time use cases, 24/7 coverage

Bre-B Key (Llave)

The llave (key) is a short alphanumeric alias that replaces a full bank account number for Bre-B transfers. Payers just enter the key in their banking app — no full account details required.

How Localpayment generates your key

When you create a Virtual Account for Colombia, Localpayment automatically generates an alphanumeric key — you do not choose or configure a key type. The key is built deterministically from the beneficiary name you provide:

Part	Content	Description
1	`LP`	Fixed prefix identifying Localpayment as the key issuer.
2	Up to 10 alphanumeric characters	First characters of the beneficiary name after stripping spaces and special characters (e.g., `-`, `.`, accents).
3	4-digit sequential counter	Zero-padded counter that increments for each key issued (e.g., `0001`, `0002`, `0003`).

Total key length: between 10 and 16 alphanumeric characters (the @ prefix symbol is not counted).

Example — beneficiary name "TechColombia SAS":

Strip spaces and special chars → TechColombiaSAS
Take the first 10 alphanumeric characters → TechColomb
Combine → @ + LP + TechColomb + 0001 = @LPTechColomb0001 (16 characters)

The generated key is returned in beneficiary.bank.account.number once the virtual account activates (status.code: "200").

Limits & Availability

Property	Payin (code `2006`)	Payout (code `0062`)
Currency	`COP`	`COP`
Minimum Amount	COP 1.00	COP 1.00
Maximum Amount	COP 12,110,000.00	COP 11,552,000.00
Settlement Speed	Real-time (< 20 s)	Real-time (< 20 s)
Availability	24/7/365	24/7/365
Payment Confirmation	Asynchronous (webhook)	Asynchronous (webhook)

Demo

See how a payer interacts with a Bre-B Virtual Account in practice:

Receiving Bre-B Payments (Payin)

Payin via Bre-B uses the Virtual Account infrastructure. Localpayment generates a unique Bre-B alphanumeric key for each account you create. Payers send funds to that key from any Bre-B-enabled banking app. Settlement is instant and fully automated.

How It Works

Create a Virtual Account: your system calls the Create Virtual Account endpoint with the beneficiary details.
Retrieve the Bre-B key: once the account activates (~6 seconds), query its status to get the system-generated key from beneficiary.bank.account.number.
Share the key with the payer: the payer enters the key in their banking app to initiate the transfer.
Receive funds and webhook: Localpayment receives the transfer and sends a real-time webhook to your configured endpoint.

Before You Begin

Ensure you have:

Valid API credentials (access token).
A Localpayment account configured for Colombia (COP).

Step 1. Create a Virtual Account

Send a POST request to the Create Virtual Account endpoint.

Key Request Parameters

Parameter	Type	Required	Description	Example
`country`	string	✅	Must be `COL` for Colombia.	`"COL"`
`accountNumber`	string	✅	Your Localpayment merchant account number.	`"{{accountNumber}}"`
`externalId`	string	✅	Your unique identifier for this virtual account. Use a UUID.	`"a1b2c3d4-..."`
`beneficiary.type`	string	✅	`INDIVIDUAL` (person) or `COMPANY` (legal entity).	`"COMPANY"`
`beneficiary.name`	string	✅	Full name or legal entity name. The first characters are used to generate the Bre-B key.	`"TechColombia SAS"`
`beneficiary.document.type`	string	✅	`NIT` for companies; `CC`, `CE`, `TI`, or `PASS` for individuals.	`"NIT"`
`beneficiary.document.id`	string	✅	Document number matching the format for the selected type.	`"901275418-3"`

See all available parameters in the API reference.

Example Request

curl --request POST \
     --url https://api.stage.localpayment.com/api/virtual-account \
     --header 'Authorization: Bearer <your_access_token>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '{
  "country": "COL",
  "accountNumber": "{{accountNumber}}",
  "externalId": "a1b2c3d4-5e6f-7890-abcd-ef1234567890",
  "beneficiary": {
    "type": "COMPANY",
    "name": "TechColombia SAS",
    "document": {
      "type": "NIT",
      "id": "901275418-3"
    }
  }
}'

Successful Response

{
  "externalId": "a1b2c3d4-5e6f-7890-abcd-ef1234567890",
  "internalId": "8f3e1c20-4b72-4d5a-9a1b-2c3d4e5f6078",
  "accountNumber": "{{accountNumber}}",
  "country": "COL",
  "currency": "COP",
  "beneficiary": {
    "type": "COMPANY",
    "name": "TechColombia SAS",
    "fullName": "TechColombia SAS",
    "lastName": "",
    "document": {
      "type": "NIT",
      "id": "901275418-3"
    }
  },
  "status": {
    "code": "100",
    "description": "INPROGRESS",
    "detail": "Virtual account in progress"
  },
  "errors": []
}

Error Response

{
  "externalId": "a1b2c3d4-5e6f-7890-abcd-ef1234567890",
  "internalId": "f2d9d9b0-093d-469b-c8d6-728b0cc67e80",
  "status": {
    "code": "300",
    "description": "REJECTED",
    "detail": "Invalid param + [document.id] + verification failed"
  },
  "errors": [
    {
      "code": "300",
      "detail": "Invalid param + [document.id] + verification failed"
    }
  ]
}

⏱️
Activation time: Colombia virtual accounts typically activate within 6 seconds. Poll the status endpoint or wait briefly before retrieving the Bre-B key.

ℹ️
Non-local beneficiaries
If your beneficiary is a foreign resident (non-local to Colombia), the virtual account must be registered under Localpayment as the account holder. This ensures compliance with local banking regulations while still allowing you to receive payments on behalf of foreign entities.

Step 2. Retrieve Your Bre-B Key

Once the virtual account is active (status.code: "200"), send a GET request to the Get Virtual Account Status endpoint.

Example Request

curl --request GET \
     --url 'https://api.stage.localpayment.com/api/virtual-account/a1b2c3d4-5e6f-7890-abcd-ef1234567890' \
     --header 'Authorization: Bearer <your_access_token>' \
     --header 'accept: application/json'

Successful Response

{
  "externalId": "a1b2c3d4-5e6f-7890-abcd-ef1234567890",
  "internalId": "8f3e1c20-4b72-4d5a-9a1b-2c3d4e5f6078",
  "accountNumber": "{{accountNumber}}",
  "country": "COL",
  "currency": "COP",
  "beneficiary": {
    "type": "COMPANY",
    "name": "TechColombia SAS",
    "fullName": "TechColombia SAS",
    "lastName": "",
    "document": {
      "type": "NIT",
      "id": "901275418-3"
    },
    "bank": {
      "account": {
        "type": "KEY",
        "number": "@LPTechColomb0001"
      }
    }
  },
  "status": {
    "code": "200",
    "description": "COMPLETED",
    "detail": "Virtual account active and ready for payments"
  },
  "errors": []
}

Key Response Fields

Field	Description
`beneficiary.bank.account.number`	The Bre-B key to share with the payer (e.g., `@LPTechColomb0001`).
`beneficiary.bank.account.type`	Always `KEY` for Bre-B virtual accounts.
`status.code`	`200` = active and ready to receive. `100` = still activating.

Share the value from beneficiary.bank.account.number with the payer. No additional bank account details are required.

Step 3. Payer Initiates the Transfer

The payer uses the Bre-B key in any participating Colombian banking app or digital wallet:

Open their banking app and select the Bre-B or Transfer by key option.
Enter the Bre-B key (e.g., @LPTechColomb0001) as the destination.
Enter the amount and confirm the transfer.
Payment completes in under 20 seconds.

Localpayment automatically matches the incoming payment to your virtual account and dispatches a webhook.

Step 4. Handle Webhooks

Localpayment sends a POST request to your configured endpoint once the payment is credited. Your server must respond with HTTP 200 OK to acknowledge receipt. See the Webhooks guide for setup instructions.

Webhook Payload Example

{
    "transactionType": "PayIn",
    "externalId": "cf194632-7ec4-4a44-9b92-9bbacad5349a",
    "internalId": "b97ac13c-1acb-4bc0-8b2a-067945e26161",
    "paymentMethod": {
        "type": "BankTransfer",
        "code": "2006",
        "flow": "DIRECT"
    },
    "country": "COL",
    "currency": "COP",
    "amount": 1000,
    "accountNumber": "{{accountNumber}}",
    "confirmed": {
        "currency": "COP",
        "fxQuote": 1.0,
        "amount": 1000.0
    },
    "payment": {
        "currency": "COP",
        "fxQuote": 1.0,
        "financingFee": 0.0,
        "amount": 1000.0
    },
    "localTaxes": [],
    "withHoldings": [],
    "fees": {
        "description": "Fee",
        "currency": "COP",
        "fxSource": 3705.82,
        "fxQuote": 1.0,
        "amount": 1.0,
        "account": "{{accountNumber}}"
    },
    "status": {
        "code": "200",
        "description": "COMPLETED",
        "detail": "The payin was credited"
    },
    "beneficiary": {
        "type": "COMPANY",
        "name": "LOCALPAYMENT",
        "document": {
            "type": "NIT",
            "id": "1111123456"
        },
        "bank": {
            "name": "BANCO DE BOGOTÁ",
            "code": "1001",
            "account": {
                "type": "KEY",
                "number": "@XXXXXXXOXX0000"
            }
        }
    },
    "merchant": {
        "type": "COMPANY",
        "name": "Test company"
    },
    "payer": {
        "type": "INDIVIDUAL",
        "name": "John",
        "lastName": "Doe",
        "document": {
            "type": "CC",
            "id": "11111654321"
        },
        "email": "NA",
        "bank": {
            "name": "BANCO POPULAR",
            "code": "1002",
            "account": {
                "type": "BREB",
                "number": "signer:wTUTnHK5mLAQXLgVuhoANKGaKTdgRFmrx7@breb"
            }
        }
    },
    "date": {
        "creationDate": "2026-02-25T18:53:25Z",
        "processedDate": "2026-02-25T18:53:26Z"
    },
    "errors": [],
    "referenceCode": "V0ZO-AIPV-NOD9",
    "tracking": {
        "id": "20260225900504001TFY123451234501234",
        "reference": "20260225900504001TFY123451234501234",
        "concept": "Test payment"
    }
}

Key Webhook Fields

Field	Description
`paymentMethod.code`	Always `2006` for Bre-B Virtual Account payins.
`status.code`	`200` = `COMPLETED` — funds have been credited.
`beneficiary.bank.account.number`	Your Virtual Account's Bre-B key that received the payment.
`payer.bank.account.type`	`BREB` — confirms the payer sent via the Bre-B network.
`tracking.id` / `tracking.reference`	Bre-B network transaction reference. Use for reconciliation.
`tracking.concept`	Transfer description provided by the payer.
`referenceCode`	Localpayment's unique reference for this transaction.

Step 5. Track Payin Status

Webhooks (Recommended)

Receive real-time notifications when a payment is credited. Most efficient for production environments.

Status API Endpoint

Query transaction status programmatically. Useful for reconciling missed webhook notifications.

Dashboard View

Visual interface for monitoring transactions. Great for manual oversight and detailed analysis.

Bre-B is a real-time direct payment rail — transactions settle instantly. The webhook is dispatched only once the payment is fully credited.

Code	Status	Description
`200`	`COMPLETED`	Payment credited to your account.

🗒️
Complete Reference
View all status codes in our Transaction Status Documentation.

Sending Bre-B Payments (Payout)

To send funds to a recipient's Bre-B key, use the Bank Transfer payout flow with payment method code 0062. The recipient must have a Bre-B key registered at their bank. You provide that key via beneficiary.bank.account.alias.

How It Works

Collect the recipient's Bre-B key: obtain the recipient's registered llave (any supported key type: alphanumeric, phone, email, document, or merchant code).
Submit the payout: call the Create Payout endpoint with code 0062 and the key in beneficiary.bank.account.alias.
Track the transfer: monitor status via webhooks or the Status API until 200 Completed.

Step 1. Initiate the Payout

Send a POST request to the Create a Payout endpoint. Note that the request body is an array.

Key Request Parameters

Parameter	Type	Required	Description	Example
`country`	string	✅	Must be `COL`.	`"COL"`
`currency`	string	✅	Must be `COP`.	`"COP"`
`amount`	number	✅	Transaction amount. Min COP 1.00, max COP 11,552,000.00.	`50000`
`paymentMethod.type`	string	✅	Must be `BankTransfer`.	`"BankTransfer"`
`paymentMethod.code`	string	✅	Must be `0062` for Bre-B.	`"0062"`
`paymentMethod.flow`	string	✅	Must be `DIRECT`.	`"DIRECT"`
`beneficiary.type`	string	✅	`INDIVIDUAL` or `COMPANY`.	`"INDIVIDUAL"`
`beneficiary.name`	string	✅	Recipient's first name or company name.	`"John"`
`beneficiary.lastName`	string	✅	Recipient's last name (individuals only).	`"Doe"`
`beneficiary.document.type`	string	✅	`CC`, `NIT`, `CE`, `TI`, or `PASS`.	`"CC"`
`beneficiary.document.id`	string	✅	Document number matching the format for the selected type.	`"1088338888"`
`beneficiary.bank.account.alias`	string	✅	Recipient's registered Bre-B key (llave). Do not include `account.type` or `account.number`.	`"@juanPerez0001"`
`accountNumber`	string	✅	Your Localpayment merchant account number.	`"{{accountNumber}}"`
`externalId`	string	✅	Your unique identifier for this payout. Use a UUID.	`"b2c3d4e5-..."`
`conceptCode`	string	✅	Payment concept code provided by Localpayment.	`"0001"`

⚠️
Important: When sending to a Bre-B key, the beneficiary.bank.account.type and beneficiary.bank.account.number fields must be excluded from the request. Use only beneficiary.bank.account.alias.

Example Request

curl --request POST \
     --url https://api.stage.localpayment.com/api/payout/ \
     --header 'Authorization: Bearer <your_access_token>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '[
  {
    "externalId": "b2c3d4e5-6f7a-8901-bcde-f12345678901",
    "country": "COL",
    "currency": "COP",
    "amount": 50000,
    "paymentMethod": {
      "type": "BankTransfer",
      "code": "0062",
      "flow": "DIRECT"
    },
    "beneficiary": {
      "type": "INDIVIDUAL",
      "name": "John",
      "lastName": "Doe",
      "document": {
        "type": "CC",
        "id": "1088338888"
      },
      "email": "[email protected]",
      "bank": {
        "account": {
          "alias": "@juanPerez0001"
        }
      }
    },
    "sender": {
      "type": "COMPANY",
      "name": "TechColombia SAS",
      "document": {
        "type": "NIT",
        "id": "901275418-3"
      },
      "email": "[email protected]"
    },
    "merchant": {
      "type": "COMPANY",
      "name": "TechColombia SAS",
      "document": {
        "type": "NIT",
        "id": "901275418-3"
      }
    },
    "accountNumber": "{{accountNumber}}",
    "conceptCode": "0001",
    "comment": "Pago Bre-B Colombia"
  }
]'

Successful Response

{
    "externalId": "b2c3d4e5-6f7a-8901-bcde-f12345678901",
    "internalId": "3a4b5c6d-7e8f-9012-cdef-a12345678902",
    "paymentMethod": {
        "code": "0062",
        "name": "Bre-B Key",
        "paymentMethodType": "BankTransfer"
    },
    "country": "COL",
    "currency": "COP",
    "amount": 50000,
    "accountNumber": "{{accountNumber}}",
    "status": {
        "code": "100",
        "description": "Received",
        "detail": "The payout was received"
    },
    "beneficiary": {
        "type": "INDIVIDUAL",
        "name": "John",
        "lastname": "Doe",
        "document": {
            "type": "CC",
            "id": "1088338888"
        },
        "email": "[email protected]",
        "bank": {
            "account": {
                "alias": "@juanPerez0001"
            }
        }
    },
    "date": {
        "creationDate": "2026-02-25T18:53:25Z",
        "processedDate": "2026-02-25T18:53:26Z"
    },
    "errors": null
}

Error Response

[
  {
    "externalId": "b2c3d4e5-6f7a-8901-bcde-f12345678901",
    "internalId": "cd052d8c-8406-45f8-98aa-aff9876c3285",
    "status": {
      "code": "801",
      "description": "Rejected",
      "detail": "Params error"
    },
    "errors": [
      {
        "code": "300",
        "description": "Invalid param + [paymentMethod.code] + doesn't exist for PAYMENT_METHOD_TYPE BankTransfer"
      }
    ]
  }
]

Step 2. Track Payout Status

Webhooks (Recommended)

Receive real-time notifications when the transfer is debited. Most efficient for production environments.

Status API Endpoint

Query payout status programmatically. Useful for reconciliation and exception handling.

Dashboard View

Visual interface for monitoring and manually approving payouts.

Code	Status	Description
`100`	`Received`	The payout was received by Localpayment.
`101`	`Locked`	Confirmed and passed AML validations.
`102`	`In Progress`	Sent to the Bre-B network.
`200`	`Completed`	Funds credited to the recipient.
`300`	`Rejected`	Invalid parameter — check the `errors` array for details.

🗒️
Complete Reference
View all status codes in our Transaction Status Documentation.

Supported Banks

Bre-B payments can be sent and received across all participating Colombian financial institutions — 200+ banks, digital wallets, and cooperatives connected to the Banco de la República network.

Full bank list

A&C COLANTA
ACCIONES Y VALORES
AFROAMERICANA
ALCALICOOP
AMAR
AVANCOP

FAQ

How long does it take for my Bre-B Virtual Account to become active?

Colombia virtual accounts typically activate within 6 seconds. The VA creation response returns status.code: "100" INPROGRESS. Poll the Get Virtual Account Status endpoint until you receive status.code: "200" COMPLETED before sharing the key with payers.

Can I use the same Bre-B key for multiple payments?

Yes. A Virtual Account and its associated Bre-B key remain active until you explicitly deactivate or delete them. You can receive an unlimited number of payments to the same key over time.

What happens if a payer sends more than the maximum amount?

Transfers exceeding the maximum (COP 12,110,000 for payin, COP 11,552,000 for payout) will be rejected by the Bre-B network. The payer will see an error in their banking app. For high-value transfers, split into multiple transactions.

Can I receive Bre-B payments outside business hours?

Yes — Bre-B operates 24/7/365 by Banco de la República mandate. There are no blackout windows, no weekends, and no holiday restrictions.

What is the difference between account.number and account.alias?

These fields serve different purposes depending on the flow:

beneficiary.bank.account.number: Used in the Get Virtual Account Status response — this is where Localpayment returns the auto-generated Bre-B key for your payin virtual account. It is a read-only output field.
beneficiary.bank.account.alias: Used in the Create Payout request — this is where you provide the recipient's Bre-B key when initiating a payout. It is an input field.

For payouts, never include account.type or account.number — only account.alias.

Why is my payout request rejected with 'Invalid param + [paymentMethod.code]'?

This error typically means paymentMethod.code is not "0062" or paymentMethod.type is not "BankTransfer". Double-check both fields and ensure paymentMethod.flow is set to "DIRECT". Also confirm you are passing the request body as a JSON array (wrapped in [...]).

How does Localpayment generate the Bre-B key for my Virtual Account?

The key is built deterministically from the beneficiary name you provide at VA creation:

Strip all spaces and special characters from the beneficiary name.
Take the first 10 alphanumeric characters of the resulting string.
Combine: @ + LP + name segment + 4-digit sequential counter.

Example: "TechColombia SAS" → strip spaces → TechColombiaSAS → first 10 → TechColomb → key = @LPTechColomb0001.

The counter (0001, 0002, etc.) increments with each key issued. Final key length is between 10 and 16 alphanumeric characters, excluding the @ symbol.

Testing Your Integration

Sandbox Environment

Use the staging environment for all testing:

# Virtual Account (payin)
POST https://api.stage.localpayment.com/api/virtual-account

# Bank Transfer payout
POST https://api.stage.localpayment.com/api/payout/

Test Scenarios

Verify your integration handles these scenarios:

VA Creation: Create a Virtual Account for Colombia and confirm the 100 INPROGRESS response.
Key Retrieval: Poll the status endpoint until status.code: "200", then verify beneficiary.bank.account.number contains a valid Bre-B key.
Payment Receipt (Payin): Simulate an incoming Bre-B payment and validate your webhook handler returns HTTP 200. See Receive Payment Notifications for webhook setup.
Payout Submission: Submit a payout with code 0062 and a valid beneficiary.bank.account.alias.
Duplicate Notification Handling: Verify your system handles webhook retries idempotently using internalId or externalId.
Account Lifecycle: Test enabling, disabling, and deleting virtual accounts.

Next Steps

Manage Virtual Account Lifecycle

Enable or disable Bre-B keys to temporarily pause or resume payment collection without deleting the virtual account.

Refund a Payin

Issue a refund for a received Bre-B payment through the Localpayment API or Dashboard.

Payment Instructions

See exactly what to share with your payers for Colombia virtual account payments.

Review Transaction Details

Retrieve full transaction information using the Localpayment API for auditing and reconciliation.