Colombia - Card Payment

This section provides Colombia-specific information about using the Card Payment API to manage subscriptions with credit and debit cards.

Availability

The Card Payment API is available in Colombia to process recurring payments with credit and debit cards issued by Colombian and international banks.

Accepted Documents

To create subscriptions and process card payments in Colombia, the following document types are accepted:

Type	Description
`CC`	Cédula de Ciudadanía
`CE`	Cédula de Extranjería
`PPN`	Pasaporte

Supported Currencies

Code	Currency
`COP`	Colombian Peso

Subscription Periodicity

Subscriptions in Colombia support the following periodicities:

Periodicity	Description
`monthly`	Recurring monthly payments
`yearly`	Recurring yearly payments
`custom`	Custom periodicity according to configuration

Workflow

1. Create Subscription

First, create a subscription by associating a card with a recurring payment plan. The card token must be obtained through the TumiPay SDK.

2. Preauthorize Transactions

For each payment cycle, preauthorize the corresponding amount. This reserves funds without making the actual charge.

3. Capture Transactions

Once preauthorized, capture the transaction to perform the actual charge to the customer’s card.

4. Automatic Renewal

For recurring subscriptions, use the renewal preauthorization endpoint to process payments in each cycle.

Special Considerations

3D Secure (3DS)

Some card transactions may require 3D Secure authentication. The system automatically handles this process when necessary.

Transaction Limits

Transaction limits may vary depending on the card type and issuing bank. Contact the support team to learn about the specific limits applicable to your account.

International Cards

Cards issued by international banks are accepted, as long as they are compatible with the processing networks available in Colombia.

Examples

Create Subscription

cURL

curl --request POST 'https://tumipay-card-payments.staging.tumipay.co/production/api/subscription/card' \
--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 '{
    "token": "card_token_abc123",
    "plan_name": "Plan Premium",
    "periodicity": "monthly",
    "customer_data": {
        "legal_doc": "1234567890",
        "legal_doc_type": "CC",
        "phone_code": "57",
        "phone_number": "3121234567",
        "email": "[email protected]",
        "full_name": "John Doe"
    },
    "start_date": "2026-01-01"
}'

Response

{
    "code": "CREATED",
    "status": true,
    "message": "Suscripción creada exitosamente",
    "data": {
        "subscription_id": "550e8400-e29b-41d4-a716-446655440000"
    }
}

Webhooks

TumiPay Card Payments sends webhooks to notify your system about important events in the payment lifecycle. Webhooks allow you to receive real-time updates about transactions and subscriptions without polling the API.

What are Webhooks?

Webhooks are HTTP callbacks that automatically notify your application when specific events occur, such as transaction authorizations, captures, or subscription status changes.

Available Events

TumiPay Card Payments sends webhooks for the following events in Colombia:

Transaction Events

transaction.authorized - Transaction successfully authorized
transaction.captured - Transaction successfully captured
transaction.declined - Transaction declined by provider

Subscription Events

subscription.created - Subscription successfully created
subscription.cancelled - Subscription cancelled
subscription.expired - Subscription expired

Webhook Configuration

Before receiving webhooks, you must configure your webhook endpoint. To configure webhooks for Card Payment, please contact the support team.

How to Configure Webhooks

To set up webhook notifications, you need to:

Contact Support: Send an email to [email protected] or request assistance through the support channel
Provide Your Webhook URL: Your HTTPS endpoint where webhooks will be sent (must be publicly accessible)
Receive Secret Key: You will receive a shared secret key used to sign and verify webhook payloads
Activation: The support team will activate webhook delivery for your account

For webhook configuration assistance, contact:

Support Email: [email protected]
Technical Email: [email protected]

Your webhook URL must use HTTPS. TumiPay will only send webhooks to secure endpoints.

Security

All webhooks are signed using HMAC SHA256. You must verify the signature in the X-Webhook-Signature header before processing any webhook to ensure authenticity.

Always verify webhook signatures to prevent unauthorized requests. Use constant-time comparison functions to prevent timing attacks.

