> ## 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 Renewal Preauthorize
> Preauthorizes a configured amount for a subscription in a renewal cycle.
Preauthorize an amount for a new cycle of an existing subscription. This endpoint is used to process recurring payments on active subscriptions, linking the new transaction with the original preauthorization.
```bash theme={null}
curl --request POST 'https://tumipay-card-payments.staging.topup.com.co/production/api/v1/subscription/card/authorize/renewal' \
--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_002",
"currency": "COP",
"amount": 400000,
"tax": 0,
"linked_transaction_id": "7f45a9da-2f84-4103-ac54-05fe8ea693ca"
}'
```
```json Success - Renewal Authorization Successful (200) theme={null}
{
"code": "AUTHORIZED",
"status": true,
"message": "Renovación de pago autorizada exitosamente",
"data": {
"transaction_id": "770e8400-e29b-41d4-a716-446655440002",
"transaction_date": "2025-12-23T10:30:45Z",
"linked_transaction_id": "660e8400-e29b-41d4-a716-446655440001",
"transaction_status": "APPROVED",
"transaction_type": "RENEWAL_PRE_AUTH_TRANSACTION",
"reference_id": "reference-uuid-456",
"amount": 150.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 Transaction Not Found (404) theme={null}
{
"code": "NOT_FOUND",
"status": false,
"message": "No se pudo localizar la transacción solicitada con UUID: 660e8400-e29b-41d4-a716-446655440001"
}
```
```json Invalid Transaction State - Cannot Renew (422) theme={null}
{
"code": "INVALID_STATE",
"status": false,
"message": "El pago no puede ser renovado porque la transacción original no está aprobada."
}
```
```json Payment Renewal Failed (422) theme={null}
{
"code": "PAYMENT_RENEWAL_FAILED",
"status": false,
"message": "La autorización de renovació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 renewal payment is preauthorized
Unique transaction identifier provided by the client for this new cycle
Currency code for transaction processing (e.g., "COP", "PEN", "USD")
Amount to preauthorize for this renewal cycle. Must be a positive value.
Processing tax associated with the transaction. If no tax will be charged, send `0`.
Identifier of the original preauthorization transaction. This ID links the new transaction with the subscription history.
## Validation Rules
### Required Fields
| Field | Type | Rules | Description |
| ----------------------- | ------- | ---------------- | --------------------------------------------------- |
| `reference_id` | string | required, max:36 | Unique payment reference identifier |
| `subscription_id` | string | required, max:36 | Subscription UUID |
| `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) |
| `linked_transaction_id` | string | required, max:36 | UUID of the original linked transaction |
### 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 renewal is successful
Operation status. `true` when successful, `false` when there is an error
Descriptive message about the renewal result
Unique identifier of the new renewal transaction created. 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`)
Identifier of the original preauthorization transaction to which this renewal is linked
Transaction status. Value: `"APPROVED"` when renewal is successful
Transaction type. Value: `"RENEWAL_PRE_AUTH_TRANSACTION"` for renewal transactions
Transaction identifier provided by the client
Preauthorized amount for this cycle
Transaction currency code (e.g., "COP")
## HTTP Status Codes
| Status Code | Description | Response Body |
| --------------------------- | ------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
| `200 OK` | Successful renewal | `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 or transaction not found | `code: "NOT_FOUND"` |
| `422 Unprocessable Entity` | Validation error, invalid subscription/transaction state, or provider renewal failure | `code: "VALIDATION_ERROR"`, `"INVALID_STATE"` or `"PAYMENT_RENEWAL_FAILED"` |
| `500 Internal Server Error` | Internal server error | `code: "SERVICE_ERROR"` |
## Response Codes
| Code | Description |
| ------------------------ | ----------------------------------------------------------------------------------------------------------- |
| `AUTHORIZED` | Successful renewal |
| `VALIDATION_ERROR` | Validation error in sent data (missing fields, incorrect types, invalid UUID, etc.) |
| `UNAUTHORIZED` | Authentication error |
| `NOT_FOUND` | Subscription or transaction not found |
| `INVALID_STATE` | Invalid state of subscription or original transaction (inactive subscription, unapproved transaction, etc.) |
| `PAYMENT_RENEWAL_FAILED` | Renewal failed at the payment provider |
| `SERVICE_ERROR` | Internal server error |
## Transaction Types
### Pre-Authorization Renewal (RENEWAL\_PRE\_AUTH\_TRANSACTION)
* **Type**: `RENEWAL_PRE_AUTH_TRANSACTION`
* **Status**: `APPROVED` (success) or `DECLINED`/`ERROR` (failure)
* **Purpose**: Renew a previous authorization, cancelling the original and creating a new one
* **Linkage**: `linked_transaction_id` points to the original transaction
* **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/renewal
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/renewal:
post:
tags:
- CardPayment
summary: Renew a Pre Authorization
description: Preauthorizes a configured amount for a subscription in a renewal cycle.
operationId: renewalPpreAuthorizeCardPayment
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
- linked_transaction_id
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
linked_transaction_id:
type: string
format: uuid
example: 7f45a9da-2f84-4103-ac54-05fe8ea693ca
responses:
'200':
description: >-
Successful renewal. A new transaction of type
RENEWAL_PRE_AUTH_TRANSACTION is created and the original transaction
is automatically cancelled.
content:
application/json:
schema:
$ref: '#/components/schemas/RenewalPreAuthorizeResponse'
examples:
success:
summary: Renewal successful
value:
code: AUTHORIZED
status: true
message: Renovación de pago autorizada exitosamente
data:
transaction_id: 770e8400-e29b-41d4-a716-446655440002
transaction_date: '2025-12-23T10:30:45Z'
linked_transaction_id: 660e8400-e29b-41d4-a716-446655440001
transaction_status: APPROVED
transaction_type: RENEWAL_PRE_AUTH_TRANSACTION
reference_id: reference-uuid-456
amount: 150
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: Suscripción o transacción no encontrada.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'422':
description: >-
Validation error, invalid subscription/transaction state, or payment
provider renewal 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:
RenewalPreAuthorizeResponse:
type: object
description: >-
Renewal preauthorization response. Creates a new transaction of type
RENEWAL_PRE_AUTH_TRANSACTION and automatically cancels the original
transaction when the renewal is successful or rejected.
required:
- code
- status
- message
- data
properties:
code:
type: string
description: 'Response code. Value: ''AUTHORIZED'' when renewal 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 renewal result
example: Renovación de pago autorizada exitosamente
data:
type: object
properties:
transaction_id:
type: string
format: uuid
description: >-
Unique identifier of the new renewal transaction created. This
ID will be used to capture the transaction later.
example: 770e8400-e29b-41d4-a716-446655440002
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'
linked_transaction_id:
type: string
format: uuid
description: >-
Identifier of the original preauthorization transaction to which
this renewal is linked
example: 660e8400-e29b-41d4-a716-446655440001
transaction_status:
type: string
description: 'Transaction status. Value: ''APPROVED'' when renewal is successful'
example: APPROVED
transaction_type:
type: string
description: >-
Transaction type. Value: 'RENEWAL_PRE_AUTH_TRANSACTION' for
renewal transactions
example: RENEWAL_PRE_AUTH_TRANSACTION
reference_id:
type: string
description: Transaction identifier provided by the client
example: reference-uuid-456
amount:
type: number
description: Preauthorized amount for this cycle
example: 150
currency:
type: string
description: Transaction currency code (e.g., 'COP')
example: COP
required:
- transaction_id
- transaction_date
- linked_transaction_id
- transaction_status
- transaction_type
- reference_id
- 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
````