POST Capture Transaction

curl --request POST 'https://tumipay-card-payments.staging.topup.com.co/production/api/v1/subscription/card/capture' \
--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 '{
    "transaction_id": "7f45a9da-2f84-4103-ac54-05fe8ea693ca",
    "amount": 400000,
    "tax": 0
}'

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

{
    "code": "VALIDATION_ERROR",
    "status": false,
    "message": "transaction_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 transacción solicitada con UUID: 550e8400-e29b-41d4-a716-446655440000"
}

{
    "code": "INVALID_STATE",
    "status": false,
    "message": "El pago no puede ser capturado porque la transacción no está aprobada."
}

{
    "code": "INVALID_STATE",
    "status": false,
    "message": "Solo las transacciones de preautorización pueden ser capturadas."
}

{
    "code": "INVALID_STATE",
    "status": false,
    "message": "La transacción no tiene una referencia de proveedor válida."
}

{
    "code": "INVALID_STATE",
    "status": false,
    "message": "La transacción no está asociada con una suscripción."
}

{
    "code": "NOT_FOUND",
    "status": false,
    "message": "No se pudo localizar la suscripción solicitada con ID: 123"
}

{
    "code": "INVALID_STATE",
    "status": false,
    "message": "La suscripción no tiene un ID de proveedor válido."
}

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

{
    "code": "PROCESSING_ERROR",
    "status": false,
    "message": "El monto de captura es inválido. Por favor, verifique el monto y vuelva a intentarlo."
}

{
    "code": "SERVICE_ERROR",
    "status": false,
    "message": "Ocurrió un error inesperado"
}

POST

api

subscription

card

capture

curl --request POST 'https://tumipay-card-payments.staging.topup.com.co/production/api/v1/subscription/card/capture' \
--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 '{
    "transaction_id": "7f45a9da-2f84-4103-ac54-05fe8ea693ca",
    "amount": 400000,
    "tax": 0
}'

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

{
    "code": "VALIDATION_ERROR",
    "status": false,
    "message": "transaction_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 transacción solicitada con UUID: 550e8400-e29b-41d4-a716-446655440000"
}

{
    "code": "INVALID_STATE",
    "status": false,
    "message": "El pago no puede ser capturado porque la transacción no está aprobada."
}

{
    "code": "INVALID_STATE",
    "status": false,
    "message": "Solo las transacciones de preautorización pueden ser capturadas."
}

{
    "code": "INVALID_STATE",
    "status": false,
    "message": "La transacción no tiene una referencia de proveedor válida."
}

{
    "code": "INVALID_STATE",
    "status": false,
    "message": "La transacción no está asociada con una suscripción."
}

{
    "code": "NOT_FOUND",
    "status": false,
    "message": "No se pudo localizar la suscripción solicitada con ID: 123"
}

{
    "code": "INVALID_STATE",
    "status": false,
    "message": "La suscripción no tiene un ID de proveedor válido."
}

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

{
    "code": "PROCESSING_ERROR",
    "status": false,
    "message": "El monto de captura es inválido. Por favor, verifique el monto y vuelva a intentarlo."
}

{
    "code": "SERVICE_ERROR",
    "status": false,
    "message": "Ocurrió un error inesperado"
}

Capture a previously preauthorized transaction, performing the actual charge to the customer’s card. You can only capture transactions that have been successfully preauthorized.

If you need to capture an amount greater than the authorized amount, you should use the Renewal Preauthorize endpoint instead of attempting to capture a larger amount.

curl --request POST 'https://tumipay-card-payments.staging.topup.com.co/production/api/v1/subscription/card/capture' \
--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 '{
    "transaction_id": "7f45a9da-2f84-4103-ac54-05fe8ea693ca",
    "amount": 400000,
    "tax": 0
}'

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

{
    "code": "VALIDATION_ERROR",
    "status": false,
    "message": "transaction_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 transacción solicitada con UUID: 550e8400-e29b-41d4-a716-446655440000"
}

{
    "code": "INVALID_STATE",
    "status": false,
    "message": "El pago no puede ser capturado porque la transacción no está aprobada."
}

{
    "code": "INVALID_STATE",
    "status": false,
    "message": "Solo las transacciones de preautorización pueden ser capturadas."
}

{
    "code": "INVALID_STATE",
    "status": false,
    "message": "La transacción no tiene una referencia de proveedor válida."
}

{
    "code": "INVALID_STATE",
    "status": false,
    "message": "La transacción no está asociada con una suscripción."
}

{
    "code": "NOT_FOUND",
    "status": false,
    "message": "No se pudo localizar la suscripción solicitada con ID: 123"
}