Idempotency

Webhooks include an idempotency_key in both the payload and the X-Idempotency-Key header. Use this key to detect and handle duplicate webhook deliveries. Format: {event_type}:{entity_uuid} Example: transaction.authorized:transaction-uuid-123

Retry Logic

If your endpoint doesn’t return a 2xx status code, TumiPay will automatically retry:

First retry: 60 seconds (1 minute)
Second retry: 600 seconds (10 minutes)
Third retry: 1800 seconds (30 minutes)

Return 200 OK immediately upon receiving the webhook. Process the webhook asynchronously if needed, but don’t wait for processing to complete before responding.

Example Webhook Payload

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "event": "transaction.authorized",
  "timestamp": "2024-01-01T10:00:00.000Z",
  "idempotency_key": "transaction.authorized:transaction-uuid-123",
  "data": {
    "transaction": {
      "transaction_id": "transaction-uuid-123",
      "transaction_type": "PRE_AUTH_TRANSACTION",
      "transaction_status": "APPROVED",
      "amount": "100.00",
      "currency": "COP",
      "reference_id": "merchant-reference-123",
      "transaction_date": "2024-01-01T10:00:00Z"
    },
    "subscription": {
      "subscription_id": "subscription-uuid-456",
      "status": "ACTIVE"
    }
  }
}

HTTP Headers

Every webhook request includes these headers:

Header	Description
`X-Webhook-Event`	Event type identifier
`X-Webhook-Timestamp`	ISO 8601 timestamp in UTC
`X-Webhook-Id`	Unique identifier for this webhook
`X-Idempotency-Key`	Key for duplicate detection
`X-Webhook-Signature`	HMAC SHA256 signature for verification
`User-Agent`	`TumiPay-Webhooks/1.0`

Complete Documentation

For detailed information about webhooks, including:

Complete signature verification examples (PHP, Node.js, Python)
All event payload structures
Best practices and implementation guides
Complete webhook handler examples

See the complete Webhooks documentation.

Support

For more information or to resolve questions about using Card Payment in Colombia, contact the support team:

Email: [email protected]
Technical email: [email protected]

Overview

Country Configuration

Card Payment

Colombia - Card Payment

Availability

Accepted Documents

Supported Currencies

Subscription Periodicity

Workflow

1. Create Subscription

2. Preauthorize Transactions

3. Capture Transactions

4. Automatic Renewal

Special Considerations

3D Secure (3DS)

Transaction Limits

International Cards

Examples

Create Subscription

Response

Webhooks

What are Webhooks?

Available Events

Transaction Events

Subscription Events

Webhook Configuration

How to Configure Webhooks

Security

Idempotency

Retry Logic

Example Webhook Payload

HTTP Headers

Complete Documentation

Support

Overview

Country Configuration

​Colombia - Card Payment

​Availability

​Accepted Documents

​Supported Currencies

​Subscription Periodicity

​Workflow

​1. Create Subscription

​2. Preauthorize Transactions

​3. Capture Transactions

​4. Automatic Renewal

​Special Considerations

​3D Secure (3DS)

​Transaction Limits

​International Cards

​Examples

​Create Subscription

​Response

​Webhooks

What are Webhooks?

​Available Events

Transaction Events

Subscription Events

​Webhook Configuration

How to Configure Webhooks

​Security

​Idempotency

​Retry Logic

​Example Webhook Payload

​HTTP Headers

​Complete Documentation

​Support

Colombia - Card Payment

Availability

Accepted Documents

Supported Currencies

Subscription Periodicity

Workflow

1. Create Subscription

2. Preauthorize Transactions

3. Capture Transactions

4. Automatic Renewal

Special Considerations

3D Secure (3DS)

Transaction Limits

International Cards

Examples

Create Subscription

Response

Webhooks

Available Events

Webhook Configuration

Security

Idempotency

Retry Logic

Example Webhook Payload

HTTP Headers

Complete Documentation

Support