Payment / Alternative payment methods / Colombia / Bre-B

H2H#

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

Initiate a Bre-B QR code payment in Colombia using the Host-to-Host (H2H) integration. Send a payment request with method: "qr_code" and receive a challenge object with challenge_type: "qr", where challenge.challenge_qr contains the QR code data: code (the EMV payload, for rendering yourself or displaying as text) and image (the same code already rendered as a Base64-encoded PNG). Display this to the customer, who scans it with a Bre-B-compatible banking app or e-wallet to confirm the payment.

How It Works#

Send a request to POST https://payments.apipro.io/v2/payment with method: "qr_code", mode: "initial", currency: "COP", and customer details, including itn and extra.meta.documentType.
Check error_code in the response — 0 means the request was accepted.
Check status — on acceptance it is "pending".
Inspect challenge.challenge_type — for Bre-B it is "qr".
Display the QR code to the customer using challenge.challenge_qr.image (a Base64-encoded PNG, e.g. via <img src="data:image/png;base64,{image}">) or challenge.challenge_qr.code (the raw EMV payload, for rendering yourself or showing as a copy-and-paste code).
The customer scans the QR code with a Bre-B-compatible banking app or e-wallet and confirms the payment there.
Receive a callback at your callback_url with the final transaction status once the payment is confirmed.

Request Parameters#

Root Object#

Parameter	Type	Required	Description
`method`	`string`	Yes	Must be `"qr_code"`.
`mode`	`string`	Yes	Must be `"initial"`. Only initial mode is available for this method.
`reference`	`string`	Yes	Unique merchant order ID (1–40 characters).
`currency`	`string`	Yes	Must be `"COP"` (Colombian Peso).
`amount`	`integer`	Yes	Transaction amount in COP (e.g., `5466`).
`description`	`string`	No	Description of the order/payment.
`callback_url`	`string`	Yes	Merchant endpoint for async status notifications.

Customer Object (`customer`)#

Parameter	Type	Required	Description
`customer.identifier`	`string`	Yes	Unique customer ID in your system.
`customer.first_name`	`string`	Yes	Customer's first name.
`customer.last_name`	`string`	Yes	Customer's last name.
`customer.email`	`string`	Yes	Customer's email address.
`customer.phone`	`string`	Yes	Customer's phone number (Colombian format, e.g., `+573103195622`).
`customer.itn`	`string`	Yes	Colombian identification number — the numeric value of the customer's document (matching the `documentType`). Validation: `CC` (Cédula de Ciudadanía — citizens 18+) and `CE` (Cédula de Extranjería — foreigners) — 6–10 digits, no separators, e.g. `1020304050`. `NIT` (Número de Identificación Tributaria — legal entities/self-employed) — digits plus a check digit, formatted `XXXXXXXXX-X`, e.g. `900123456-7`.

Extra / Metadata Object (`extra`)#

Parameter	Type	Required	Description
`extra.meta.documentType`	`string`	Yes	The type of the customer's identification document (see Document Types table below).

Colombian Document Types#

Code	Description	Format (used in `customer.itn`)
`CO_CC`	Cédula de Ciudadanía (Citizenship ID) — for Colombian citizens aged 18 and over.	6–10 digits, no separators, e.g. `1020304050`.
`CO_CE`	Cédula de Extranjería (Foreign Resident ID) — for foreign residents in Colombia.	6–10 digits, no separators, e.g. `1020304050`.
`CO_NIT`	NIT — Número de Identificación Tributaria (Tax ID for businesses) — for legal entities and self-employed individuals.	Digits plus a check digit, formatted `XXXXXXXXX-X`, e.g. `900123456-7`.

Responses#

Status	When
`200 OK`	The request was accepted: `status` is `"pending"` and `challenge.challenge_qr` holds the QR code. See Succesful transaction in the Responses tab.
`200 OK` with `error_code` ≠ 0	The transaction failed — see `error_reason`. See Transaction processing error in the Responses tab.
`400 Bad Request`	Returned when required fields are missing or malformed. See Invalid params in the Responses tab.
`504 Gateway Timeout`	If the upstream provider does not respond within 30 seconds, a `504` is returned. Do not treat this as a failure. Use the Check Transaction Status endpoint or wait for the async callback.

