Payment / Alternative payment methods / Colombia / Bre-B

HPP#

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

Initiate a Bre-B QR code payment in Colombia using the Hosted Payment Page (HPP) integration. Send a payment request with widget.method: "qr_code" and receive a redirect_url at the top level of the response. Redirect the customer's browser there; they authorize the payment inside their banking app or e-wallet, and you receive a final status via callback_url.

How It Works#

Send a request to POST https://payments.apipro.io/v2/payment with widget.method: "qr_code", currency: "COP", and customer details, including itn and extra.meta.documentType.
Check error_code — 0 means the request was accepted.
Check status — on acceptance it is "new".
Read redirect_url directly from the top level of the response.
Redirect the customer's browser to that URL. They log in to their banking app or e-wallet and authorize the transaction there.
Receive a callback at your callback_url once the payment reaches a terminal status (success, declined, error, or expired).

Request Parameters#

Root Object#

Parameter	Type	Required	Description
`widget.method`	`string`	Yes	Must be `"qr_code"` (snake_case only).
`reference`	`string`	Yes	Unique merchant order ID.
`currency`	`string`	Yes	Must be `"COP"`.
`amount`	`integer`	Yes	Transaction amount in COP.
`redirect_url`	`string`	Conditional	URL to redirect the customer after payment completion.
`callback_url`	`string`	Conditional	Server-to-server notification URL for async status updates.
`cancel_url`	`string`	Conditional	URL to redirect the customer if they cancel.
`extra`	`object`	Yes	Additional metadata for transaction routing.

Customer Object (`customer`)#

Parameter	Type	Required	Description
`customer.identifier`	`string`	Yes	Unique customer ID in your system.
`customer.email`	`string`	Yes	Customer's email address.
`customer.phone`	`string`	Yes	Customer's phone number (Colombian format, e.g., +573103195622).
`customer.first_name`	`string`	Yes	Customer's first name.
`customer.last_name`	`string`	Yes	Customer's last name.
`customer.itn`	`string`	Yes	Colombian identification number (CC / CE / NIT).

Widget Object (`widget`)#

Parameter	Type	Required	Description
`widget.method`	`string`	Yes	Must be `"qr_code"`.
`widget.locale`	`string`	No	Language for the hosted payment page (e.g., `"es"`, `"en"`). Defaults to `"en"`.

Extra / Metadata Object (`extra`)#

Parameter	Type	Required	Description
`extra.meta.documentType`	`string`	Yes	Document type — see Colombian Document Types table.

Colombian Document Types#

Code	Description	Format (used in `customer.itn`)
`CO_CC`	Cédula de Ciudadanía (citizens 18+)	6–10 digits, no separators, e.g. `1020304050`
`CO_CE`	Cédula de Extranjería (foreign residents)	6–10 digits, no separators, e.g. `1020304050`
`CO_NIT`	NIT (legal entities / self-employed)	`XXXXXXXXX-X`, e.g. `900123456-7`

Responses#

Status	When
`200 OK`	A successful request returns a `redirect_url` where the customer must be sent to view and scan the QR code. See Succesful transaction in the Responses tab.
`400 Bad Request`	Returned when required fields are missing or validation fails. See Invalid fields (validation failed) in the Responses tab.
`504 Gateway Timeout`	A 504 Gateway Timeout may occur after 30 seconds. You can safely retry the request.

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, Expired (Payment Intention)) are in the Callback tab.

Business Logic & Regional Requirements#

Currency Locking: Only "COP" (Colombian Peso) is supported.
Method Code: "qr_code" — snake_case only.
Document Number (ITN): Required; must match CC / CE / NIT format per Colombian Document Types table.
Redirect Handling: redirect_url is returned at the top level of the initial response.

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.

{
    "reference": "postman-{{time}}", // required, unique
    "currency": "COP", // required, only COP is supported
    "amount": 5000, // required, amount in COP
    "customer": { // required
        "identifier": "postman-{{time}}", // required, unique customer ID in your merchant system
        "phone": "+573103195622", // required, Colombian format
        "email": "carlos.mendez@example.com", // required
        "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)
    },
    "widget": { // required
        "method": "qr_code", // required, snake_case / lower case only: "qr_code" (not "QR_CODE" or "QrCode")
        "locale": "es" // optional, language of the hosted payment page ("es", "en"), defaults to "en"
    },
    "redirect_url": "https://merchant.shop.com/", // conditional
    "cancel_url": "https://merchant.shop.com/cancel", // conditional
    "callback_url": "https://merchant.shop.com/success", // conditional
    "extra": { // required
        "meta": { // required
            "documentType": "CO_CC" // required, CO_CC, CO_CE or CO_NIT (see Colombian Document Types)
        }
    }
}

Fields#

