POST Preauthorize Transaction

curl --request POST 'https://tumipay-card-payments.staging.topup.com.co/production/api/v1/subscription/card/authorize' \
--header 'Token-Top: your_auth_token' \
--header 'Authorization: Basic your_auth_key' \
--header 'X-Merchant-ID: your_merchant_id' \
--header 'X-Request-ID: your-request-id' \
--header 'Content-Type: application/json' \
--data-raw '{
    "subscription_id": "sub_93af8f63-97d1-4be0-9e0d-f6fd8c2d92a0",
    "reference_id": "ref_2025_001",
    "currency": "COP",
    "amount": 400000,
    "tax": 0
}'

{
    "code": "AUTHORIZED",
    "status": true,
    "message": "Pago autorizado exitosamente",
    "data": {
        "transaction_id": "550e8400-e29b-41d4-a716-446655440000",
        "transaction_date": "2025-12-23T10:30:45Z",
        "transaction_status": "APPROVED",
        "transaction_type": "PRE_AUTH_TRANSACTION",
        "reference_id": "reference-uuid-123",
        "amount": 100.0,
        "currency": "COP"
    }
}

{
    "code": "VALIDATION_ERROR",
    "status": false,
    "message": "reference_id is required."
}

{
    "message": "Missing required header: X-Merchant-ID"
}

{
    "message": "Missing required header: X-Request-ID"
}

{
    "code": "UNAUTHORIZED",
    "status": false,
    "message": "Unauthorized."
}

{
    "code": "NOT_FOUND",
    "status": false,
    "message": "No se pudo localizar la suscripción solicitada con UUID: 550e8400-e29b-41d4-a716-446655440000"
}

{
    "code": "INVALID_STATE",
    "status": false,
    "message": "El pago no puede ser autorizado porque la suscripción no es válida."
}

{
    "code": "PAYMENT_AUTHORIZATION_FAILED",
    "status": false,
    "message": "La autorización de pago falló. Por favor, verifique la información proporcionada."
}

{
    "code": "SERVICE_ERROR",
    "status": false,
    "message": "Ocurrió un error. Por favor, intente nuevamente."
}

POST

api

subscription

card

authorize

curl --request POST 'https://tumipay-card-payments.staging.topup.com.co/production/api/v1/subscription/card/authorize' \
--header 'Token-Top: your_auth_token' \
--header 'Authorization: Basic your_auth_key' \
--header 'X-Merchant-ID: your_merchant_id' \
--header 'X-Request-ID: your-request-id' \
--header 'Content-Type: application/json' \
--data-raw '{
    "subscription_id": "sub_93af8f63-97d1-4be0-9e0d-f6fd8c2d92a0",
    "reference_id": "ref_2025_001",
    "currency": "COP",
    "amount": 400000,
    "tax": 0
}'

{
    "code": "AUTHORIZED",
    "status": true,
    "message": "Pago autorizado exitosamente",
    "data": {
        "transaction_id": "550e8400-e29b-41d4-a716-446655440000",
        "transaction_date": "2025-12-23T10:30:45Z",
        "transaction_status": "APPROVED",
        "transaction_type": "PRE_AUTH_TRANSACTION",
        "reference_id": "reference-uuid-123",
        "amount": 100.0,
        "currency": "COP"
    }
}

{
    "code": "VALIDATION_ERROR",
    "status": false,
    "message": "reference_id is required."
}

{
    "message": "Missing required header: X-Merchant-ID"
}

{
    "message": "Missing required header: X-Request-ID"
}

{
    "code": "UNAUTHORIZED",
    "status": false,
    "message": "Unauthorized."
}

{
    "code": "NOT_FOUND",
    "status": false,
    "message": "No se pudo localizar la suscripción solicitada con UUID: 550e8400-e29b-41d4-a716-446655440000"
}

{
    "code": "INVALID_STATE",
    "status": false,
    "message": "El pago no puede ser autorizado porque la suscripción no es válida."
}

{
    "code": "PAYMENT_AUTHORIZATION_FAILED",
    "status": false,
    "message": "La autorización de pago falló. Por favor, verifique la información proporcionada."
}

{
    "code": "SERVICE_ERROR",
    "status": false,
    "message": "Ocurrió un error. Por favor, intente nuevamente."
}

