Payment / Alternative payment methods / Colombia / PSE

HPP#

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

Initiate a Colombian PSE (Pagos Seguros en Línea) bank transfer payment using the Hosted Payment Page (HPP) integration. The customer is redirected to an ApiPro-hosted page where they authenticate with their online banking credentials and authorize the transfer through the PSE portal.

How It Works#

Send a request to create a payment intention with widget.method set to "bank_transfer_colombia", including the customer's document type and bank code in extra.meta.

⚠️ Important: This method is specifically PSE, not a direct bank transfer. On your side, the customer must be shown the PSE button/option.

The customer selects their bank from a dropdown within the PSE flow, and you must pass the corresponding bank code as extra.meta.bankCode (see the bank codes list) matching the bank the customer selected.
Receive a redirect_url in the response.
Redirect the customer to that URL — they will see the ApiPro-hosted page for PSE bank transfer authorization.
The customer authenticates and authorizes the transfer through the PSE portal, using the bank selected in step 1.
After the customer completes (or cancels) payment, they are returned to your redirect_url or cancel_url.
Receive a callback at your callback_url with the final transaction status.

ℹ️ Note: You can implement this in one of two ways on your side: either display a single PSE button, and let the customer choose their bank on the next screen; or display individual bank buttons directly and map each one to the corresponding bankCode. Either way, the bank selected by the customer must be passed as extra.meta.bankCode in the request — this is required for the transaction to route correctly.

Request Parameters#

Root Object#

Parameter	Type	Required	Description
`reference`	string	Yes	Unique merchant order reference (1–40 characters). Must match `[a-z0-9-_]+`.
`currency`	string	Yes	Must be `"COP"` (Colombian Peso).
`amount`	integer	Yes	Transaction amount in COP (e.g., `30000` = 30,000 COP).
`description`	string	Yes	Description of the payment/order.
`customer`	object	Yes	Customer details object (see below).
`widget`	object	Yes	Widget configuration object (see below).
`redirect_url`	string	Yes	URL to redirect the customer after payment completion.
`cancel_url`	string	Yes	URL to redirect the customer if they cancel.
`callback_url`	string	Yes	Server-to-server notification URL for async status updates.
`extra`	object	Yes	Additional metadata for Colombia-specific fields (see below).

Customer Object (`customer`)#

Parameter	Type	Required	Description
`customer.identifier`	string	Yes	Unique customer ID in your merchant system.
`customer.email`	string	Yes	Customer's email address.
`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 — 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`.

Widget Object (`widget`)#

Parameter	Type	Required	Description
`widget.method`	string	Yes	Must be `"bank_transfer_colombia"` (snake_case / lower case only).

Extra / Metadata Object (`extra`)#

Parameter	Type	Required	Description
`extra.meta`	object	Yes	Colombia-specific routing metadata.
`extra.meta.bankCode`	string	Yes	The numeric code of the customer's Colombian bank (e.g., `"1001"`).
`extra.meta.documentType`	string	Yes	The type of the customer's identification document (see Document Types table below).

