Payment / Alternative payment methods / Colombia / Cash

HPP#

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

Initiate cash payments in Colombia using the Hosted Payment Page (HPP) integration. The response contains a redirect_url to an ApiPro-hosted page where the customer receives a payment voucher with a barcode and payment reference. The customer then completes the payment using the voucher, following the instructions on the page.

How It Works#

Send a request to create a payment with widget.method set to "cash_colombia" and currency set to "COP".
Check error_code in the response. If it is not 0, the transaction has failed. Otherwise, the transaction is created with status: "new".
Redirect the customer to the redirect_url from the response. The customer sees an ApiPro-hosted page with the payment voucher.
The customer completes the payment using the barcode or payment reference from the voucher.
The customer is returned to your redirect_url, cancel_url or error_url (optional request parameters), depending on the outcome.
Receive a callback at your callback_url when the payment reaches a terminal state.

Request Parameters#

Root Object#

Parameter	Type	Required	Description
`widget.method`	`string`	Yes	Must be `"cash_colombia"`
`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 `"cash_colombia"`.
`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 generate a cash payment voucher. 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: Only "COP" (Colombian Peso) is supported — currency must be "COP".
Method: widget.method must be "cash_colombia" — snake_case / lower case only. Do not use camelCase, PascalCase or UPPER CASE ("cashColombia", "CashColombia", "CASH_COLOMBIA"): the value will not be recognized and the payment method will be rejected.
Reference: reference must be unique for each payment.
Customer Data: customer.identifier, customer.email, customer.phone, customer.first_name, customer.last_name and customer.itn are required.
Document Type: Pass the type of the customer's document in extra.meta.documentType (e.g. "CO_CC" for Cédula de Ciudadanía); customer.itn must contain the number of that document.
Initial Response: A successful request returns error_code: 0 and status: "new". The payment page URL is returned in the root redirect_url field of the response.
Return URLs: redirect_url, cancel_url and error_url in the request are optional and define where the customer is returned after leaving the payment page. They are different from the redirect_url in the response, which is the payment page itself.
Final Status: The transaction result is delivered via callback to callback_url when the payment reaches a terminal state.
Signature Validation: Always validate the callback signature before processing.

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, 1-40 characters, [a-z0-9-_]+
    "currency": "COP", // required, only COP is supported
    "amount": 15000, // required
    "customer": { // required
        "identifier": "postman-{{time}}", // required
        "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); must match extra.meta.documentType
    },
    "widget": { // required
        "method": "cash_colombia", // required, snake_case / lower case only: "cash_colombia" (not "CASH_COLOMBIA" or "CashColombia")
        "locale": "es" // optional, language of the hosted payment page ("es", "en"), defaults to "en"
    },
    "redirect_url": "https://merchant.shop.com/", // conditional
    "callback_url": "https://merchant.shop.com/success", // conditional
    "cancel_url": "https://merchant.shop.com/cancel", // 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, 1-40 characters, [a-z0-9-_]+
`currency`	string	required, only COP is supported
`amount`	integer	required
`customer`	object	required
`customer.identifier`	string	required
`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); must match extra.meta.documentType
`widget`	object	required
`widget.method`	string	required, snake_case / lower case only: "cash_colombia" (not "CASH_COLOMBIA" or "CashColombia")
`widget.locale`	string	optional, language of the hosted payment page ("es", "en"), defaults to "en"
`redirect_url`	string	conditional
`callback_url`	string	conditional
`cancel_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"
}

Duplicated reference

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

Succesful transaction

{
  "identifier": "CAS015162655",
  "reference": "postman-1790171328619",
  "request_id": "098ce1d0-5a04-4a1a-9cdc-f08842d6ec8c",
  "status": "new",
  "redirect_url": "https://checkout.apipro.io/payment/...",
  "error_code": 0
}

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