Preauthorize an amount for a subscription without making the actual charge to the card. Preauthorization reserves funds and verifies that the card has sufficient availability.

curl --request POST 'https://tumipay-card-payments.staging.topup.com.co/production/api/v1/subscription/card/authorize' \
--header 'Token-Top: your_auth_token' \
--header 'Authorization: Basic your_auth_key' \
--header 'X-Merchant-ID: your_merchant_id' \
--header 'X-Request-ID: your-request-id' \
--header 'Content-Type: application/json' \
--data-raw '{
    "subscription_id": "sub_93af8f63-97d1-4be0-9e0d-f6fd8c2d92a0",
    "reference_id": "ref_2025_001",
    "currency": "COP",
    "amount": 400000,
    "tax": 0
}'

{
    "code": "AUTHORIZED",
    "status": true,
    "message": "Pago autorizado exitosamente",
    "data": {
        "transaction_id": "550e8400-e29b-41d4-a716-446655440000",
        "transaction_date": "2025-12-23T10:30:45Z",
        "transaction_status": "APPROVED",
        "transaction_type": "PRE_AUTH_TRANSACTION",
        "reference_id": "reference-uuid-123",
        "amount": 100.0,
        "currency": "COP"
    }
}

{
    "code": "VALIDATION_ERROR",
    "status": false,
    "message": "reference_id is required."
}

{
    "message": "Missing required header: X-Merchant-ID"
}

{
    "message": "Missing required header: X-Request-ID"
}

{
    "code": "UNAUTHORIZED",
    "status": false,
    "message": "Unauthorized."
}

{
    "code": "NOT_FOUND",
    "status": false,
    "message": "No se pudo localizar la suscripción solicitada con UUID: 550e8400-e29b-41d4-a716-446655440000"
}

{
    "code": "INVALID_STATE",
    "status": false,
    "message": "El pago no puede ser autorizado porque la suscripción no es válida."
}

{
    "code": "PAYMENT_AUTHORIZATION_FAILED",
    "status": false,
    "message": "La autorización de pago falló. Por favor, verifique la información proporcionada."
}

{
    "code": "SERVICE_ERROR",
    "status": false,
    "message": "Ocurrió un error. Por favor, intente nuevamente."
}

Required Headers

string

required

Merchant authentication token

string

required

Basic authentication (Basic Auth)

string

required

Unique identifier of the merchant invoking Card Payment services

string

required

Unique tracking identifier for the request

string

required

Must be “application/json”

Request Body Parameters

string

required

Identifier of the subscription for which the payment is preauthorized

string

Unique transaction identifier provided by the client. If not provided, the system generates one automatically.

string

required

Currency code for transaction processing (e.g., “COP”, “PEN”, “USD”)

number

required

Amount to preauthorize. Must be a positive value.

number

required

Processing tax associated with the transaction. If no tax will be charged, send 0.

Validation Rules

Required Fields

Field	Type	Rules	Description
`subscription_id`	string	required, max:36	Subscription UUID
`reference_id`	string	required, max:36	Unique payment reference identifier
`currency`	string	required, max:3	ISO 4217 currency code
`amount`	numeric	required, min:0	Payment amount (must be greater than or equal to 0)
`tax`	numeric	required, min:0	Payment tax (must be greater than or equal to 0)

Allowed Values

currency

COP - Colombian Peso

Common Validation Error Messages

The following are common validation error messages returned by the API (in Spanish):

:attribute es obligatorio. - Required field missing
:attribute debe ser una cadena de texto. - Invalid data type (expected string)
:attribute debe ser un número. - Invalid data type (expected numeric)
:attribute no puede tener más de :max caracteres. - Maximum length exceeded
:attribute debe ser mayor o igual a :min. - Minimum value not met
:attribute no es válido. - Invalid value

Response Fields

Success Response (200 OK)

string

required

Response code. Value: "AUTHORIZED" when authorization is successful

boolean

required

Operation status. true when successful, false when there is an error

string

required

Descriptive message about the authorization result

object

required

Show Transaction data

string

required

Unique identifier of the created preauthorization transaction. This ID will be used to capture the transaction later.

string

required

Transaction processing date and time in ISO 8601 format with UTC timezone (format: Y-m-d\TH:i:s\Z)

string

required

Transaction status. Value: "APPROVED" when authorization is successful