Callback Examples#

Callbacks are sent to your callback_url when the transaction reaches a final status. Always validate the callback signature to avoid suspicious activity. Examples for each final status (Success, Declined, Error, Expired) are in the Callback tab.

Business Logic & Regional Requirements#

Currency Locking: Only "COP" (Colombian Peso) is supported. Any other currency will be rejected.
Method Code: QR Code payments use "qr_code" as the method identifier (snake_case only — not "QR_CODE" or "QrCode").
Document Number (ITN): The customer.itn field is required and must contain a valid Colombian identification number — CC, CE, or NIT (see Colombian Document Types table).
QR Code Display: The API responds with challenge.challenge_type: "qr". The challenge.challenge_qr object contains everything needed to display the code: code (the EMV payload of the Bre-B QR code, usable to render the QR yourself or show as a copy-and-paste code) and image (the same QR code pre-rendered as a Base64-encoded PNG, displayable via <img src="data:image/png;base64,{image}">). The QR code is not delivered via a redirect page — it is returned directly in the API response.
Timeout Handling: A 504 Gateway Timeout may occur if the upstream provider does not respond within 30 seconds. Do not treat this as a failure — use the Check Transaction Status endpoint or wait for the async callback.

Final Status Reference#

For a full explanation of every transaction status (including whether it's final and successful), see Transaction Statuses.

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.

{
    "mode": "initial", // required, only "initial" is available for this method
    "method": "qr_code", // required, snake_case / lower case only: "qr_code" (not "QR_CODE" or "QrCode")
    "reference": "postman-1712345333", // required, unique, 1-40 characters
    "currency": "COP", // required, only COP is supported
    "amount": 5000, // required, amount in COP
    "description": "Top-up of account #314155400", // optional
    "customer": { // required
        "identifier": "customer_1", // required, unique customer ID in your merchant system
        "email": "carlos.mendez@example.com", // required
        "phone": "+573103195622", // required, Colombian format
        "first_name": "Carlos", // required
        "last_name": "Mendez", // required
        "itn": "1130628333" // required, CC (Cédula de Ciudadanía) / CE (Cédula de Extranjería) / NIT (Número de Identificación Tributaria); numeric value of the document matching extra.meta.documentType
    },
    "redirect_url": "https://merchant.shop.com/", // optional
    "cancel_url": "https://merchant.shop.com/cancel", // optional
    "callback_url": "https://merchant.shop.com/success", // required
    "extra": { // required
        "meta": { // required
            "documentType": "CO_CC" // required, CO_CC, CO_CE or CO_NIT (see Colombian Document Types)
        }
    }
}

Fields#

Field	Type	Requirement / note
`mode`	string	required, only "initial" is available for this method
`method`	string	required, snake_case / lower case only: "qr_code" (not "QR_CODE" or "QrCode")
`reference`	string	required, unique, 1-40 characters
`currency`	string	required, only COP is supported
`amount`	integer	required, amount in COP
`description`	string	optional
`customer`	object	required
`customer.identifier`	string	required, unique customer ID in your merchant system
`customer.email`	string	required
`customer.phone`	string	required, Colombian format
`customer.first_name`	string	required
`customer.last_name`	string	required
`customer.itn`	string	required, CC (Cédula de Ciudadanía) / CE (Cédula de Extranjería) / NIT (Número de Identificación Tributaria); numeric value of the document matching extra.meta.documentType
`redirect_url`	string	optional
`cancel_url`	string	optional
`callback_url`	string	required
`extra`	object	required
`extra.meta`	object	required
`extra.meta.documentType`	string	required, CO_CC, CO_CE or CO_NIT (see Colombian Document Types)

Responses#

ResponsesCallback

Response Examples

HTTP 200 (58)HTTP 400 (1)HTTP 401 (15)

Merchant not found

{
  "error_code": 35,
  "error_reason": "Merchant not found",
  "description": "The requested resource is undefined",
  "request_id": "YOUR_REFERENCE",
  "status": "error",
  "timestamp": "2025-10-26T14:01:00.00Z"
}

Required fields are missing: method or widget.method, reference

{
  "error_code": 31,
  "error_reason": "Required fields are missing: method or widget.method, reference",
  "timestamp": "2025-10-26T14:03:00.00Z"
}

Using 'method' and 'widget.method' at the same time.

{
  "error_code": 30,
  "error_reason": "Invalid params",
  "description": "Widget and method cannot be used together",
  "request_id": "YOUR_REFERENCE",
  "status": "error",
  "timestamp": "2025-10-26T14:04:00.00Z"
}

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"
}

