Guides
API Reference
Start typing to search…

🔁Subscription

📘 Credit Card Subscriptions API

Create, manage, and automate recurring credit card payments.

This guide explains how to create, retrieve, control, and cancel recurring credit card subscriptions using our API.

🔒

Note: Only single-installment credit card transactions are allowed for subscriptions.

🧭 Overview — Subscription Flow

sequenceDiagram
    autonumber
    participant Client
    participant API
    participant CardProcessor
    participant WebhookReceiver

    Client->>API: Create subscription (POST /charge/)
    API->>CardProcessor: Process initial charge
    CardProcessor-->>API: Charge approved
    API-->>Client: Return charge + subscription data
    API-->>WebhookReceiver: Webhook: charge confirmed

    loop Recurring Billing Cycle
        API->>CardProcessor: Attempt recurring charge
        alt Success
            CardProcessor-->>API: Charge approved
            API-->>WebhookReceiver: Webhook success
        else Failure
            CardProcessor-->>API: Charge failed
            API-->>WebhookReceiver: Webhook error
        end
    end

    alt Subscription cancelled
        Client->>API: Cancel subscription
        API-->>Client: Subscription cancelled
    else End date reached
        API-->>Client: Subscription expired
    end

🔄 Recurrence Models

We support two recurrence strategies:

🟦 Internal Recurrence (A55-Controlled)

"subscription": {
  "cycle": "weekly",
  "end_date": "2025-11-25"
}

Features

  • ✔️ Charges automatically generated by A55
  • ✔️ Webhooks for each event
  • ✔️ Minimal merchant effort
  • ❌ Does not use MIT indicators

🟩 External Recurrence (Merchant-Controlled)

"subscription": {
  "external_recurrence": true,
  "initiated_transaction_indicator_category": "C1"
}

Features

  • ✔️ Merchant controls timing of new charges
  • ✔️ Full support for C1/M1 indicators
  • ✔️ CRM-driven billing
  • ❌ Merchant must manage retries & scheduling

🔐 Initiated Transaction Indicators

IndicatorMeaning
C1Customer‑initiated transaction (first subscription payment, cardholder present)
M1Merchant‑initiated recurring charge (subsequent subscription payments)

Subscription Rules

  • First payment of the subscription → C1
  • All subsequent recurring charges → M1

🧑‍💼 Creating New Charges (External Recurrence)

First payment (customer-initiated)

{
    "wallet_uuid": "00000000-0000-0000-0000-000000000000",
    "merchant_id": "11111111-1111-1111-1111-111111111111",
    "payer_name": "John Doe",
    "payer_tax_id": "38899334821",
    "payer_email": "[email protected]",
    "payer_cell_phone": "+155599999999",
    "items": [
        {
            "name": "Test Product",
            "description": "Sample",
            "quantity": 1,
            "total_amount": 100.00,
            "unit_amount": 100.00,
            "sku": "TEST-SKU-001",
            "code": "TEST-CODE-001"
        }
    ],
    "payer_address": {
        "street": "Test Avenue",
        "address_number": "123",
        "complement": "Suite 456",
        "neighborhood": "Downtown",
        "city": "Testville",
        "state": "CA",
        "postal_code": "12345-678",
        "country": "US"
    },
    "currency": "BRL",
    "installment_value": 100.00,
    "due_date": "2025-12-31",
    "description": "First subscription payment",
    "type_charge": "credit_card",
    "card_name": "John Doe",
    "card_number": "4111111111111111",
    "card_expiry_month": "12",
    "card_expiry_year": "2030",
    "card_cvv": "123",
    "subscription": {
      "external_recurrence": true,
      "initiated_transaction_indicator_category": "C1" 
    },
    "webhook_url": "https://webhook.example.com/payment-status",
    "redirect_url": "https://merchant.example.com/thank-you"
}