string

required

Transaction type. Value: "PRE_AUTH_TRANSACTION" for preauthorization transactions

string

Transaction identifier provided by the client

number

required

Preauthorized amount

string

required

Transaction currency code (e.g., “COP”)

HTTP Status Codes

Status Code	Description	Response Body
`200 OK`	Successful authorization	`status: true`, `code: "AUTHORIZED"`
`400 Bad Request`	Missing required header (`X-Merchant-ID` or `X-Request-ID`)	Simple error message
`401 Unauthorized`	Authentication failed (invalid `Token-Top` or `Authorization`)	`code: "UNAUTHORIZED"`
`404 Not Found`	Subscription not found	`code: "NOT_FOUND"`
`422 Unprocessable Entity`	Validation error, invalid subscription state, or provider authorization failure	`code: "VALIDATION_ERROR"`, `"INVALID_STATE"` or `"PAYMENT_AUTHORIZATION_FAILED"`
`500 Internal Server Error`	Internal server error	`code: "SERVICE_ERROR"`

Response Codes

Code	Description
`AUTHORIZED`	Successful authorization
`VALIDATION_ERROR`	Validation error in sent data (missing fields, incorrect types, invalid currency, etc.)
`UNAUTHORIZED`	Authentication error
`NOT_FOUND`	Subscription not found
`INVALID_STATE`	The subscription is not in `ACTIVE` state (cannot authorize payments)
`PAYMENT_AUTHORIZATION_FAILED`	Authorization failed at the payment provider
`SERVICE_ERROR`	Internal server error

Transaction Types

Pre-Authorization (PRE_AUTH_TRANSACTION)

Type: PRE_AUTH_TRANSACTION
Status: APPROVED (success) or DECLINED/ERROR (failure)
Purpose: Reserve funds without capturing them
Next Step: Requires an additional capture step to charge the funds

Supported Currencies

The currency field must be one of the allowed values according to the Currency enum. Example:

COP: Colombian Peso

Headers

X-Merchant-ID

string

required

Unique identifier of the Merchant invoking Card Payment services. Should not be used to authenticate end users.

X-Request-ID

string

required

Tracking identifier associated with the request, used to establish a correlation_id between ecosystem components.

Token-Top

string

required

Token for authentication.

Authorization

string

required

Basic authentication.

Body

application/json

reference_id

string<uuid>

required

Example:

"ORDER-123456"

subscription_id

string<uuid>

required

Example:

"550e8400-e29b-41d4-a716-446655440000"

currency

string

required

Example:

"COP"

amount

number

required

Required range: x >= 0

Example:

1500

tax

number

required

Required range: x >= 0

Example:

0

Response

Successful authorization. A new transaction of type PRE_AUTH_TRANSACTION is created.

Preauthorization response. Creates a new transaction of type PRE_AUTH_TRANSACTION.

code

string

required

Response code. Value: 'AUTHORIZED' when authorization is successful

Example:

"AUTHORIZED"

status

boolean

required

Operation status. true when successful, false when there is an error

Example:

true

message

string

required

Descriptive message about the authorization result

Example:

"Pago autorizado exitosamente"

data

object

required

Show child attributes

Getting Started

Merchant API

PayIn API

PayOut API

Card Payment API

Integration

POST Preauthorize Transaction

Required Headers

Request Body Parameters

Validation Rules

Required Fields

Allowed Values

currency

Common Validation Error Messages

Response Fields

Success Response (200 OK)

HTTP Status Codes

Response Codes

Transaction Types

Pre-Authorization (PRE_AUTH_TRANSACTION)

Supported Currencies

Headers

Body

Response

​Required Headers

​Request Body Parameters

​Validation Rules

​Required Fields

​Allowed Values

​currency

​Common Validation Error Messages

​Response Fields

​Success Response (200 OK)

​HTTP Status Codes

​Response Codes

​Transaction Types

​Pre-Authorization (PRE_AUTH_TRANSACTION)

​Supported Currencies

Headers

Body

Response

Required Headers

Request Body Parameters

Validation Rules

Required Fields

Allowed Values

currency

Common Validation Error Messages

Response Fields

Success Response (200 OK)

HTTP Status Codes

Response Codes

Transaction Types

Pre-Authorization (PRE_AUTH_TRANSACTION)

Supported Currencies