Timeout while requesting routing

{
  "error_code": 121,
  "error_reason": "An issue has been detected in the routing settings. For instance, it could be due to a disabled project or bank",
  "description": "Routing request timeout",
  "request_id": "YOUR_REFERENCE",
  "status": "error",
  "timestamp": "2025-10-26T14:08:01.00Z"
}

Payment transaction timeout after some time

{
  "error_code": 121,
  "error_reason": "An issue has been detected in the routing settings. For instance, it could be due to a disabled project or bank",
  "description": "Payment transaction timeout after 30 seconds",
  "request_id": "YOUR_REFERENCE",
  "status": "error",
  "timestamp": "2025-10-26T14:08:03.00Z"
}

Unknown routing error

{
  "error_code": 121,
  "error_reason": "An issue has been detected in the routing settings. For instance, it could be due to a disabled project or bank",
  "description": "Unknown routing error",
  "request_id": "YOUR_REFERENCE",
  "status": "error",
  "timestamp": "2025-10-26T14:08:02.00Z"
}

Payment transaction was cancelled

{
  "error_code": 121,
  "error_reason": "An issue has been detected in the routing settings. For instance, it could be due to a disabled project or bank",
  "description": "Payment transaction was cancelled",
  "request_id": "YOUR_REFERENCE",
  "status": "error",
  "timestamp": "2025-10-26T14:08:04.00Z"
}

Internal error: Data is empty

{
  "error_code": 121,
  "error_reason": "An issue has been detected in the routing settings. For instance, it could be due to a disabled project or bank",
  "description": "Internal error: Value cannot be null. (Parameter 'data')",
  "request_id": "YOUR_REFERENCE",
  "status": "error",
  "timestamp": "2025-10-26T14:08:05.00Z"
}

Endpoint type wasn't found

{
  "error_code": 121,
  "error_reason": "An issue has been detected in the routing settings. For instance, it could be due to a disabled project or bank",
  "description": "Internal error: Endpoint type cannot be null or empty (Parameter 'endpointType')",
  "request_id": "YOUR_REFERENCE",
  "status": "error",
  "timestamp": "2025-10-26T14:08:06.00Z"
}

Mid configuration error

{
  "error_code": 121,
  "error_reason": "An issue has been detected in the routing settings. For instance, it could be due to a disabled project or bank",
  "description": "Internal error: Mid [Mid ID] no longer exists in configuration",
  "request_id": "YOUR_REFERENCE",
  "status": "error",
  "timestamp": "2025-10-26T14:08:07.00Z"
}

Routing service error: Converting data error

{
  "error_code": 121,
  "error_reason": "An issue has been detected in the routing settings. For instance, it could be due to a disabled project or bank",
  "description": "Routing service error: The JSON value could not be converted to System.Guid.",
  "request_id": "YOUR_REFERENCE",
  "status": "error",
  "timestamp": "2025-10-26T14:08:08.00Z"
}

Routing service error

{
  "error_code": 121,
  "error_reason": "An issue has been detected in the routing settings. For instance, it could be due to a disabled project or bank",
  "description": "Routing service error",
  "request_id": "YOUR_REFERENCE",
  "status": "error",
  "timestamp": "2025-10-26T14:08:08.00Z"
}

Broker transport failure

{
  "error_code": 121,
  "error_reason": "An issue has been detected in the routing settings. For instance, it could be due to a disabled project or bank",
  "description": "Internal error: Broker transport failure",
  "request_id": "YOUR_REFERENCE",
  "status": "error",
  "timestamp": "2025-10-26T14:08:09.00Z"
}

Internal error

{
  "error_code": 121,
  "error_reason": "An issue has been detected in the routing settings. For instance, it could be due to a disabled project or bank",
  "description": "Internal error",
  "request_id": "YOUR_REFERENCE",
  "status": "error",
  "timestamp": "2025-10-26T14:08:09.00Z"
}

