POST Renewal Preauthorize

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

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

POST

api

subscription

card

authorize

renewal

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

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

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

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

POST Preauthorize Transaction POST Capture Transaction

​Required Headers

​Request Body Parameters

​Validation Rules

​Required Fields

​Allowed Values

​currency

​Common Validation Error Messages

​Response Fields

​Success Response (200 OK)

​HTTP Status Codes

​Response Codes

​Transaction Types

​Pre-Authorization Renewal (RENEWAL_PRE_AUTH_TRANSACTION)

​Supported Currencies

Headers

Body

Response

Required Headers

Request Body Parameters

Validation Rules

Required Fields

Allowed Values

currency

Common Validation Error Messages

Response Fields

Success Response (200 OK)

HTTP Status Codes

Response Codes

Transaction Types

Pre-Authorization Renewal (RENEWAL_PRE_AUTH_TRANSACTION)

Supported Currencies