POST Renewal Preauthorize

Preauthorizes a configured amount for a subscription in a renewal cycle.

POST /api/subscription/card/authorize/renewal

curl --request POST 'https://tumipay-card-payments.staging.tumipay.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"
}'

Success - Renewal Authorization Successful (200)

{
    "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"
    }
}

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.

curl --request POST 'https://tumipay-card-payments.staging.tumipay.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"
}'

Success - Renewal Authorization Successful (200)

{
    "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"
    }
}

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 renewal payment is preauthorized

reference_id · string · required

Unique transaction identifier provided by the client for this new cycle

currency · string · required

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

amount · number · required

Amount to preauthorize for this renewal cycle. Must be a positive value.

tax · number · required

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

linked_transaction_id · string · required

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)

code · string · required

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

status · boolean · required

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

message · string · required

Descriptive message about the renewal result

data · object · required

Show Transaction data

transaction_id · string · required

Unique identifier of the new renewal transaction created. 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)

linked_transaction_id · string · required

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

transaction_status · string · required

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

transaction_type · string · required

Transaction type. Value: "RENEWAL_PRE_AUTH_TRANSACTION" for renewal transactions

reference_id · string · required

Transaction identifier provided by the client

amount · number · required

Preauthorized amount for this cycle

currency · string · required

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

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

reference_id · string<uuid> · required

Example:

"ORDER-123456"

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

linked_transaction_id · string<uuid> · required

Example:

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

Response

200

application/json

Successful renewal. A new transaction of type RENEWAL_PRE_AUTH_TRANSACTION is created and the original transaction is automatically cancelled.

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.

code · string · required

Response code. Value: 'AUTHORIZED' when renewal 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 renewal result

Example:

"Renovación de pago autorizada exitosamente"

data · object · required

Show child attributes