Payout / Alternative payment methods / Colombia

Bre-B

POST https://payments.apipro.io/v2/payout

The ApiPro Payout API allows you to send funds to your clients' bank accounts in Colombia. This document provides instructions on how to create and manage these Bre-B (QR Code) payouts.

How Bre-B Payouts Work

1. Request: Your application makes a POST request to the ApiPro payout endpoint to create a transaction.

2. Processing: ApiPro processes the payout, interacting with the corresponding banking provider in Colombia.

3. Notification: Once the transaction reaches a terminal state (e.g., success or error), ApiPro sends a callback (webhook) to your specified callback_url.

Headers

Header	Value
Content-Type	application/json
Authorization	{{authorization}}
Digest	{{digest}}
Host	{{host}}
Date	{{date}}

See Authentication & Signature for how to build the signed headers.

Request body

Annotations in the example are the field requirements: required, optional or conditional. Comments are stripped automatically by the Postman collection before signing; remove them in your own requests.

{
    "method": "qr_code", // required, snake_case / lower case only: "qr_code" (not "QR_CODE" or "QrCode")
    "reference": "ColombiaPayoutQRTest(1)", // required, unique
    "currency": "COP", // required
    "amount": 50, // required
    "description": "order payout", // optional,
    "customer": // required
    {
        "identifier": "1234567890123456789012", // required, any unique value from the merchant's system may be used.
        "email": "rrecamango@gmail.com", // optional
        "phone": "+573205671968", // optional
        "first_name": "Roxana", // optional
        "last_name": "Recaman", // optional
        "middle_name": "", // optional
        "country": "CO", // optional
        "state_code": "DC", // optional
        "city": "Bogotá", // optional
        "address": "Carrera 7 # 26-20", // optional
        "zip_code": "110311", // optional
        "itn": "1045726853", // optional, CC (Cédula de Ciudadanía) / CE (Cédula de Extranjería) / NIT (Número de Identificación Tributaria)
        "birthday": "2006-01-22", // optional
        "ip": "192.168.0.1", // optional
        "gender": "male" // optional
    },
    "qr_code": { // required
        "account_number": "1000296999931", // required
        "account_type": "SAVINGS", // required, SAVINGS by default
        "beneficiary_first_name": "Roxana", // required
        "beneficiary_last_name": "Recaman", // required
        "beneficiary_email": "rrecamango@gmail.com", // optional
        "beneficiary_phone": "+573205671968", // required
        "beneficiary_document_type": "CC", // required
        "beneficiary_document_value": "1045726853", // required
        "breb_code": "1234567" // required
    },
    "lang": "es", // optional
    "redirect_url": "redirect_url", // optional
    "cancel_url": "cancel_url", // optional
    "callback_url": "callback_url", // optional
    "extra": { // optional, any field which may be needed for transaction routing and integration
        "meta": {
            "key": "value"
        }
    }
}

Fields

Field	Type	Requirement / note
method	string	required, snake_case / lower case only: "qr_code" (not "QR_CODE" or "QrCode")
reference	string	required, unique
currency	string	required
amount	integer	required
description	string	optional,
customer	object	required
customer.identifier	string	required, any unique value from the merchant's system may be used.
customer.email	string	optional
customer.phone	string	optional
customer.first_name	string	optional
customer.last_name	string	optional
customer.middle_name	string	optional
customer.country	string	optional
customer.state_code	string	optional
customer.city	string	optional
customer.address	string	optional
customer.zip_code	string	optional
customer.itn	string	optional, CC (Cédula de Ciudadanía) / CE (Cédula de Extranjería) / NIT (Número de Identificación Tributaria)
customer.birthday	string	optional
customer.ip	string	optional
customer.gender	string	optional
qr_code	object	required
qr_code.account_number	string	required
qr_code.account_type	string	required, SAVINGS by default
qr_code.beneficiary_first_name	string	required
qr_code.beneficiary_last_name	string	required
qr_code.beneficiary_email	string	optional
qr_code.beneficiary_phone	string	required
qr_code.beneficiary_document_type	string	required
qr_code.beneficiary_document_value	string	required
qr_code.breb_code	string	required
lang	string	optional
redirect_url	string	optional
cancel_url	string	optional
callback_url	string	optional
extra	object	optional, any field which may be needed for transaction routing and integration
extra.meta	object
extra.meta.key	string