An issue has been detected in the routing settings. For instance, it could be due to a disabled project or bank

{
  "error_code": 121,
  "error_reason": "An issue has been detected in the routing settings. For instance, it could be due to a disabled project or bank",
  "description": "An issue has been detected in the routing settings. For instance, it could be due to a disabled project or bank",
  "request_id": "YOUR_REFERENCE",
  "status": "error",
  "timestamp": "2025-10-26T14:08:10.00Z"
}

An unexpected error occurred while processing the request

{
  "error_code": 200,
  "error_reason": "Transaction processing error",
  "description": "An unexpected error occurred while processing the request",
  "request_id": "YOUR_REFERENCE",
  "status": "error",
  "timestamp": "2025-10-26T14:09:00.00Z"
}

Invalid method challenge configuration. Settings not found.

{
  "error_code": 121,
  "error_reason": "Invalid method challenge configuration. Please reconfigure method challenge type settings",
  "description": "Invalid method challenge configuration. Settings not found.",
  "request_id": "YOUR_REFERENCE",
  "status": "error",
  "timestamp": "2025-10-26T14:10:00.00Z"
}

Route is invalid (Incorrect method, mid settings)

{
  "error_code": 121,
  "error_reason": "Route is invalid",
  "description": "There is more than one challenge setting for a method. Please reconfigure method challenge type settings.",
  "request_id": "YOUR_REFERENCE",
  "status": "error",
  "timestamp": "2025-10-26T14:11:00.00Z"
}

Getting currency rate info error.

{
  "error_code": 200,
  "error_reason": "While getting currency rate, error happend",
  "description": "An internal error occurred while processing currency information",
  "request_id": "YOUR_REFERENCE",
  "status": "error",
  "timestamp": "2025-10-26T14:12:00.00Z"
}

Error processing currency information.

{
  "error_code": 200,
  "error_reason": "Error with payment configurations",
  "description": "An internal error occurred while processing currency information",
  "request_id": "YOUR_REFERENCE",
  "status": "error",
  "timestamp": "2025-10-26T14:13:00.00Z"
}

Error with wallet

{
  "error_code": 200,
  "error_reason": "Error with wallet",
  "description": "An internal error occurred while processing currency information",
  "request_id": "YOUR_REFERENCE",
  "status": "error",
  "timestamp": "2025-10-26T14:14:00.00Z"
}

Failed to register transaction

{
  "error_code": 200,
  "error_reason": "Failed to register transaction",
  "description": "An internal error occurred while processing currency information",
  "request_id": "YOUR_REFERENCE",
  "status": "error",
  "timestamp": "2025-10-26T14:15:00.00Z"
}

Failed saving card info

{
  "error_code": 200,
  "error_reason": "Transaction processing error",
  "description": "Failed to save card information",
  "request_id": "YOUR_REFERENCE",
  "status": "error",
  "timestamp": "2025-10-26T14:16:00.00Z"
}

Transaction processing error

{
  "error_code": 200,
  "error_reason": "Transaction processing error",
  "identifier": "QR_000000012",
  "request_id": "d2348e57-4ef5-4a7a-8a6c-ef046bf90b5f",
  "reference": "order-00001",
  "status": "error",
  "type": "payment",
  "method": "qr_code",
  "mode": "initial",
  "currency": "COP",
  "amount": "5466",
  "timestamp": "2022-02-09T10:53:33Z"
}

Mid doesn't support challenge type for method (mid or method settings problem)

{
  "error_code": 121,
  "error_reason": "Route is invalid",
  "description": "Mid does not support challenge type [challengeType] for method [method]",
  "request_id": "YOUR_REFERENCE",
  "status": "error",
  "timestamp": "2025-10-26T14:18:00.00Z"
}

Mid is disabled

{
  "error_code": 121,
  "error_reason": "Route is invalid",
  "description": "Mid is disabled",
  "request_id": "YOUR_REFERENCE",
  "status": "error",
  "timestamp": "2025-10-26T14:19:00.00Z"
}

Bank doesn't support currency

{
  "error_code": 1051,
  "error_reason": "Bank doesn't support currency",
  "description": "Blocked routing for transaction: Invalid currency",
  "request_id": "YOUR_REFERENCE",
  "status": "error",
  "timestamp": "2025-10-26T14:20:00.00Z"
}