Field	Type	Requirement / note
`reference`	string	required, unique
`currency`	string	required, only COP is supported
`amount`	integer	required, amount in COP
`customer`	object	required
`customer.identifier`	string	required, unique customer ID in your merchant system
`customer.phone`	string	required, Colombian format
`customer.email`	string	required
`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)
`widget`	object	required
`widget.method`	string	required, snake_case / lower case only: "qr_code" (not "QR_CODE" or "QrCode")
`widget.locale`	string	optional, language of the hosted payment page ("es", "en"), defaults to "en"
`redirect_url`	string	conditional
`cancel_url`	string	conditional
`callback_url`	string	conditional
`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",
  "description": "Failed to register the transaction",
  "request_id": "YOUR_REFERENCE",
  "status": "error",
  "timestamp": "2025-10-26T14:17:00.00Z"
}

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

{
  "error_code": 0,
  "identifier": "HPI0000000046GPX",
  "reference": "hpp-payment-202306221129",
  "request_id": "c17a96fd-d5ba-46fd-afd9-1c26d084ac89",
  "status": "new",
  "redirect_url": "https://..."
}

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 fields (validation failed)

{
  "request_id": "e76789fa-cb93-4643-9506-0314c8f82450",
  "error_code": 1,
  "error_reason": "Invalid fields: \nreference - must match \"[a-z0-9-_]+\";\n reference - size must be between 1 and 40",
  "timestamp": "2022-02-09T17:32:46.131339",
  "error_fields": {
    "reference": "must match \"[a-z0-9-_]+\"; size must be between 1 and 40"
  }
}

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_015090285",
  "creation_date": "2026-09-21T21:11:10.415Z",
  "request_id": "651dc70c-1e77-4f9d-8611-c0c40f9e2d77",
  "reference": "postman-1790025070793",
  "method": "qr_code",
  "type": "payment",
  "mode": "initial",
  "status": "success",
  "status_date": "2026-09-21T21:11:30.059Z",
  "amount": "5000.00",
  "currency": "COP",
  "customer": {
    "identifier": "postman-1790025070793",
    "email": "carlos.mendez@example.com",
    "phone": "+573103195622",
    "first_name": "Carlos",
    "last_name": "Mendez",
    "itn": "1130628333"
  },
  "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_015090285",
  "creation_date": "2026-09-21T21:11:10.415Z",
  "request_id": "651dc70c-1e77-4f9d-8611-c0c40f9e2d77",
  "reference": "postman-1790025070793",
  "method": "qr_code",
  "type": "payment",
  "mode": "initial",
  "status": "declined",
  "status_date": "2026-09-21T21:11:40.623Z",
  "amount": "5000.00",
  "currency": "COP",
  "customer": {
    "identifier": "postman-1790025070793",
    "email": "carlos.mendez@example.com",
    "phone": "+573103195622",
    "first_name": "Carlos",
    "last_name": "Mendez",
    "itn": "1130628333"
  },
  "error_code": 0,
  "error_reason": "General bank decline",
  "timestamp": "2026-09-21T21:11:40.8543196Z"
}

Callback: Error

{
  "identifier": "QR_015090285",
  "creation_date": "2026-09-21T21:11:10.415Z",
  "request_id": "651dc70c-1e77-4f9d-8611-c0c40f9e2d77",
  "reference": "postman-1790025070793",
  "method": "qr_code",
  "type": "payment",
  "mode": "initial",
  "status": "error",
  "status_date": "2026-09-21T21:12:05.848Z",
  "amount": "5000.00",
  "currency": "COP",
  "customer": {
    "identifier": "postman-1790025070793",
    "email": "carlos.mendez@example.com",
    "phone": "+573103195622",
    "first_name": "Carlos",
    "last_name": "Mendez",
    "itn": "1130628333"
  },
  "error_code": 0,
  "error_reason": "General bank decline",
  "timestamp": "2026-09-21T21:12:05.9885293Z"
}

Callback: Expired

{
  "identifier": "QR_015090285",
  "creation_date": "2026-09-21T21:11:10.415Z",
  "request_id": "651dc70c-1e77-4f9d-8611-c0c40f9e2d77",
  "reference": "postman-1790025070793",
  "method": "qr_code",
  "type": "payment",
  "mode": "initial",
  "status": "expired",
  "status_date": "2026-09-21T21:12:14.481Z",
  "amount": "5000.00",
  "currency": "COP",
  "customer": {
    "identifier": "postman-1790025070793",
    "email": "carlos.mendez@example.com",
    "phone": "+573103195622",
    "first_name": "Carlos",
    "last_name": "Mendez",
    "itn": "1130628333"
  },
  "error_code": 105,
  "error_reason": "Transaction expired",
  "timestamp": "2026-09-21T21:12:14.6215071Z"
}

Callback: Expired (Payment Intention)

{
  "reference": "order-00001",
  "request_id": "de2fc4ea-0b64-4ba4-b1f3-eb4394e158a1",
  "status": "expired",
  "currency": "COP",
  "amount": "5466",
  "error_code": 620,
  "error_reason": "Payment intention expired"
}

HPP#

How It Works#

Request Parameters#

Root Object#

Customer Object (customer)#

Widget Object (widget)#

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`)#

Widget Object (`widget`)#

Extra / Metadata Object (`extra`)#