​

Card Payment API

This API enables you to manage recurring subscriptions with credit and debit cards. With this API you can create subscriptions, preauthorize amounts, capture transactions, and cancel subscriptions when needed.

​

Key Concepts

​

Subscriptions

A subscription is an agreement between the merchant and the customer to make recurring payments. Each subscription has:

• Plan Name: Identifier name of the subscription plan
• Periodicity: Frequency of recurring payments
• Token: Token of the card associated with the subscription
• Customer Data: Customer information associated with the subscription

​

Periodicity

Periodicity defines how frequently subscription payments will be processed:

​

Transaction Flow

The payment process with subscriptions follows this flow:

​

Preauthorization

Preauthorization reserves an amount on the customer’s card without making the actual charge. This allows:

• Verifying that the card has sufficient funds
• Reserving the amount for later capture
• Validating that the card is still valid

Important: Preauthorizations have a limited validity period. You must capture the transaction within the established period.

​

Capture

Capture performs the actual charge to the customer’s card. You can only capture transactions that have been previously preauthorized.

​

Subscription Renewal

To process recurring payments on existing subscriptions, use the renewal preauthorization endpoint. This endpoint:

• Links the new transaction with the original preauthorization
• Maintains the history of related transactions
• Allows processing payments in each subscription cycle

​

Endpoints

​

Create Subscription

​

Cancel Subscription

​

Preauthorize Transaction

​

Renew Preauthorization

​

Capture Transaction

​

Authentication

All endpoints require authentication through:

• Basic Authentication: User credentials and password in the Authorization header
• Token-Top: Merchant authentication token in the Token-Top header
• X-Merchant-ID: Unique identifier of the merchant invoking Card Payment services (required)
• X-Request-ID: Tracking identifier for request correlation (required)

For more details on authentication, see the authentication documentation.

​

Transaction States

Transactions can have the following states:

​

Transaction Types

​

Error Handling

All endpoints return responses with standard structure:

• code: Response code
• status: Operation status
• message: Descriptive message
• data: Response data (if applicable)

In case of error, an ErrorResponse object is returned with:

• code: Specific error code
• message: Descriptive error message
• details: Additional error details (optional)