Bank doesn't support payment method

{
  "error_code": 1054,
  "error_reason": "Bank doesn't support payment method",
  "description": "Blocked routing for transaction: Invalid method: [method]",
  "request_id": "YOUR_REFERENCE",
  "status": "error",
  "timestamp": "2025-10-26T14:21:00.00Z"
}

Bank does not support transaction: Invalid payment type

{
  "error_code": 1050,
  "error_reason": "Bank does not support transaction",
  "description": "Blocked routing for transaction: Invalid payment type",
  "request_id": "YOUR_REFERENCE",
  "status": "error",
  "timestamp": "2025-10-26T14:22:00.00Z"
}

Mid request timeout

{
  "error_code": 200,
  "error_reason": "Mid request timeout",
  "request_id": null,
  "reference": "YOUR_REFERENCE",
  "timestamp": "2025-10-26T14:24:00.00Z"
}

Communication error

{
  "error_code": 200,
  "error_reason": "Communication error",
  "request_id": "[UUID_ТРАНЗАКЦІЇ]",
  "reference": "YOUR_REFERENCE",
  "timestamp": "2025-10-26T14:25:00.00Z"
}

Forbidden

{
  "error_code": 5,
  "error_reason": "Forbidden",
  "timestamp": "2025-10-26T14:33:00.00Z"
}

Some unexpected message

{
  "error_code": 5,
  "error_reason": "[Some unexpected message]",
  "timestamp": "2025-10-26T14:33:00.00Z"
}

Failed to register card transaction

{
  "error_code": 200,
  "error_reason": "Failed to register card transaction",
  "request_id": null,
  "reference": "YOUR_REFERENCE",
  "timestamp": "2025-10-26T14:34:00.00Z"
}

Failed to register cascade transaction

{
  "error_code": 200,
  "error_reason": "Failed to register cascade transaction",
  "request_id": null,
  "reference": "YOUR_REFERENCE",
  "timestamp": "2025-10-26T14:35:00.00Z"
}

Endpoint type cannot be null or empty

{
  "error_code": 200,
  "error_reason": "Endpoint type cannot be null or empty",
  "request_id": null,
  "reference": "YOUR_REFERENCE",
  "timestamp": "2025-10-26T14:36:00.00Z"
}

Data is empty

{
  "error_code": 200,
  "error_reason": "Value cannot be null. (Parameter 'data')",
  "request_id": null,
  "reference": "YOUR_REFERENCE",
  "timestamp": "2025-10-26T14:36:00.00Z"
}

An unexpected internal error occured

{
  "error_code": 200,
  "error_reason": "Transaction processing error",
  "description": "An unexpected internal error occurred",
  "request_id": "YOUR_REFERENCE",
  "status": "error",
  "timestamp": "2025-10-26T14:38:00.00Z"
}

Handler returned null response

{
  "error_code": 210,
  "error_reason": "Handler returned null response",
  "description": "Handler returned null response",
  "request_id": "your_transaction_reference",
  "status": "error",
  "timestamp": "2025-10-26T12:02:00.000Z"
}

Rate limit exceeded

{
  "error_code": 210,
  "error_reason": "Rate limit exceeded",
  "description": "Rate limit exceeded",
  "request_id": "your_transaction_reference",
  "status": "error",
  "timestamp": "2025-10-26T12:01:00.000Z"
}

Access denied: Invalid or missing access token

{
  "error_code": 210,
  "error_reason": "Access denied: Invalid or missing access token",
  "description": "Access denied: Invalid or missing access token",
  "request_id": "your_transaction_reference",
  "status": "error",
  "timestamp": "2025-10-26T12:00:00.000Z"
}

Request cannot be null

{
  "error_code": 121,
  "error_reason": "An issue has been detected in the routing settings. For instance, it could be due to a disabled project or bank",
  "request_id": "[YOUR_REFERENCE]",
  "reference": "",
  "status": "error",
  "timestamp": "2025-10-04T12:56:41.94Z",
  "description": "Request cannot be null"
}

Flow cache limit exceeded