Colombian Document Types (`documentType`)#

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`.

Colombian Bank Codes (`bankCode`)#

Code	Bank Name
`1001`	BANCO DE BOGOTA
`1002`	BANCO POPULAR
`1006`	ITAU
`1007`	BANCOLOMBIA
`1009`	CITIBANK
`1012`	BANCO GNB SUDAMERIS
`1013`	BBVA COLOMBIA
`1019`	SCOTIABANK COLPATRIA S.A
`1023`	BANCO DE OCCIDENTE
`1032`	BANCO CAJA SOCIAL BCSC SA
`1040`	BANCO AGRARIO
`1047`	BANCO MUNDO MUJER
`1051`	BANCO DAVIVIENDA SA
`1052`	BANCO AV VILLAS
`1053`	BANCO W
`1059`	BANCO DE LAS MICROFINANZAS - BANCAMIA S.A.
`1060`	BANCO PICHINCHA
`1061`	BANCOOMEVA
`1062`	BANCO FALABELLA S.A.
`1063`	BANCO FINANDINA S.A.
`1065`	BANCO SANTANDER DE NEGOCIOS COLOMBIA S.A
`1066`	BANCO COOPERATIVO COOPCENTRAL
`1067`	MIBANCO S.A.
`1069`	BANCO SERFINANZA S.A
`1070`	LULO BANK S.A.
`1071`	BANCO J.P. MORGAN COLOMBIA S.A.
`1097`	Dale
`1121`	FINANCIERA JURISCOOP S.A. COMPAÑIA DE FINANCIAMIENTO
`1283`	COOPERATIVA FINANCIERA DE ANTIOQUIA
`1286`	JFK COOPERATIVA FINANCIERA
`1289`	COOTRAFA COOPERATIVA FINANCIERA
`1292`	CONFIAR COOPERATIVA FINANCIERA
`1303`	BANCO UNION S.A
`1370`	COLTEFINANCIERA S.A
`1507`	NEQUI
`1551`	DAVIPLATA
`1558`	BAN100 S.A
`1637`	IRIS
`1801`	MOVII
`1802`	DING TECNIPAGOS SA
`1803`	POWWI
`1804`	UALA
`1805`	BANCO BTG PACTUAL
`1808`	BOLD CF
`1809`	NU COLOMBIA
`1811`	RAPPIPAY
`1812`	COINK
`1814`	GLOBAL66
`1815`	Alianza fiduciaria
`1816`	Crezcamos

Responses#

Status	When
`200 OK`	A successful request returns a `redirect_url` where the customer must be sent to complete the PSE bank transfer. 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`	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 (success, declined, error, expired). Examples for each final status are in the Callback tab. Always validate the callback signature to avoid suspicious activity.

Business Logic & Regional Requirements#

Currency Locking: Only "COP" (Colombian Peso) is supported. Requests with other currencies will be rejected.
PSE Network: Colombian bank transfers are processed through the PSE (Pagos Seguros en Línea) network, Colombia's standard interbank payment system.
Document Type Mandatory: The extra.meta.documentType field is required and must be a valid Colombian document type prefix (CO_CC, CO_CE, CO_NIT).
Bank Code Mandatory: The extra.meta.bankCode field is required — it identifies the customer's bank within the PSE network (e.g., "1001").
ITN (Identification Number): The customer.itn field must contain the numeric value of the customer's identification document.
Signature Validation: Always validate the callback signature before processing.
504 Gateway Timeout: If a timeout occurs, the request can be safely retried.

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-1712345678", // required, unique, 1-40 characters, [a-z0-9-_]+
    "currency": "COP", // required, only COP is supported
    "amount": 30000, // required, amount in COP
    "description": "Payment for Roxana", // required
    "customer": { // required
        "identifier": "customer_1", // required, unique customer ID in your merchant system
        "email": "rrecamango@gmail.com", // required
        "first_name": "Roxana", // required
        "last_name": "Recaman", // required
        "itn": "1045726853" // 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
    },
    "widget": { // required
        "method": "bank_transfer_colombia" // required, snake_case / lower case only: "bank_transfer_colombia" (not "BANK_TRANSFER_COLOMBIA" or "BankTransferColombia")
    },
    "redirect_url": "https://merchant.shop.com/", // required
    "cancel_url": "https://merchant.shop.com/cancel", // required
    "callback_url": "https://merchant.shop.com/success", // required
    "extra": { // required
        "meta": { // required
            "bankCode": "1001", // required, code of the bank selected by the customer (see Colombian Bank Codes)
            "documentType": "CO_CC" // required, CO_CC, CO_CE or CO_NIT (see Colombian Document Types)
        }
    }
}

Fields#

Field	Type	Requirement / note
`reference`	string	required, unique, 1-40 characters, [a-z0-9-_]+
`currency`	string	required, only COP is supported
`amount`	integer	required, amount in COP
`description`	string	required
`customer`	object	required
`customer.identifier`	string	required, unique customer ID in your merchant system
`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); numeric value of the document matching extra.meta.documentType
`widget`	object	required
`widget.method`	string	required, snake_case / lower case only: "bank_transfer_colombia" (not "BANK_TRANSFER_COLOMBIA" or "BankTransferColombia")
`redirect_url`	string	required
`cancel_url`	string	required
`callback_url`	string	required
`extra`	object	required
`extra.meta`	object	required
`extra.meta.bankCode`	string	required, code of the bank selected by the customer (see Colombian Bank Codes)
`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": "BAN000000000",
  "reference": "postman-1000000000",
  "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": "2024-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