Responses

ResponsesCallback

Response Examples

HTTP 200 (57)HTTP 401 (15)

Card can only be used with specific methods. Check documentation

{
  "error_code": 30,
  "error_reason": "Invalid params",
  "description": "Card can only be used with specific methods. Check documentation",
  "request_id": "YOUR_REFERENCE",
  "status": "error",
  "timestamp": "2025-10-26T14:05:00.00Z"
}

Customer is blocked

{
  "error_code": 451,
  "error_reason": "General risk decline",
  "description": "Customer is blocked",
  "request_id": "YOUR_REFERENCE",
  "status": "error",
  "timestamp": "2025-10-26T14:06:00.00Z"
}

Customer is blocked for all merchant projects

{
  "error_code": 451,
  "error_reason": "General risk decline",
  "description": "Customer is blocked for all merchant projects",
  "request_id": "YOUR_REFERENCE",
  "status": "error",
  "timestamp": "2025-10-26T14:08:02.00Z"
}

Customer is blocked for the specified project

{
  "error_code": 451,
  "error_reason": "General risk decline",
  "description": "Customer is blocked for the specified project",
  "request_id": "YOUR_REFERENCE",
  "status": "error",
  "timestamp": "2025-10-26T14:08:04.00Z"
}

Customer is blocked system-wide

{
  "error_code": 451,
  "error_reason": "General risk decline",
  "description": "Customer is blocked system-wide",
  "request_id": "YOUR_REFERENCE",
  "status": "error",
  "timestamp": "2025-10-26T14:08:06.00Z"
}

Customer is globally locked

{
  "error_code": 451,
  "error_reason": "General risk decline",
  "description": "Customer is globally locked",
  "request_id": "YOUR_REFERENCE",
  "status": "error",
  "timestamp": "2025-10-26T14:08:08.00Z"
}

Resource not found

{
  "error_code": 35,
  "error_reason": "Resource not found",
  "description": "The requested resource is undefined",
  "request_id": "value_from_data_reference",
  "status": "error",
  "timestamp": "2025-10-02T14:15:00.00Z"
}

Routing failed

{
  "error_code": 121,
  "error_reason": "Routing failed",
  "timestamp": "2025-10-02T14:17:00.00Z"
}

Unknown routing error

{
  "error_code": 1,
  "error_reason": "Unknown routing error",
  "timestamp": "2025-10-02T14:17:00.00Z"
}

Routing service error: Value cannot be null. (Parameter 'data')

{
  "error_code": 1,
  "error_reason": "Routing service error: Value cannot be null. (Parameter 'data')",
  "timestamp": "2025-10-02T14:17:00.00Z"
}

Routing request timeout

{
  "error_code": 2,
  "error_reason": "Routing request timeout",
  "timestamp": "2025-10-02T14:17:00.00Z"
}

Required fields are missing: method, reference, amount, currency

{
  "error_code": 31,
  "error_reason": "Required fields are missing: method, reference, amount, currency",
  "timestamp": "2025-10-02T14:16:00.00Z"
}

Routing service error: Endpoint type cannot be null or empty

{
  "error_code": 1,
  "error_reason": "Routing service error: Endpoint type cannot be null or empty",
  "timestamp": "2025-10-02T14:17:00.00Z"
}

Routing service error

{
  "error_code": 1,
  "error_reason": "Routing service error",
  "timestamp": "2025-10-02T14:17:00.00Z"
}

Payment transaction timeout after seconds

{
  "error_code": 1,
  "error_reason": "Payment transaction timeout after 30 seconds",
  "timestamp": "2025-10-02T14:17:00.00Z"
}