{
  "error_code": 121,
  "error_reason": "An issue has been detected in the routing settings. For instance, it could be due to a disabled project or bank",
  "request_id": "[YOUR_REFERENCE]",
  "reference": "",
  "status": "error",
  "timestamp": "2025-10-04T12:56:41.94Z",
  "description": "Flow cache limit exceeded"
}

Flow configuration not found for project: {projectId}

{
  "error_code": 121,
  "error_reason": "An issue has been detected in the routing settings. For instance, it could be due to a disabled project or bank",
  "request_id": "[YOUR_REFERENCE]",
  "reference": "",
  "status": "error",
  "timestamp": "2025-10-04T12:56:41.94Z",
  "description": "Flow configuration not found for project: {projectId}"
}

Invalid flow configuration

{
  "error_code": 121,
  "error_reason": "An issue has been detected in the routing settings. For instance, it could be due to a disabled project or bank",
  "request_id": "[YOUR_REFERENCE]",
  "reference": "",
  "status": "error",
  "timestamp": "2025-10-04T12:56:41.94Z",
  "description": "Invalid flow configuration"
}

Flow execution failed

{
  "error_code": 121,
  "error_reason": "An issue has been detected in the routing settings. For instance, it could be due to a disabled project or bank",
  "request_id": "[YOUR_REFERENCE]",
  "reference": "",
  "status": "error",
  "timestamp": "2025-10-04T12:56:41.94Z",
  "description": "Flow execution failed"
}

Circular reference detected at node: {NodeIdentifier}

{
  "error_code": 121,
  "error_reason": "An issue has been detected in the routing settings. For instance, it could be due to a disabled project or bank",
  "request_id": "[YOUR_REFERENCE]",
  "reference": "",
  "status": "error",
  "timestamp": "2025-10-04T12:56:41.94Z",
  "description": "Circular reference detected at node: {NodeIdentifier}"
}

Node not found: {NodeIdentifier}

{
  "error_code": 121,
  "error_reason": "An issue has been detected in the routing settings. For instance, it could be due to a disabled project or bank",
  "request_id": "[YOUR_REFERENCE]",
  "reference": "",
  "status": "error",
  "timestamp": "2025-10-04T12:56:41.94Z",
  "description": "Node not found: {NodeIdentifier}"
}

Flow execution limit exceeded

{
  "error_code": 121,
  "error_reason": "An issue has been detected in the routing settings. For instance, it could be due to a disabled project or bank",
  "request_id": "[YOUR_REFERENCE]",
  "reference": "",
  "status": "error",
  "timestamp": "2025-10-04T12:56:41.94Z",
  "description": "Flow execution limit exceeded"
}

Flow ended without result

{
  "error_code": 121,
  "error_reason": "An issue has been detected in the routing settings. For instance, it could be due to a disabled project or bank",
  "request_id": "[YOUR_REFERENCE]",
  "reference": "",
  "status": "error",
  "timestamp": "2025-10-04T12:56:41.94Z",
  "description": "Flow ended without result"
}

Succesful transaction

{
  "type": "payment",
  "method": "qr_code",
  "mode": "initial",
  "currency": "COP",
  "amount": "5000",
  "challenge": {
    "challenge_type": "qr",
    "challenge_qr": {
      "code": "00020...",
      "image": "iVBOR..."
    }
  },
  "timestamp": "2024-09-21T20:13:28.1800002Z",
  "identifier": "QR_000000000",
  "reference": "postman-1790021606398",
  "request_id": "d9174008-f5b0-4703-93a0-189948e01234",
  "status": "pending",
  "error_code": 0,
  "error_reason": ""
}

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 params

{
  "error_code": 30,
  "error_reason": "Invalid params",
  "request_id": "36b61e02-fab7-4fb6-81b7-6e12f0acda16",
  "error_fields": [
    {
      "field": "reference",
      "message": "reference is a required field"
    }
  ],
  "timestamp": "2024-04-09T10:48:09Z"
}

Missing Authorization header

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

Invalid Authorization header format

{
  "error_code": 31,
  "error_reason": "Invalid authorization header format",
  "timestamp": "2025-10-26T16:03:00.00Z"
}

Invalid signature format

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

Unsupported algorithm

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

Invalid API key

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

Missing Date header

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

Invalid date format

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

Date is outdated or invalid

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

Missing Digest header

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

Invalid digest

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

Request timestamp has already been used

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

