> ## 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.

# Card Payment API

> API for managing subscriptions with credit and debit cards, including preauthorization and transaction capture.

# 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:

| Value     | Description                                        |
| --------- | -------------------------------------------------- |
| `monthly` | Recurring monthly payments                         |
| `yearly`  | Recurring yearly payments                          |
| `custom`  | Custom periodicity according to plan configuration |

### Transaction Flow

The payment process with subscriptions follows this flow:

```mermaid theme={null}
sequenceDiagram
    participant M as Merchant
    participant T as TumiPay API
    participant P as Payment Provider
    participant C as Customer Card

    M->>T: 1. Create subscription
    T->>T: 2. Validate and store subscription
    T->>M: 3. Return subscription_id
    
    M->>T: 4. Preauthorize transaction
    T->>P: 5. Request preauthorization
    P->>C: 6. Verify funds
    C->>P: 7. Verification response
    P->>T: 8. Preauthorization result
    T->>M: 9. Return transaction_id and status
    
    M->>T: 10. Capture transaction
    T->>P: 11. Process capture
    P->>C: 12. Charge amount to card
    C->>P: 13. Charge confirmation
    P->>T: 14. Capture result
    T->>M: 15. Return confirmation
```

### 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

<Card title="/subscription/card" icon="plus-circle" iconType="solid">
  Creates a new subscription by associating a card with a recurring payment plan.
</Card>

### Cancel Subscription

<Card title="/subscription/card/cancel" icon="x-circle" iconType="solid">
  Cancels an existing subscription. The operation is idempotent.
</Card>

### Preauthorize Transaction

<Card title="/subscription/card/authorize" icon="lock" iconType="solid">
  Preauthorizes an amount for a subscription without making the actual charge.
</Card>

### Renew Preauthorization

<Card title="/subscription/card/authorize/renewal" icon="refresh" iconType="solid">
  Preauthorizes an amount for a new cycle of an existing subscription.
</Card>

### Capture Transaction

<Card title="/subscription/card/capture" icon="check-circle" iconType="solid">
  Captures a previously preauthorized transaction, performing the actual charge to the card.
</Card>

## 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](/api-reference/authentication).

## Transaction States

Transactions can have the following states:

| State        | Description                                     |
| ------------ | ----------------------------------------------- |
| `PENDING`    | Transaction created but not yet processed       |
| `PROCESSING` | Transaction in validation/authorization process |
| `APPROVED`   | Transaction approved successfully               |
| `DECLINED`   | Transaction rejected by the provider            |
| `REFUNDED`   | Transaction refunded                            |
| `CANCELLED`  | Transaction cancelled                           |
| `ERROR`      | Error in transaction processing                 |

## Transaction Types

| Type                           | Description              |
| ------------------------------ | ------------------------ |
| `PRE_AUTH_TRANSACTION`         | Initial preauthorization |
| `RENEWAL_PRE_AUTH_TRANSACTION` | Renewal preauthorization |
| `COMPLETION_TRANSACTION`       | Transaction capture      |

## 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)