Internal error: Mid {MidId} no longer exists in configuration

{
  "error_code": 1,
  "error_reason": "Internal error: Mid {MidId} no longer exists in configuration",
  "timestamp": "2025-10-02T14:17:00.00Z"
}

Internal error: Value cannot be null. (Parameter 'tcs')

{
  "error_code": 1,
  "error_reason": "Internal error: Value cannot be null. (Parameter 'tcs')",
  "timestamp": "2025-10-02T14:17:00.00Z"
}

Payment transaction was cancelled

{
  "error_code": 1,
  "error_reason": "Payment transaction was cancelled",
  "timestamp": "2025-10-02T14:17:00.00Z"
}

Error while trying to process filling data

{
  "error_code": 200,
  "error_reason": "Error while trying to process filling data",
  "request_id": null,
  "reference": "value_from_data_reference",
  "timestamp": "2025-10-02T14:18:00.00Z"
}

Invalid method challenge configuration. Please reconfigure method challenge type settings

{
  "error_code": 121,
  "error_reason": "Invalid method challenge configuration. Please reconfigure method challenge type settings",
  "timestamp": "2025-10-02T14:19:00.00Z"
}

There is more than one challenge setting for a method. Please reconfigure method challenge type settings

{
  "error_code": 121,
  "error_reason": "There is more than one challenge setting for a method. Please reconfigure method challenge type settings",
  "timestamp": "2025-10-02T14:20:00.00Z"
}

MID not found in cache while getting currency rate

{
  "error_code": 35,
  "error_reason": "Resource not found",
  "description": "MID not found in cache while getting currency rate",
  "request_id": "value_from_data_reference",
  "status": "error",
  "timestamp": "2025-10-02T14:21:00.00Z"
}

Transaction processing error: error while getting currency rate

{
  "error_code": 200,
  "error_reason": "Transaction processing error",
  "description": "Unexpected error while getting currency rate",
  "request_id": "value_from_data_reference",
  "status": "error",
  "timestamp": "2025-10-02T14:22:00.00Z"
}

Transaction processing error: error with payment configurations during calculation

{
  "error_code": 200,
  "error_reason": "Transaction processing error",
  "description": "Error with payment configurations during calculation",
  "request_id": "value_from_data_reference",
  "status": "error",
  "timestamp": "2025-10-02T14:23:00.00Z"
}

Exceeded amount limits for project

{
  "error_code": 1132,
  "error_reason": "Limit exceeded",
  "description": "Amount is outside the allowed project limits",
  "request_id": "value_from_data_reference",
  "status": "error",
  "timestamp": "2025-10-02T14:24:00.00Z"
}

Exceeded amount limits for MID

{
  "error_code": 1132,
  "error_reason": "Limit exceeded",
  "description": "Amount is outside the allowed MID limits",
  "request_id": "value_from_data_reference",
  "status": "error",
  "timestamp": "2025-10-02T14:24:00.00Z"
}

Transaction processing error: error while getting withdrawal rates

{
  "error_code": 200,
  "error_reason": "Transaction processing error",
  "description": "Unexpected error while getting withdrawal rates",
  "request_id": "value_from_data_reference",
  "status": "error",
  "timestamp": "2025-10-02T14:24:00.00Z"
}

Invalid params: transactions constraints were violated

{
  "error_code": 30,
  "error_reason": "Invalid params",
  "description": "Transaction contraints were violated",
  "request_id": "value_from_data_reference",
  "status": "error",
  "timestamp": "2025-10-02T14:26:00.00Z"
}

Failed to create transaction for unfamiliar reason

{
  "error_code": 200,
  "error_reason": "Transaction processing error",
  "description": "Failed to create transaction",
  "request_id": "value_from_data_reference",
  "status": "error",
  "timestamp": "2025-10-02T14:27:00.00Z"
}

Account payout has negative balance after update

{
  "error_code": 1,
  "error_reason": "Insufficient funds on account",
  "description": "Account payout has negative balance after update",
  "request_id": "value_from_data_reference",
  "status": "error",
  "timestamp": "2025-10-02T14:28:00.00Z"
}