{
  "billing_amount": "15000.00",
  "billing_currency": "COP",
  "fee_amount": "1275.00",
  "fee_currency": "COP",
  "error_code": 0,
  "reference": "postman-1790172482006",
  "request_id": "4c85b279-8015-48d7-b83c-aa5f734e1d9b",
  "status": "success",
  "amount": "15000.00",
  "currency": "COP",
  "payment": {
    "error_code": 0,
    "identifier": "CAS015163173",
    "request_id": "4c85b279-8015-48d7-b83c-aa5f734e1d9b",
    "reference": "postman-1790172482006",
    "method": "cash_colombia",
    "type": "payment",
    "mode": "initial",
    "status": "success",
    "status_date": "2026-09-23T14:08:23.606Z",
    "customer": {
      "identifier": "postman-1790172482006",
      "email": "carlos.mendez@example.com",
      "phone": "+573103195622",
      "first_name": "Carlos",
      "last_name": "Mendez",
      "itn": "1130628333"
    },
    "creation_date": "2026-09-23T14:08:02.494Z"
  }
}

Callback: Declined

{
  "error_code": 0,
  "error_reason": "General bank decline",
  "reference": "postman-1790172482006",
  "request_id": "4c85b279-8015-48d7-b83c-aa5f734e1d9b",
  "status": "declined",
  "amount": "15000.00",
  "currency": "COP",
  "payment": {
    "error_code": 0,
    "error_reason": "General bank decline",
    "identifier": "CAS015163173",
    "request_id": "4c85b279-8015-48d7-b83c-aa5f734e1d9b",
    "reference": "postman-1790172482006",
    "method": "cash_colombia",
    "type": "payment",
    "mode": "initial",
    "status": "declined",
    "status_date": "2026-09-23T14:08:28.731Z",
    "customer": {
      "identifier": "postman-1790172482006",
      "email": "carlos.mendez@example.com",
      "phone": "+573103195622",
      "first_name": "Carlos",
      "last_name": "Mendez",
      "itn": "1130628333"
    },
    "creation_date": "2026-09-23T14:08:02.494Z"
  }
}

Callback: Error

{
  "error_code": 0,
  "error_reason": "General bank decline",
  "reference": "postman-1790172482006",
  "request_id": "4c85b279-8015-48d7-b83c-aa5f734e1d9b",
  "status": "error",
  "amount": "15000.00",
  "currency": "COP",
  "payment": {
    "error_code": 0,
    "error_reason": "General bank decline",
    "identifier": "CAS015163173",
    "request_id": "4c85b279-8015-48d7-b83c-aa5f734e1d9b",
    "reference": "postman-1790172482006",
    "method": "cash_colombia",
    "type": "payment",
    "mode": "initial",
    "status": "error",
    "status_date": "2026-09-23T14:08:33.091Z",
    "customer": {
      "identifier": "postman-1790172482006",
      "email": "carlos.mendez@example.com",
      "phone": "+573103195622",
      "first_name": "Carlos",
      "last_name": "Mendez",
      "itn": "1130628333"
    },
    "creation_date": "2026-09-23T14:08:02.494Z"
  }
}

Callback: Expired

{
  "error_code": 105,
  "error_reason": "Transaction expired",
  "reference": "postman-1790172482006",
  "request_id": "4c85b279-8015-48d7-b83c-aa5f734e1d9b",
  "status": "expired",
  "amount": "15000.00",
  "currency": "COP",
  "payment": {
    "error_code": 105,
    "error_reason": "Transaction expired",
    "identifier": "CAS015163173",
    "request_id": "4c85b279-8015-48d7-b83c-aa5f734e1d9b",
    "reference": "postman-1790172482006",
    "method": "cash_colombia",
    "type": "payment",
    "mode": "initial",
    "status": "expired",
    "status_date": "2026-09-23T14:08:37.675Z",
    "customer": {
      "identifier": "postman-1790172482006",
      "email": "carlos.mendez@example.com",
      "phone": "+573103195622",
      "first_name": "Carlos",
      "last_name": "Mendez",
      "itn": "1130628333"
    },
    "creation_date": "2026-09-23T14:08:02.494Z"
  }
}

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