Skip to main content
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"
}'

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

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

FieldTypeRulesDescription
reference_idstringrequired, max:36Unique payment reference identifier
subscription_idstringrequired, max:36Subscription UUID
currencystringrequired, max:3ISO 4217 currency code
amountnumericrequired, min:0Payment amount (must be greater than or equal to 0)
taxnumericrequired, min:0Payment tax (must be greater than or equal to 0)
linked_transaction_idstringrequired, max:36UUID 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

​
HTTP Status Codes

Status CodeDescriptionResponse Body
200 OKSuccessful renewalstatus: true, code: "AUTHORIZED"
400 Bad RequestMissing required header (X-Merchant-ID or X-Request-ID)Simple error message
401 UnauthorizedAuthentication failed (invalid Token-Top or Authorization)code: "UNAUTHORIZED"
404 Not FoundSubscription or transaction not foundcode: "NOT_FOUND"
422 Unprocessable EntityValidation error, invalid subscription/transaction state, or provider renewal failurecode: "VALIDATION_ERROR", "INVALID_STATE" or "PAYMENT_RENEWAL_FAILED"
500 Internal Server ErrorInternal server errorcode: "SERVICE_ERROR"

​
Response Codes

CodeDescription
AUTHORIZEDSuccessful renewal
VALIDATION_ERRORValidation error in sent data (missing fields, incorrect types, invalid UUID, etc.)
UNAUTHORIZEDAuthentication error
NOT_FOUNDSubscription or transaction not found
INVALID_STATEInvalid state of subscription or original transaction (inactive subscription, unapproved transaction, etc.)
PAYMENT_RENEWAL_FAILEDRenewal failed at the payment provider
SERVICE_ERRORInternal 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