Error with wallet

{
  "error_code": 200,
  "error_reason": "Transaction processing error",
  "description": "Error with wallet",
  "request_id": "value_from_data_reference",
  "status": "error",
  "timestamp": "2025-10-02T14:29:00.00Z"
}

Mid is disabled

{
  "error_code": 32,
  "error_reason": "Invalid MID",
  "description": "Mid is disabled",
  "request_id": "value_from_data_reference",
  "status": "error",
  "timestamp": "2025-10-02T14:30:00.00Z"
}

Blocked routing for transaction: Invalid currency

{
  "error_code": 31,
  "error_reason": "Invalid currency",
  "description": "Blocked routing for transaction: Invalid currency",
  "request_id": "value_from_data_reference",
  "status": "error",
  "timestamp": "2025-10-02T14:31:00.00Z"
}

Blocked routing for transaction: Invalid method

{
  "error_code": 1054,
  "error_reason": "Invalid method",
  "description": "Blocked routing for transaction: Invalid method",
  "request_id": "value_from_data_reference",
  "status": "error",
  "timestamp": "2025-10-02T14:32:00.00Z"
}

Blocked routing for transaction: Invalid payment type

{
  "error_code": 1054,
  "error_reason": "Invalid type",
  "description": "Blocked routing for transaction: Invalid payment type",
  "request_id": "value_from_data_reference",
  "status": "error",
  "timestamp": "2025-10-02T14:33:00.00Z"
}

Requisites - Invalid JSON format

{
  "error_code": 31,
  "error_reason": "Required fields are missing: requisites - invalid JSON format",
  "timestamp": "2025-10-02T14:34:00.00Z"
}

Mid configuration error

{
  "error_code": 200,
  "error_reason": "Mid configuration error",
  "request_id": null,
  "reference": "value_from_data_reference",
  "timestamp": "2025-10-02T14:35:00.00Z"
}

Mid request timeout

{
  "error_code": 200,
  "error_reason": "Mid request timeout",
  "request_id": null,
  "reference": "value_from_data_reference",
  "timestamp": "2025-10-02T14:36:00.00Z"
}

Communication error

{
  "error_code": 200,
  "error_reason": "Communication error",
  "request_id": null,
  "reference": "value_from_data_reference",
  "timestamp": "2025-10-02T14:36:00.00Z"
}

Invalid adapter response format

{
  "error_code": 200,
  "error_reason": "Invalid adapter response format",
  "request_id": null,
  "reference": "value_from_data_reference",
  "timestamp": "2025-10-02T14:37:00.00Z"
}

Failed to register card transaction

{
  "error_code": 200,
  "error_reason": "Failed to register card transaction",
  "request_id": null,
  "reference": "value_from_data_reference",
  "timestamp": "2025-10-02T14:48:00.00Z"
}

Failed to register cascade transaction

{
  "error_code": 200,
  "error_reason": "Failed to register cascade transaction",
  "request_id": null,
  "reference": "value_from_data_reference",
  "timestamp": "2025-10-02T14:48:00.00Z"
}

Mid with ID '[MidId]' not found

{
  "error_code": 200,
  "error_reason": "Mid with ID '[MidId]' not found",
  "request_id": null,
  "reference": "value_from_data_reference",
  "timestamp": "2025-10-02T14:49:00.00Z"
}

Mid [MidName] ([MidId]) is not active

{
  "error_code": 200,
  "error_reason": "Mid [MidName] ([MidId]) is not active",
  "request_id": null,
  "reference": "value_from_data_reference",
  "timestamp": "2025-10-02T14:49:00.00Z"
}

Mid [MidId] no longer exists in configuration

{
  "error_code": 200,
  "error_reason": "Mid [MidId] no longer exists in configuration",
  "request_id": null,
  "reference": "value_from_data_reference",
  "timestamp": "2025-10-02T14:49:00.00Z"
}

