> ## 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 Preauthorize Transaction
> Preauthorizes a configured amount for a subscription.
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.
```bash theme={null}
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
}'
```
```json Success - Payment Authorized (200) theme={null}
{
"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"
}
}
```
```json Validation Error (422) theme={null}
{
"code": "VALIDATION_ERROR",
"status": false,
"message": "reference_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 Subscription Not Found (404) theme={null}
{
"code": "NOT_FOUND",
"status": false,
"message": "No se pudo localizar la suscripción solicitada con UUID: 550e8400-e29b-41d4-a716-446655440000"
}
```
```json Invalid Subscription State - Not Active (422) theme={null}
{
"code": "INVALID_STATE",
"status": false,
"message": "El pago no puede ser autorizado porque la suscripción no es válida."
}
```
```json Payment Authorization Failed (422) theme={null}
{
"code": "PAYMENT_AUTHORIZATION_FAILED",
"status": false,
"message": "La autorización de pago falló. Por favor, verifique la información proporcionada."
}
```
```json Service Error (500) theme={null}
{
"code": "SERVICE_ERROR",
"status": false,
"message": "Ocurrió un error. Por favor, intente nuevamente."
}
```
## 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
Identifier of the subscription for which the payment is preauthorized
Unique transaction identifier provided by the client. If not provided, the system generates one automatically.
Currency code for transaction processing (e.g., "COP", "PEN", "USD")
Amount to preauthorize. Must be a positive value.
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)
Response code. Value: `"AUTHORIZED"` when authorization is successful
Operation status. `true` when successful, `false` when there is an error
Descriptive message about the authorization result
Unique identifier of the created preauthorization transaction. This ID will be used to capture the transaction later.
Transaction processing date and time in ISO 8601 format with UTC timezone (format: `Y-m-d\TH:i:s\Z`)
Transaction status. Value: `"APPROVED"` when authorization is successful
Transaction type. Value: `"PRE_AUTH_TRANSACTION"` for preauthorization transactions
Transaction identifier provided by the client
Preauthorized amount
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
## OpenAPI
````yaml post /api/subscription/card/authorize
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/authorize:
post:
tags:
- CardPayment
summary: Preauthorize a Transaction
description: Preauthorizes a configured amount for a subscription.
operationId: preAuthorizeCardPayment
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:
- reference_id
- subscription_id
- currency
- amount
- tax
properties:
reference_id:
type: string
format: uuid
example: ORDER-123456
subscription_id:
type: string
format: uuid
example: 550e8400-e29b-41d4-a716-446655440000
currency:
type: string
example: COP
amount:
type: number
minimum: 0
example: 1500
tax:
type: number
minimum: 0
example: 0
responses:
'200':
description: >-
Successful authorization. A new transaction of type
PRE_AUTH_TRANSACTION is created.
content:
application/json:
schema:
$ref: '#/components/schemas/PreAuthorizeResponse'
examples:
success:
summary: Authorization successful
value:
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
currency: COP
'400':
description: Missing required header (X-Merchant-ID or X-Request-ID).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Authentication failed (invalid Token-Top or Authorization).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Subscription not found.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'422':
description: >-
Validation error, invalid subscription state, or payment provider
authorization failure.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'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:
PreAuthorizeResponse:
type: object
description: >-
Preauthorization response. Creates a new transaction of type
PRE_AUTH_TRANSACTION.
required:
- code
- status
- message
- data
properties:
code:
type: string
description: 'Response code. Value: ''AUTHORIZED'' when authorization is successful'
example: AUTHORIZED
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 authorization result
example: Pago autorizado exitosamente
data:
type: object
properties:
transaction_id:
type: string
format: uuid
description: >-
Unique identifier of the created preauthorization transaction.
This ID will be used to capture the transaction later.
example: 550e8400-e29b-41d4-a716-446655440000
transaction_date:
type: string
format: date-time
description: >-
Transaction processing date and time in ISO 8601 format with UTC
timezone (format: Y-m-d\TH:i:s\Z)
example: '2025-12-23T10:30:45Z'
transaction_status:
type: string
description: >-
Transaction status. Value: 'APPROVED' when authorization is
successful
example: APPROVED
transaction_type:
type: string
description: >-
Transaction type. Value: 'PRE_AUTH_TRANSACTION' for
preauthorization transactions
example: PRE_AUTH_TRANSACTION
reference_id:
type: string
description: Transaction identifier provided by the client
example: reference-uuid-123
amount:
type: number
description: Preauthorized amount
example: 100
currency:
type: string
description: Transaction currency code (e.g., 'COP')
example: COP
required:
- 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
````