> ## Documentation Index
> Fetch the complete documentation index at: https://docs.v2.topup.com.co/llms.txt
> Use this file to discover all available pages before exploring further.
# POST Capture Transaction
> Captures a previously preauthorized transaction.
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](/api-reference/card-payment/post-renewal-authorize) endpoint instead of attempting to capture a larger amount.
```bash theme={null}
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
}'
```
```json Success - Payment Captured (200) theme={null}
{
"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"
}
}
```
```json Validation Error (422) theme={null}
{
"code": "VALIDATION_ERROR",
"status": false,
"message": "transaction_id is required."
}
```
```json Missing Required Header - X-Merchant-ID (400) theme={null}
{
"message": "Missing required header: X-Merchant-ID"
}
```
```json Missing Required Header - X-Request-ID (400) theme={null}
{
"message": "Missing required header: X-Request-ID"
}
```
```json Internal Authentication Failed (401) theme={null}
{
"code": "UNAUTHORIZED",
"status": false,
"message": "Unauthorized."
}
```
```json Transaction Not Found (404) theme={null}
{
"code": "NOT_FOUND",
"status": false,
"message": "No se pudo localizar la transacción solicitada con UUID: 550e8400-e29b-41d4-a716-446655440000"
}
```
```json Invalid Transaction State - Cannot Capture (422) theme={null}
{
"code": "INVALID_STATE",
"status": false,
"message": "El pago no puede ser capturado porque la transacción no está aprobada."
}
```
```json Invalid Transaction Type (422) theme={null}
{
"code": "INVALID_STATE",
"status": false,
"message": "Solo las transacciones de preautorización pueden ser capturadas."
}
```
```json Missing Provider Reference (422) theme={null}
{
"code": "INVALID_STATE",
"status": false,
"message": "La transacción no tiene una referencia de proveedor válida."
}
```
```json Transaction Not Associated with Subscription (422) theme={null}
{
"code": "INVALID_STATE",
"status": false,
"message": "La transacción no está asociada con una suscripción."
}
```
```json Subscription Not Found (404) theme={null}
{
"code": "NOT_FOUND",
"status": false,
"message": "No se pudo localizar la suscripción solicitada con ID: 123"
}
```
```json Subscription Missing Provider ID (422) theme={null}
{
"code": "INVALID_STATE",
"status": false,
"message": "La suscripción no tiene un ID de proveedor válido."
}
```
```json Payment Capture Failed (422) theme={null}
{
"code": "PAYMENT_CAPTURE_FAILED",
"status": false,
"message": "La captura de pago falló. Por favor, verifique la información proporcionada."
}
```
```json Invalid Capture Amount (422) theme={null}
{
"code": "PROCESSING_ERROR",
"status": false,
"message": "El monto de captura es inválido. Por favor, verifique el monto y vuelva a intentarlo."
}
```
This error occurs when attempting to capture an amount greater than the authorized amount. If you need to capture a larger amount, use the [Renewal Preauthorize](/api-reference/card-payment/post-renewal-authorize) endpoint instead.
```json Service Error (500) theme={null}
{
"code": "SERVICE_ERROR",
"status": false,
"message": "Ocurrió un error inesperado"
}
```
## Required Headers
Merchant authentication token
Basic authentication (Basic Auth)
Unique identifier of the merchant invoking Card Payment services
Unique tracking identifier for the request
Must be "application/json"
## Request Body Parameters
Unique identifier of the preauthorization transaction to capture
Amount to capture. Must be greater than 0.
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)
Response code. Value: `"CAPTURED"` when capture is successful
Operation status. `true` when successful, `false` when there is an error
Descriptive message about the capture result
Unique identifier of the new capture transaction created
Identifier of the original preauthorization transaction to which this capture is linked
Capture processing date and time in ISO 8601 format with UTC timezone (format: `Y-m-d\TH:i:s\Z`)
Transaction status. Value: `"APPROVED"` when capture is successful
Transaction type. Value: `"COMPLETION_TRANSACTION"` for capture transactions
Transaction identifier provided by the client in the original preauthorization
Captured amount
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
## OpenAPI
````yaml post /api/subscription/card/capture
openapi: 3.0.0
info:
title: Payment Platform - Card Payment API
version: 1.0.0
description: API for managing subscriptions with credit and debit cards.
contact:
url: https://docs.tumipay.co
name: Payment Platform Card Payment
email: it@tumipay.co
license:
name: Proprietary License
url: https://tumipay.com/license
servers:
- url: https://tumipay-card-payments.staging.topup.com.co/production
description: Staging server
security: []
tags:
- name: CardPayment
description: Operations related to subscription creation, authorization, and capture.
paths:
/api/subscription/card/capture:
post:
tags:
- CardPayment
summary: Capture transaction
description: Captures a previously preauthorized transaction.
operationId: captureCardPaymentTransaction
parameters:
- $ref: '#/components/parameters/MerchantId'
- $ref: '#/components/parameters/RequestId'
- $ref: '#/components/parameters/TokenTop'
- $ref: '#/components/parameters/BasicAuth'
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- transaction_id
- amount
- tax
properties:
transaction_id:
type: string
format: uuid
example: 7f45a9da-2f84-4103-ac54-05fe8ea693ca
amount:
type: number
minimum: 0
example: 1500
tax:
type: number
minimum: 0
example: 0
responses:
'200':
description: >-
Successful capture. A new transaction of type COMPLETION_TRANSACTION
is created.
content:
application/json:
schema:
$ref: '#/components/schemas/CaptureResponse'
examples:
success:
summary: Capture successful
value:
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
currency: COP
'400':
description: >-
Bad request: missing required header (X-Merchant-ID or X-Request-ID)
or invalid capture amount from payment provider (K012). If the
capture amount exceeds 10% of the originally authorized amount,
Kushki returns this error — use the Renewal endpoint instead.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
missing_header:
summary: Missing required header
value:
code: MISSING_HEADER
status: false
message: The X-Merchant-ID header is required.
invalid_capture_amount:
summary: >-
Invalid capture amount (exceeds 10% of authorized amount —
use Renewal instead)
value:
code: PROCESSING_ERROR
status: false
message: >-
El monto de captura es inválido. Por favor, verifique el
monto y vuelva a intentarlo.
'401':
description: Authentication failed (invalid Token-Top or Authorization).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Transaction or subscription not found.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'409':
description: >-
The transaction has already been captured. Each pre-authorization
can only be captured once.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
already_captured:
summary: Transaction already captured
value:
code: TRANSACTION_ALREADY_CAPTURED
status: false
message: La transacción ya fue capturada anteriormente.
'422':
description: >-
Validation error or invalid transaction/subscription state for
capture. Only APPROVED transactions of type PRE_AUTH_TRANSACTION or
RENEWAL_PRE_AUTH_TRANSACTION can be captured.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
invalid_state:
summary: Invalid transaction state for capture
value:
code: INVALID_STATE
status: false
message: >-
This transaction operation cannot be performed. Current
status: DECLINED
'500':
description: Internal server error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
components:
parameters:
MerchantId:
name: X-Merchant-ID
in: header
required: true
description: >-
Unique identifier of the Merchant invoking Card Payment services. Should
not be used to authenticate end users.
schema:
type: string
RequestId:
name: X-Request-ID
in: header
required: true
description: >-
Tracking identifier associated with the request, used to establish a
correlation_id between ecosystem components.
schema:
type: string
TokenTop:
name: Token-Top
in: header
required: true
description: Token for authentication.
schema:
type: string
BasicAuth:
name: Authorization
in: header
required: true
description: Basic authentication.
schema:
type: string
schemas:
CaptureResponse:
type: object
description: >-
Response when capturing a transaction. Creates a new transaction of type
COMPLETION_TRANSACTION linked to the original transaction.
required:
- code
- status
- message
- data
properties:
code:
type: string
description: 'Response code. Value: ''CAPTURED'' when capture is successful'
example: CAPTURED
status:
type: boolean
description: Operation status. true when successful, false when there is an error
example: true
message:
type: string
description: Descriptive message about the capture result
example: Pago capturado exitosamente
data:
type: object
properties:
transaction_id:
type: string
format: uuid
description: Unique identifier of the new capture transaction created
example: 550e8400-e29b-41d4-a716-446655440000
linked_transaction_id:
type: string
format: uuid
description: >-
Identifier of the original preauthorization transaction to which
this capture is linked
example: 660e8400-e29b-41d4-a716-446655440001
transaction_date:
type: string
format: date-time
description: >-
Capture processing date and time in ISO 8601 format with UTC
timezone (format: Y-m-d\TH:i:s\Z)
example: '2024-01-15T10:30:45Z'
transaction_status:
type: string
description: 'Transaction status. Value: ''APPROVED'' when capture is successful'
example: APPROVED
transaction_type:
type: string
description: >-
Transaction type. Value: 'COMPLETION_TRANSACTION' for capture
transactions
example: COMPLETION_TRANSACTION
reference_id:
type: string
description: >-
Transaction identifier provided by the client in the original
preauthorization
example: reference-uuid-123
amount:
type: number
description: Captured amount
example: 100
currency:
type: string
description: Transaction currency code (e.g., 'COP')
example: COP
required:
- transaction_id
- linked_transaction_id
- transaction_date
- transaction_status
- transaction_type
- amount
- currency
ErrorResponse:
type: object
description: >-
Standard structure for error responses. For 400 errors (missing
headers), it only contains 'message'.
oneOf:
- type: object
properties:
code:
type: string
description: >-
Error code. Possible values: 'VALIDATION_ERROR', 'UNAUTHORIZED',
'NOT_FOUND', 'ACCESS_DENIED', 'SUBSCRIPTION_CREATION_FAILED',
'SERVICE_ERROR'
example: VALIDATION_ERROR
status:
type: boolean
description: Always false for error responses
example: false
message:
type: string
description: Descriptive error message
example: The given data was invalid.
details:
type: object
additionalProperties: true
description: Additional error details (optional)
- type: object
properties:
message:
type: string
description: Error message for missing headers
example: 'Missing required header: X-Merchant-ID'
required:
- message
````