POST Preauthorize Transaction

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

Required Headers

Token-Top

string

required

Merchant authentication token

Authorization

string

required

Basic authentication (Basic Auth)

X-Merchant-ID

string

required

Unique identifier of the merchant invoking Card Payment services

X-Request-ID

string

required

Unique tracking identifier for the request

Content-Type

string

required

Must be “application/json”

Request Body Parameters

subscription_id

string

required

Identifier of the subscription for which the payment is preauthorized

reference_id

string

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

currency

string

required

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

amount

number

required

Amount to preauthorize. Must be a positive value.

tax

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)

code

string

required

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

status

boolean

required

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

message

string

required

Descriptive message about the authorization result

data

object

required

Show Transaction data

transaction_id

string

required

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

transaction_date

string

required

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

transaction_status

string

required

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

transaction_type

string

required

Transaction type. Value: "PRE_AUTH_TRANSACTION" for preauthorization transactions

reference_id

string

Transaction identifier provided by the client

amount

number

required

Preauthorized amount

currency

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

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

reference_id

string<uuid>

Example:

"ORDER-123456"

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

Getting Started

Merchant API

PayIn API

PayOut API

Card Payment API

Integration

​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