Some unexpected error occured

{
  "error_code": 200,
  "error_reason": "<Some unexpected error message>",
  "request_id": null,
  "reference": "value_from_data_reference",
  "timestamp": "2025-10-02T14:49:00.00Z"
}

Request cannot be null

{
  "code": 0,
  "reason": "",
  "error_code": 1,
  "error_reason": "Request cannot be null",
  "request_id": "",
  "reference": "",
  "status": "error",
  "timestamp": "2025-09-29T11:52:39.25Z",
  "description": ""
}

Flow cache limit exceeded

{
  "code": 0,
  "reason": "",
  "error_code": 1,
  "error_reason": "Flow cache limit exceeded",
  "request_id": "",
  "reference": "",
  "status": "error",
  "timestamp": "2025-09-29T11:52:39.25Z",
  "description": ""
}

Flow configuration not found for project: {projectId}

{
  "code": 0,
  "reason": "",
  "error_code": 1,
  "error_reason": "Flow configuration not found for project: {projectId}",
  "request_id": "",
  "reference": "",
  "status": "error",
  "timestamp": "2025-09-29T11:52:39.25Z",
  "description": ""
}

Invalid flow configuration

{
  "code": 0,
  "reason": "",
  "error_code": 1,
  "error_reason": "Invalid flow configuration",
  "request_id": "",
  "reference": "",
  "status": "error",
  "timestamp": "2025-09-29T11:52:39.25Z",
  "description": ""
}

Flow execution failed: some unexpected error

{
  "code": 0,
  "reason": "",
  "error_code": 1,
  "error_reason": "Flow execution failed:",
  "request_id": "",
  "reference": "",
  "status": "error",
  "timestamp": "2025-09-29T11:52:39.25Z",
  "description": ""
}

Node not found: {NodeIdentifier}

{
  "code": 0,
  "reason": "",
  "error_code": 1,
  "error_reason": "Node not found: {NodeIdentifier}",
  "request_id": "",
  "reference": "",
  "status": "error",
  "timestamp": "2025-09-29T11:52:39.25Z",
  "description": ""
}

Flow execution limit exceeded

{
  "code": 0,
  "reason": "",
  "error_code": 1,
  "error_reason": "Flow execution limit exceeded",
  "request_id": "",
  "reference": "",
  "status": "error",
  "timestamp": "2025-09-29T11:52:39.25Z",
  "description": ""
}

Flow ended without result

{
  "code": 0,
  "reason": "",
  "error_code": 1,
  "error_reason": "Flow ended without result",
  "request_id": "",
  "reference": "",
  "status": "error",
  "timestamp": "2025-09-29T11:52:39.25Z",
  "description": ""
}

'qr_code' missing field

{
  "error_code": 31,
  "error_reason": "Required fields are missing: qr_code",
  "timestamp": "2025-10-02T14:25:00.00Z"
}

Succesful transaction

{
  "error_code": 0,
  "error_reason": "",
  "request_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
  "reference": "ColombiaQRPayoutTest(1)",
  "status": "pending",
  "type": "payout",
  "method": "qr_code",
  "mode": "initial",
  "currency": "COP",
  "amount": "5.00",
  "timestamp": "2025-10-04T14:13:19.0806904Z"
}

Duplicated reference

{
  "error_code": 108,
  "error_reason": "Duplicated reference",
  "request_id": "3829f5bd-6dcb-41f9-a4ba-3ff8b65a3cfc",
  "reference": "",
  "timestamp": "2025-11-10T08:47:22.81Z"
}

Invalid Authorization header format

{
  "error_code": 31,
  "error_reason": "Invalid Authorization header format",
  "timestamp": "2025-10-26T14:04:00.00Z"
}

Invalid Signature format

{
  "error_code": 31,
  "error_reason": "Invalid signature format",
  "timestamp": "2025-10-26T14:04:00.00Z"
}

Unsupported algorithm

{
  "error_code": 31,
  "error_reason": "Unsupported algorithm",
  "timestamp": "2025-10-26T14:04:00.00Z"
}

