Create subscription

POST/api/v1/bank/wallet/charge/Bearer Token

Subscription via charge endpoint

Subscriptions are created by including a subscription object in the Create charge request body. The first charge is processed immediately, and subsequent charges are created automatically based on the billing cycle.

---

Request headers

Header	Value	Required
Authorization	Bearer {A55_ACCESS_TOKEN}	Yes
Content-Type	application/json	Yes
Idempotency-Key	UUID v4	Recommended

Request body

All Create charge fields apply, plus the subscription object:

Field	Type	Required	Description
type_charge	string	Yes	Must be credit_card or debit_card
subscription.cycle	string	Yes	Billing cycle — see table below
subscription.end_date	string	No	End date YYYY-MM-DD (omit for indefinite)

Billing cycles

Cycle	Description	Charge frequency
weekly	Every 7 days	52 charges/year
biweekly	Every 14 days	26 charges/year
monthly	Same day each month	12 charges/year
quarterly	Every 3 months	4 charges/year
semiannually	Every 6 months	2 charges/year
yearly	Once per year	1 charge/year

---

Response fields

All Create charge response fields, plus:

Field	Type	Description
subscription.subscription_uuid	string	Unique subscription identifier
subscription.cycle	string	Billing cycle
subscription.status	string	active on creation
subscription.next_charge_date	string	Next automatic charge date
subscription.end_date	string	Subscription end date (null if indefinite)

---

HTTP status codes

Status	Description
200	Subscription created and first charge processed
400	Invalid subscription cycle or missing required fields
401	Invalid or expired Bearer token
403	Insufficient permissions for this wallet
404	Wallet not found
409	Duplicate (same Idempotency-Key)
422	Validation error (invalid card, cycle, dates)
429	Rate limit exceeded
500	Internal server error — retry with exponential backoff

---

Code examples

cURL

curl -s -X POST https://sandbox.api.a55.tech/api/v1/bank/wallet/charge/ \
  -H "Authorization: Bearer $A55_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: aa0e8400-e29b-41d4-a716-446655440005" \
  -d '{
    "wallet_uuid": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "merchant_id": "11111111-1111-1111-1111-111111111111",
    "payer_name": "Maria Silva",
    "payer_email": "maria@example.com",
    "payer_tax_id": "123.456.789-09",
    "payer_cell_phone": "+5511999999999",
    "installment_value": 49.90,
    "installment_count": 1,
    "currency": "BRL",
    "due_date": "2026-12-31",
    "description": "Premium Plan — Monthly subscription",
    "type_charge": "credit_card",
    "card_number": "4024007153763191",
    "card_name": "MARIA SILVA",
    "card_expiry_month": "12",
    "card_expiry_year": "2030",
    "card_cvv": "123",
    "subscription": {
      "cycle": "monthly",
      "end_date": "2027-12-31"
    },
    "webhook_url": "https://your-app.com/webhooks/a55",
    "payer_address": {
      "street": "Av. Paulista",
      "address_number": "1000",
      "complement": "Sala 101",
      "neighborhood": "Bela Vista",
      "city": "São Paulo",
      "state": "SP",
      "postal_code": "01310-100",
      "country": "BR"
    }
  }'

Python

import requests
import os

token = os.environ["A55_ACCESS_TOKEN"]
base = os.environ.get("A55_API_URL", "https://sandbox.api.a55.tech")

try:
    response = requests.post(
        f"{base}/api/v1/bank/wallet/charge/",
        json={
            "wallet_uuid": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
            "merchant_id": "11111111-1111-1111-1111-111111111111",
            "payer_name": "Maria Silva",
            "payer_email": "maria@example.com",
            "payer_tax_id": "123.456.789-09",
            "payer_cell_phone": "+5511999999999",
            "installment_value": 49.90,
            "installment_count": 1,
            "currency": "BRL",
            "due_date": "2026-12-31",
            "description": "Premium Plan — Monthly subscription",
            "type_charge": "credit_card",
            "card_number": "4024007153763191",
            "card_name": "MARIA SILVA",
            "card_expiry_month": "12",
            "card_expiry_year": "2030",
            "card_cvv": "123",
            "subscription": {
                "cycle": "monthly",
                "end_date": "2027-12-31",
            },
            "webhook_url": "https://your-app.com/webhooks/a55",
            "payer_address": {
                "street": "Av. Paulista",
                "address_number": "1000",
                "complement": "Sala 101",
                "neighborhood": "Bela Vista",
                "city": "São Paulo",
                "state": "SP",
                "postal_code": "01310-100",
                "country": "BR",
            },
        },
        headers={
            "Authorization": f"Bearer {token}",
            "Content-Type": "application/json",
            "Idempotency-Key": "aa0e8400-e29b-41d4-a716-446655440005",
        },
    )
    response.raise_for_status()
    charge = response.json()
    sub = charge.get("subscription", {})
    print(f"Charge: {charge['charge_uuid']} — Status: {charge['status']}")
    print(f"Subscription: {sub.get('subscription_uuid')} — Next: {sub.get('next_charge_date')}")
except requests.exceptions.HTTPError as e:
    print(f"HTTP {e.response.status_code}: {e.response.json()}")
except requests.exceptions.RequestException as e:
    print(f"Request failed: {e}")

Node.js

const token = process.env.A55_ACCESS_TOKEN;
const base = process.env.A55_API_URL || "https://sandbox.api.a55.tech";

try {
  const response = await fetch(`${base}/api/v1/bank/wallet/charge/`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${token}`,
      "Content-Type": "application/json",
      "Idempotency-Key": "aa0e8400-e29b-41d4-a716-446655440005",
    },
    body: JSON.stringify({
      wallet_uuid: "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      merchant_id: "11111111-1111-1111-1111-111111111111",
      payer_name: "Maria Silva",
      payer_email: "maria@example.com",
      payer_tax_id: "123.456.789-09",
      payer_cell_phone: "+5511999999999",
      installment_value: 49.90,
      installment_count: 1,
      currency: "BRL",
      due_date: "2026-12-31",
      description: "Premium Plan — Monthly subscription",
      type_charge: "credit_card",
      card_number: "4024007153763191",
      card_name: "MARIA SILVA",
      card_expiry_month: "12",
      card_expiry_year: "2030",
      card_cvv: "123",
      subscription: { cycle: "monthly", end_date: "2027-12-31" },
      webhook_url: "https://your-app.com/webhooks/a55",
      payer_address: {
        street: "Av. Paulista",
        address_number: "1000",
        complement: "Sala 101",
        neighborhood: "Bela Vista",
        city: "São Paulo",
        state: "SP",
        postal_code: "01310-100",
        country: "BR",
      },
    }),
  });

  if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
  const charge = await response.json();
  console.log(`Charge: ${charge.charge_uuid} — Status: ${charge.status}`);
  console.log(`Subscription: ${charge.subscription?.subscription_uuid} — Next: ${charge.subscription?.next_charge_date}`);
} catch (error) {
  console.error("Subscription creation failed:", error.message);
}

---

Error response example

{
  "charge_uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "error",
  "message": [
    {
      "code": "INVALID_SUBSCRIPTION_CYCLE",
      "source": "subscription",
      "description": "Cycle 'daily' is not supported. Use: weekly, biweekly, monthly, quarterly, semiannually, yearly"
    }
  ]
}

---

Get subscription →View subscription details and billing history.Cancel subscription →Stop future charges for a subscription.Webhooks →Receive notifications for each recurring charge.