{
  "error_code": 0,
  "reference": "postman-1712345678",
  "request_id": "de2fc4ea-0b64-4ba4-b1f3-eb4394e158a1",
  "status": "success",
  "amount": "30000",
  "currency": "COP",
  "billing_amount": "30000",
  "billing_currency": "COP",
  "fee_amount": "4500",
  "fee_currency": "COP",
  "payment": {
    "error_code": 0,
    "identifier": "BAN000000000",
    "request_id": "de2fc4ea-0b64-4ba4-b1f3-eb4394e122a2",
    "reference": "postman-1712345678",
    "method": "bank_transfer_colombia",
    "type": "payment",
    "mode": "initial",
    "status": "success",
    "status_date": "2024-02-09T13:12:18.395695",
    "customer": {
      "identifier": "customer_1",
      "email": "rrecamango@gmail.com",
      "first_name": "Roxana",
      "last_name": "Recaman",
      "itn": "1045726853"
    },
    "creation_date": "2024-09-15T07:54:00.503Z"
  }
}

Callback: Declined

{
  "error_code": 0,
  "error_reason": "General bank decline",
  "reference": "postman-1789460165296",
  "request_id": "fe17a0d6-f6af-4f21-9569-839d90c98242",
  "status": "declined",
  "amount": "5000.00",
  "currency": "COP",
  "payment": {
    "error_code": 0,
    "error_reason": "General bank decline",
    "identifier": "BAN014213401",
    "request_id": "fe17a0d6-f6af-4f21-9569-839d90c98242",
    "reference": "postman-1789460165296",
    "method": "bank_transfer_colombia",
    "type": "payment",
    "mode": "initial",
    "status": "declined",
    "status_date": "2024-09-15T08:16:35.76Z",
    "customer": {
      "identifier": "487143444-1789460165296",
      "email": "rrecamango@gmail.com",
      "first_name": "Roxana",
      "last_name": "Recaman",
      "itn": "1045726853"
    },
    "creation_date": "2024-09-15T08:16:06.084Z"
  }
}

Callback: Error

{
  "error_code": 200,
  "error_reason": "Transaction processing error",
  "reference": "postman-1789460165296",
  "request_id": "fe17a0d6-f6af-4f21-9569-839d90c98242",
  "status": "error",
  "amount": "5000.00",
  "currency": "COP",
  "payment": {
    "error_code": 200,
    "error_reason": "Transaction processing error",
    "identifier": "BAN014213401",
    "request_id": "fe17a0d6-f6af-4f21-9569-839d90c98242",
    "reference": "postman-1789460165296",
    "method": "bank_transfer_colombia",
    "type": "payment",
    "mode": "initial",
    "status": "error",
    "status_date": "2024-09-15T08:59:31.436Z",
    "customer": {
      "identifier": "487143444-1789460165296",
      "email": "rrecamango@gmail.com",
      "first_name": "Roxana",
      "last_name": "Recaman",
      "itn": "1045726853"
    },
    "creation_date": "2024-09-15T08:16:06.084Z"
  }
}

Callback: Expired (Transaction)

{
  "error_code": 105,
  "error_reason": "Transaction expired",
  "reference": "postman-1789460165296",
  "request_id": "fe17a0d6-f6af-4f21-9569-839d90c98242",
  "status": "expired",
  "amount": "5000.00",
  "currency": "COP",
  "payment": {
    "error_code": 105,
    "error_reason": "Transaction expired",
    "identifier": "BAN014213401",
    "request_id": "fe17a0d6-f6af-4f21-9569-839d90c98242",
    "reference": "postman-1789460165296",
    "method": "bank_transfer_colombia",
    "type": "payment",
    "mode": "initial",
    "status": "expired",
    "status_date": "2024-09-15T09:01:32.52Z",
    "customer": {
      "identifier": "487143444-1789460165296",
      "email": "rrecamango@gmail.com",
      "first_name": "Roxana",
      "last_name": "Recaman",
      "itn": "1045726853"
    },
    "creation_date": "2024-09-15T08:16:06.084Z"
  }
}

Callback: Expired (Payment Intention)

{
  "reference": "postman-1712345678",
  "request_id": "de2fc4ea-0b64-4ba4-b1f3-eb4394e158a1",
  "status": "expired",
  "currency": "COP",
  "amount": "30000",
  "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 (documentType)#

Colombian Bank Codes (bankCode)#

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

Colombian Document Types (`documentType`)#

Colombian Bank Codes (`bankCode`)#