{
    "wallet_uuid": "00000000-0000-0000-0000-000000000000",
    "merchant_id": "11111111-1111-1111-1111-111111111111",
    "payer_name": "John Doe",
    "payer_tax_id": "38899334821",
    "payer_email": "[email protected]",
    "payer_cell_phone": "+155599999999",
    "items": [
        {
            "name": "Test Product",
            "description": "Sample",
            "quantity": 1,
            "total_amount": 100.00,
            "unit_amount": 100.00,
            "sku": "TEST-SKU-001",
            "code": "TEST-CODE-001"
        }
    ],
    "payer_address": {
        "street": "Test Avenue",
        "address_number": "123",
        "complement": "Suite 456",
        "neighborhood": "Downtown",
        "city": "Testville",
        "state": "CA",
        "postal_code": "12345-678",
        "country": "US"
    },
    "currency": "BRL",
    "installment_value": 100.00,
    "due_date": "2025-12-31",
    "description": "First subscription payment",
    "type_charge": "credit_card",
    "card_name": "John Doe",
    "card_number": "4111111111111111", // Dpan network Token
    "card_cryptogram": "abcdefghijklmnopqrstuvw==", // criptograma (ex.: TAVV/CAVV)
    "card_expiry_month": "12",
    "card_expiry_year": "2030",
    "card_cvv": "123", // not mandatory
    "subscription": {
      "external_recurrence": true,
      "initiated_transaction_indicator_category": "C1" 
    },
    "webhook_url": "https://webhook.example.com/payment-status",
    "redirect_url": "https://merchant.example.com/thank-you"
}

Future recurring charges (merchant‑initiated)

{
    "wallet_uuid": "00000000-0000-0000-0000-000000000000",
    "merchant_id": "11111111-1111-1111-1111-111111111111",
    "payer_name": "John Doe",
    "payer_tax_id": "38899334821",
    "payer_email": "[email protected]",
    "payer_cell_phone": "+155599999999",
    "items": [
        {
            "name": "Test Product",
            "description": "Sample",
            "quantity": 1,
            "total_amount": 100.00,
            "unit_amount": 100.00,
            "sku": "TEST-SKU-001",
            "code": "TEST-CODE-001"
        }
    ],
    "payer_address": {
        "street": "Test Avenue",
        "address_number": "123",
        "complement": "Suite 456",
        "neighborhood": "Downtown",
        "city": "Testville",
        "state": "CA",
        "postal_code": "12345-678",
        "country": "US"
    },
    "currency": "BRL",
    "installment_value": 100.00,
    "due_date": "2025-12-31",
    "description": "Recurring subscription payment",
    "type_charge": "credit_card",
    "card_name": "John Doe",
    "card_number": "4111111111111111",
    "card_expiry_month": "12",
    "card_expiry_year": "2030",
    "card_cvv": "123",
    "subscription": {
      "external_recurrence": true,
      "initiated_transaction_indicator_category": "M1" 
    },
    "webhook_url": "https://webhook.example.com/payment-status",
    "redirect_url": "https://merchant.example.com/thank-you"
}
{
    "wallet_uuid": "00000000-0000-0000-0000-000000000000",
    "merchant_id": "11111111-1111-1111-1111-111111111111",
    "payer_name": "John Doe",
    "payer_tax_id": "38899334821",
    "payer_email": "[email protected]",
    "payer_cell_phone": "+155599999999",
    "items": [
        {
            "name": "Test Product",
            "description": "Sample",
            "quantity": 1,
            "total_amount": 100.00,
            "unit_amount": 100.00,
            "sku": "TEST-SKU-001",
            "code": "TEST-CODE-001"
        }
    ],
    "payer_address": {
        "street": "Test Avenue",
        "address_number": "123",
        "complement": "Suite 456",
        "neighborhood": "Downtown",
        "city": "Testville",
        "state": "CA",
        "postal_code": "12345-678",
        "country": "US"
    },
    "currency": "BRL",
    "installment_value": 100.00,
    "due_date": "2025-12-31",
    "description": "Recurring subscription payment",
    "type_charge": "credit_card",
    "card_name": "John Doe",
    "card_number": "4111111111111111", // Dpan network Token
    "card_cryptogram": "abcdefghijklmnopqrstuvw==", // criptograma (ex.: TAVV/CAVV)
    "card_expiry_month": "12",
    "card_expiry_year": "2030",
    "card_cvv": "123", // not mandatory
    "subscription": {
      "external_recurrence": true,
      "initiated_transaction_indicator_category": "M1" 
    },
    "webhook_url": "https://webhook.example.com/payment-status",
    "redirect_url": "https://merchant.example.com/thank-you"
}