Invalid API key

{
  "error_code": 31,
  "error_reason": "Invalid API key",
  "timestamp": "2025-10-26T14:04:00.00Z"
}

Invalid date format

{
  "error_code": 31,
  "error_reason": "Invalid date format",
  "timestamp": "2025-10-26T14:04:00.00Z"
}

Date is outdated or invalid

{
  "error_code": 31,
  "error_reason": "Date is outdated or invalid",
  "timestamp": "2025-10-26T14:04:00.00Z"
}

Missing Digest header

{
  "error_code": 31,
  "error_reason": "Invalid digest",
  "timestamp": "2025-10-26T14:04:00.00Z"
}

Invalid digest

{
  "error_code": 31,
  "error_reason": "Missing Digest header",
  "timestamp": "2025-10-26T14:04:00.00Z"
}

Invalid signature

{
  "error_code": 31,
  "error_reason": "Invalid signature",
  "timestamp": "2025-10-26T14:04:00.00Z"
}

Invalid headers specification

{
  "error_code": 31,
  "error_reason": "Invalid headers specification",
  "timestamp": "2025-10-26T14:04:00.00Z"
}

Request timestamp has already been used

{
  "error_code": 31,
  "error_reason": "Request timestamp has already been used",
  "timestamp": "2025-10-26T14:04:00.00Z"
}

Missing required authentication headers

{
  "error_code": 31,
  "error_reason": "Missing required authentication headers",
  "timestamp": "2025-10-26T14:04:00.00Z"
}

Missing Authorization header

{
  "error_code": 31,
  "error_reason": "Missing Authorization header",
  "timestamp": "2025-10-26T16:01:00.00Z"
}

Missing Date header

{
  "error_code": 31,
  "error_reason": "Missing Date header",
  "timestamp": "2025-10-26T16:06:00.00Z"
}

Processing error:

{
  "error_code": 210,
  "error_reason": "Processing error:",
  "description": "Processing error:",
  "request_id": "your_transaction_reference",
  "status": "error",
  "timestamp": "2025-10-26T12:03:00.000Z"
}

Callback Notifications

The system sends an HTTP callback to the callback_url of your request when a transaction reaches a final state. Always verify the callback signature; see Callback Verification.

Callback Payload

Callback request

{
  "request_id": "7a8b9c0d-1e2f-3a4b-5c6d-7e8f9a0b1c2d",
  "identifier": "PT_CO_X1Y2Z3A4B5C6",
  "reference": "POUT-CO-QR-ORD-12345-20231127",
  "creation_date": "2023-11-27T18:30:00.123456",
  "method": "qr_code",
  "type": "payout",
  "mode": "initial",
  "status": "success",
  "status_date": "2023-11-27T18:30:02.654321",
  "amount": "250000",
  "currency": "COP",
  "billing_amount": "250000",
  "billing_currency": "COP",
  "fee_amount": "3000",
  "fee_currency": "COP",
  "customer": {
    "identifier": "CUST-CO-9876543210",
    "email": "carlos.rodriguez@example.com",
    "phone": "+573101234567",
    "first_name": "Carlos",
    "last_name": "Rodriguez",
    "country": "CO",
    "state_code": "ANT",
    "city": "Medellín",
    "address": "Calle 10 # 43A-30",
    "zip_code": "050021",
    "itn": "71789012",
    "birthday": "1988-05-15",
    "ip": "181.54.32.10",
    "gender": "male"
  },
  "qr_code": {
    "account_number": "100011102220222",
    "beneficiary_first_name": "Carlos",
    "beneficiary_last_name": "Rodriguez",
    "beneficiary_email": "neda@gmail.com",
    "beneficiary_phone": "+573555777666",
    "beneficiary_document_type": "CC",
    "beneficiary_document_value": "1050999999",
    "breb_code": "1234567"
  },
  "error_code": 0,
  "error_reason": "",
  "timestamp": "2023-11-27T18:30:05.789012"
}