Invalid headers specification

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

Invalid signature

{
  "error_code": 31,
  "error_reason": "Invalid signature",
  "timestamp": "2025-10-26T16:13: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"
}

Missing required authentication headers

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

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: Success

{
  "billing_amount": "5000.00",
  "billing_currency": "COP",
  "fee_amount": "925.00",
  "fee_currency": "COP",
  "identifier": "QR_000000000",
  "creation_date": "2026-09-21T21:11:10.415Z",
  "request_id": "de2fc4ea-0b64-4ba4-b1f3-eb4394e158a1",
  "reference": "postman-1712345678",
  "method": "qr_code",
  "type": "payment",
  "mode": "initial",
  "status": "success",
  "status_date": "2026-09-21T21:11:30.059Z",
  "amount": "5000.00",
  "currency": "COP",
  "customer": {
    "identifier": "customer_1",
    "email": "carlos.mendez@example.com",
    "phone": "+573103195622",
    "first_name": "Carlos",
    "last_name": "Mendez",
    "itn": "98565020"
  },
  "error_code": 0,
  "error_reason": "",
  "timestamp": "2026-09-21T21:11:30.2055265Z"
}

Callback: Declined

{
  "billing_amount": "5000.00",
  "billing_currency": "COP",
  "fee_amount": "0.00",
  "fee_currency": "COP",
  "identifier": "QR_000000000",
  "creation_date": "2026-09-21T21:11:10.415Z",
  "request_id": "de2fc4ea-0b64-4ba4-b1f3-eb4394e158a1",
  "reference": "postman-1712345678",
  "method": "qr_code",
  "type": "payment",
  "mode": "initial",
  "status": "declined",
  "status_date": "2026-09-21T21:11:40.623Z",
  "amount": "5000.00",
  "currency": "COP",
  "customer": {
    "identifier": "customer_1",
    "email": "carlos.mendez@example.com",
    "phone": "+573103195622",
    "first_name": "Carlos",
    "last_name": "Mendez",
    "itn": "98565020"
  },
  "error_code": 0,
  "error_reason": "General bank decline",
  "timestamp": "2026-09-21T21:11:40.8543196Z"
}

Callback: Error

{
  "identifier": "QR_000000000",
  "creation_date": "2026-09-21T21:11:10.415Z",
  "request_id": "de2fc4ea-0b64-4ba4-b1f3-eb4394e158a1",
  "reference": "postman-1712345678",
  "method": "qr_code",
  "type": "payment",
  "mode": "initial",
  "status": "error",
  "status_date": "2026-09-21T21:12:05.848Z",
  "amount": "5000.00",
  "currency": "COP",
  "customer": {
    "identifier": "customer_1",
    "email": "carlos.mendez@example.com",
    "phone": "+573103195622",
    "first_name": "Carlos",
    "last_name": "Mendez",
    "itn": "98565020"
  },
  "error_code": 0,
  "error_reason": "General bank decline",
  "timestamp": "2026-09-21T21:12:05.9885293Z"
}

Callback: Expired

{
  "identifier": "QR_000000000",
  "creation_date": "2026-09-21T21:11:10.415Z",
  "request_id": "de2fc4ea-0b64-4ba4-b1f3-eb4394e158a1",
  "reference": "postman-1712345678",
  "method": "qr_code",
  "type": "payment",
  "mode": "initial",
  "status": "expired",
  "status_date": "2026-09-21T21:12:14.481Z",
  "amount": "5000.00",
  "currency": "COP",
  "customer": {
    "identifier": "customer_1",
    "email": "carlos.mendez@example.com",
    "phone": "+573103195622",
    "first_name": "Carlos",
    "last_name": "Mendez",
    "itn": "98565020"
  },
  "error_code": 105,
  "error_reason": "Transaction expired",
  "timestamp": "2026-09-21T21:12:14.6215071Z"
}

H2H#

How It Works#

Request Parameters#

Root Object#

Customer Object (customer)#

Extra / Metadata Object (extra)#

Colombian Document Types#

Responses#

Callback Examples#

Business Logic & Regional Requirements#

Final Status Reference#

Headers#

Request body#

Fields#

Responses#

Customer Object (`customer`)#

Extra / Metadata Object (`extra`)#