🧾 Creating New Charges (Internal Recurrence)


🌀 Supported Billing Cycles

CycleDescription
weeklyEvery 7 days
biweeklyEvery 14 days
monthlyEvery month
quarterlyEvery 3 months
semiannuallyEvery 6 months
yearlyEvery year

🔄 Subscription Status Lifecycle

StatusDescription
pendingInitial payment pending
activeSubscription active
cancelledManually cancelled
errorLast charge attempt failed
expiredEnd date reached or cycle failure

Creating New Charges

{
    "wallet_uuid": "00000000-0000-0000-0000-000000000000",
    "merchant_id": "11111111-1111-1111-1111-111111111111",
    "payer_name": "John Doe",
    "payer_tax_id": "38899334821",
    "payer_email": "[email protected]",
    "payer_cell_phone": "+155599999999",
    "items": [
        {
            "name": "Test Product",
            "description": "Sample",
            "quantity": 1,
            "total_amount": 100.00,
            "unit_amount": 100.00,
            "sku": "TEST-SKU-001",
            "code": "TEST-CODE-001"
        }
    ],
    "payer_address": {
        "street": "Test Avenue",
        "address_number": "123",
        "complement": "Suite 456",
        "neighborhood": "Downtown",
        "city": "Testville",
        "state": "CA",
        "postal_code": "12345-678",
        "country": "US"
    },
    "currency": "BRL",
    "installment_value": 100.00,
    "due_date": "2025-12-31",
    "description": "First subscription payment",
    "type_charge": "credit_card",
    "card_name": "John Doe",
    "card_number": "4111111111111111",
    "card_expiry_month": "12",
    "card_expiry_year": "2030",
    "card_cvv": "123",
    "subscription": {
      "cycle": "monthly",
      "end_date": "2025-07-30"
    },
    "webhook_url": "https://webhook.example.com/payment-status",
    "redirect_url": "https://merchant.example.com/thank-you"
}

🔍 Retrieve Subscription

GET /api/v1/bank/wallet/subscription/?wallet_uuid={WALLET_UUID}&subscription_uuid={SUBSCRIPTION_UUID}
{
  "subscription_uuid": "b13216d0-1054-4353-9c47-ef12824e262a",
  "cycle": "monthly",
  "end_date": "2025-07-30",
  "status": "active",
  "next_due_date": "2025-07-30",
  "charges": [
    {
      "charge_uuid": "e7a22849-5a1b-41c8-b244-f7b8f2acfa1f",
      "value": 20,
      "currency": "BRL",
      "status": "confirmed"
    }
  ]
}

❌ Cancel Subscription

DELETE /api/v1/bank/wallet/subscription/{subscription_uuid}/cancel/{wallet_uuid}/
{
  "subscription_uuid": "b13216d0-1054-4353-9c47-ef12824e262a",
  "status": "cancelled"
}

ℹ️ Notes

  • All dates must use ISO 8601 (YYYY-MM-DD)
  • Only cards supporting recurring transactions are accepted
  • Webhooks are sent for every charge attempt
  • MIT Indicators (C1, M1) are only used in external recurrence

Updated 5 days ago