Collections

Guide to testing and simulating collection payments in the Bre-B sandbox environment

This sandbox environment lets you test your collection integration end-to-end without processing real payments. You can simulate incoming payments to your collections, including both successful and failed scenarios.

Prerequisites

At least one collection with an active Bre-B key
The collection associated to the Bre-B key must be in ready or minimum_paid state.

Sandbox Collections simulator

If you want to simulate a payment without writing any code, open the Bre-B sandbox simulator. It is a Mono-hosted web tool that pays any of your sandbox collection keys end-to-end — the same webhooks fire as in a real payment.

Three input modes

Enter a key manually (Ingresar llave) — paste a Bre-B key value.
Scan a QR (Escanear QR) — use your device camera to read a Bre-B QR.
Upload a QR image (Subir imagen) — drag-and-drop a saved QR.

Form fields

Field	Purpose
`Llave de pago`	Destination Bre-B key (auto-filled when you scan or upload a QR).
`Monto (COP)`	Amount in Colombian pesos. Required.
`Tipo de error`	Optional. Pick a failure mode to exercise rejection paths.
`Datos del pagador`	Optional. Override the auto-generated payer information.

Click Simular Pago and the simulator drives the same end-to-end flow as the POST /sandbox/collection-attempts API documented below — meaning the webhooks you receive on your endpoint are identical.

When to use which

Use the web simulator if...	Use the API endpoint if...
You want a quick check without writing a script	You're adding sandbox calls to a test suite
You're verifying a specific scenario by hand	You need to script bulk simulations
You haven't set up sandbox tooling yet (Postman, scripts, etc.)	You're already in your test runner

Simulating a collection attempt

Send a POST request to simulate a payer making a payment to one of your collection keys. This endpoint is only available in the sandbox environment.

Minimal example

{
  "creditor_key_value": "@YOURBREBKEY",
  "amount": {
    "amount": 50000,
    "currency": "COP"
  }
}

The sandbox will generate random payer information and payment_id if they aren't provided, and process the payment through the full flow. You will receive a 202 Accepted response immediately:

{
  "collection_id": "bbcol_5g8k2mNpQrStUvWx",
  "attempt_id": "bbcolat_7hJkLmNpQrStUvWx",
  "transfer_id": "bbit_1a2b3c4d5e6f7g8h9i0j",
  "attempt_state_reason": null
}

A few seconds later, the webhook events will be delivered to your configured webhook URL with the final attempt result. You could receive the following collection webhooks:

collection.attempt_successful: The payment attempt was settled successfully by the simulation workflow.
collection.attempt_unsuccessful: The payment attempt was rejected (either by a simulated error or a validation failure).
collection.paid: The collection has reached its total amount.
collection.minimum_paid: The collection has reached its minimum required amount.

Error simulation

By default, simulated payments complete successfully. To test how your integration handles failures, pass an error field:

{
  "creditor_key_value": "@MN1234567890",
  "amount": {
    "amount": 50000,
    "currency": "COP"
  },
  "error": "tx_risk_control"
}

The payment is still created and you will receive the 202 Accepted response, but the subsequent webhook event will carry a rejection status.

Available error codes

Error code	Description
`tx_unknown`	An unexpected error occurred
`tx_provider_unavailable`	The Bre-B system is unavailable
`tx_breb_timeout`	The Bre-B system timed out
`tx_risk_control`	Transaction blocked by risk control rules

Expected flow

You call the sandbox endpoint to simulate a payment.
The API responds with 202 Accepted.
After a short delay (2–5 seconds), a webhook is sent to your configured URL.
1. If no error was specified, the payment settles successfully.
2. If an error was specified, the payment is rejected with the corresponding reason.

Collections

On this page