Subscription

This guide walks you through how to create, retrieve, and cancel credit card subscriptions using our API.

🔒 Only single-installment credit card payments are accepted.

sequenceDiagram
    autonumber
    participant Client
    participant API
    participant CardProcessor
    participant WebhookReceiver

    Client->>API: Create subscription (POST /charge/)
    API->>CardProcessor: Process initial charge
    CardProcessor-->>API: Charge confirmed
    API-->>Client: Return charge + subscription info
    API-->>WebhookReceiver: Notify successful charge

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

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

🌀 Supported Cycles:

Option	Description
`weekly`	Every 7 days
`biweekly`	Every 14 days
`monthly`	Every month
`quarterly`	Every 3 months
`semiannually`	Every 6 months
`yearly`	Every year

🔄 Subscription Status Lifecycle

Status	Description
`pending`	Subscription created but not yet paid (waiting for the first successful charge).
`active`	Subscription is active. The initial payment was completed successfully.
`cancelled`	Subscription has been manually cancelled. No further charges will be generated.
`error`	A failure occurred during a charge attempt (e.g., card declined, technical issue).
`expired`	The subscription reached the defined `end_date` or failed to process any charge within cycle.

🧾 Example Request Payload

{
  "wallet_uuid": "00000000-0000-0000-0000-000000000000",
  "merchant_id": "11111111-1111-1111-1111-111111111111",
  "payer_name": "John Doe",
  "payer_email": "[email protected]",
  "payer_cell_phone": "+5511999999999",
  "subscription": {
    "cycle": "monthly",
    "end_date": "2025-07-30"
  },
  "payer_address": {
    "street": "Sample Street",
    "address_number": "123",
    "complement": "Apt 101",
    "neighborhood": "Sample Neighborhood",
    "city": "Sample City",
    "state": "SP",
    "postal_code": "00000-000",
    "country": "BR"
  },
  "currency": "BRL",
  "installment_value": 100,
  "installment_count": 1,
  "due_date": "2025-12-31",
  "description": "Sample Subscription",
  "type_charge": "credit_card",
  "card_name": "John Doe",
  "card_number": "4111111111111111",
  "card_expiry_month": "12",
  "card_expiry_year": "2030",
  "card_cvv": "123",
  "webhook_url": "https://webhook-test.com/sample-webhook"
}

{
  "charge_uuid": "c950b2e5-95f8-40c2-b58e-e3c66c6cc100",
  "local_currency": 100,
  "currency": "BRL",
  "usd_currency": 17.93,
  "eur_currency": 15.72,
  "type": "credit_card",
  "date": "2025-07-30",
  "description": "Sample Subscription",
  "due_date": "2026-01-30",
  "status": "confirmed",
  "installment_count": 1,
  "installments": [
    {
      "local_currency": 100,
      "currency": "BRL",
      "usd_currency": 17.93,
      "eur_currency": 15.72,
      "due_date": "2026-01-30",
      "status": "confirmed",
      "installment_number": 1
    }
  ],
  "charge_payment_url": "https://pay.a55.tech/charge/c950b2e5-95f8-40c2-b58e-e3c66c6cc100",
  "subscription": {
    "subscription_uuid": "96b95c56-34f0-48c0-93e9-ac5fc6d3f3d5",
    "cycle": "monthly",
    "end_date": "2025-07-30",
    "status": "active",
    "next_due_date": "2025-08-30"
  }
}

🔍 Retrieve Subscription

Endpoint: GET /api/v1/bank/wallet/subscription/?wallet_uuid={WALLET_UUID}&subscription_uuid={SUBSCRIPTION_UUID}

📤 Response

{
  "subscription_uuid": "b13216d0-1054-4353-9c47-ef12824e262a",
  "cycle": "monthly",
  "end_date": "2025-07-30",
  "status": "active",
  "description": "Teste de Subscription",
  "next_due_date": "2025-07-30",
  "charges": [
    {
      "charge_uuid": "e7a22849-5a1b-41c8-b244-f7b8f2acfa1f",
      "value": 20,
      "currency": "BRL",
      "date": "2025-06-30",
      "status": "confirmed"
    },
    {
      "charge_uuid": "b9258ce8-5b39-414c-8c1a-9ef66048289c",
      "value": 20,
      "currency": "BRL",
      "date": "2025-05-30",
      "status": "confirmed"
    }
  ]
}

❌ Cancel Subscription

Endpoint: DELETE /api/v1/bank/wallet/subscription/{subscription_uuid}/cancel/{wallet_uuid}/

📤 Response

{
  "subscription_uuid": "b13216d0-1054-4353-9c47-ef12824e262a",
  "status": "cancelled"
}

ℹ️ Notes
All dates must be in ISO 8601 format: YYYY-MM-DD.

Only credit cards that support online recurring transactions are accepted.

The webhook will notify your system of each successful charge.