{
    "code": "INVALID_STATE",
    "status": false,
    "message": "La suscripción no tiene un ID de proveedor válido."
}

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

{
    "code": "PROCESSING_ERROR",
    "status": false,
    "message": "El monto de captura es inválido. Por favor, verifique el monto y vuelva a intentarlo."
}

{
    "code": "SERVICE_ERROR",
    "status": false,
    "message": "Ocurrió un error inesperado"
}

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

Unique identifier of the preauthorization transaction to capture

number

required

Amount to capture. Must be greater than 0.

number

required

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

Validation Rules

Required Fields

Field	Type	Rules	Description
`transaction_id`	string	required, max:36	UUID of the transaction to capture
`amount`	numeric	required, min:0	Amount to capture (must be greater than or equal to 0)
`tax`	numeric	required, min:0	Tax to capture (must be greater than or equal to 0)

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: "CAPTURED" when capture is successful

boolean

required

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

string

required

Descriptive message about the capture result

object

required

Show Captured transaction data

string

required

Unique identifier of the new capture transaction created

string

required

Identifier of the original preauthorization transaction to which this capture is linked

string

required

Capture 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 capture is successful

string

required

Transaction type. Value: "COMPLETION_TRANSACTION" for capture transactions

string

Transaction identifier provided by the client in the original preauthorization

number

required

Captured amount

string

required

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

HTTP Status Codes

Status Code	Description	Response Body
`200 OK`	Successful capture	`status: true`, `code: "CAPTURED"`
`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`	Transaction or subscription not found	`code: "NOT_FOUND"`
`422 Unprocessable Entity`	Validation error or invalid state	`code: "VALIDATION_ERROR"`, `"INVALID_STATE"`, `"PAYMENT_CAPTURE_FAILED"` or `"PROCESSING_ERROR"` (invalid capture amount)
`500 Internal Server Error`	Internal server error	`code: "SERVICE_ERROR"`

Response Codes

Code	Description
`CAPTURED`	Successful capture
`VALIDATION_ERROR`	Validation error in sent data (missing fields, incorrect types, etc.)
`UNAUTHORIZED`	Authentication error
`NOT_FOUND`	Transaction or subscription not found
`INVALID_STATE`	Invalid state of transaction or subscription (not approved, incorrect type, no provider reference, etc.)
`PAYMENT_CAPTURE_FAILED`	Capture failed at the payment provider
`PROCESSING_ERROR`	Invalid capture amount (greater than authorized amount). Use the Renewal Preauthorize endpoint instead.
`SERVICE_ERROR`	Internal server error

Transaction Types

Original Transaction (Pre-Authorization)

Type: PRE_AUTH_TRANSACTION or RENEWAL_PRE_AUTH_TRANSACTION
Status: APPROVED
Purpose: Reserve funds without capturing them

Capture Transaction

Type: COMPLETION_TRANSACTION
Status: APPROVED (success) or DECLINED/ERROR (failure)
Purpose: Capture the pre-authorized funds
Linkage: linked_transaction_id points to the original transaction

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

transaction_id

string<uuid>

required

Example:

"7f45a9da-2f84-4103-ac54-05fe8ea693ca"

amount

number

required

Required range: x >= 0

Example:

1500

tax

number

required

Required range: x >= 0

Example:

0

Response

Successful capture. A new transaction of type COMPLETION_TRANSACTION is created.

Response when capturing a transaction. Creates a new transaction of type COMPLETION_TRANSACTION linked to the original transaction.

code

string

required

Response code. Value: 'CAPTURED' when capture is successful

Example:

"CAPTURED"

status

boolean

required

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

Example:

true

message

string

required

Descriptive message about the capture result

Example:

"Pago capturado exitosamente"

data

object

required

Show child attributes

Getting Started

Merchant API

PayIn API

PayOut API

Card Payment API

Integration

POST Capture Transaction

Required Headers

Request Body Parameters

Validation Rules

Required Fields

Common Validation Error Messages

Response Fields

Success Response (200 OK)

HTTP Status Codes

Response Codes

Transaction Types

Original Transaction (Pre-Authorization)

Capture Transaction

Headers

Body

Response

​Required Headers

​Request Body Parameters

​Validation Rules

​Required Fields

​Common Validation Error Messages

​Response Fields

​Success Response (200 OK)

​HTTP Status Codes

​Response Codes

​Transaction Types

​Original Transaction (Pre-Authorization)

​Capture Transaction

Headers

Body

Response

Required Headers

Request Body Parameters

Validation Rules

Required Fields

Common Validation Error Messages

Response Fields

Success Response (200 OK)

HTTP Status Codes

Response Codes

Transaction Types

Original Transaction (Pre-Authorization)

Capture Transaction