Criar assinatura

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

Assinatura via endpoint de cobrança

As assinaturas são criadas incluindo um objeto subscription no corpo da requisição de Criar cobrança. A primeira cobrança é processada imediatamente, e as cobranças subsequentes são criadas automaticamente com base no ciclo de cobrança.

Cabeçalhos da requisição

Cabeçalho	Valor	Obrigatório
`Authorization`	`Bearer {A55_ACCESS_TOKEN}`	Sim
`Content-Type`	`application/json`	Sim
`Idempotency-Key`	UUID v4	Recomendado

Corpo da requisição

Todos os campos de Criar cobrança se aplicam, além do objeto subscription:

Campo	Tipo	Obrigatório	Descrição
`type_charge`	string	Sim	Deve ser `credit_card` ou `debit_card`
`subscription.cycle`	string	Sim	Ciclo de cobrança — veja a tabela abaixo
`subscription.end_date`	string	Não	Data final `YYYY-MM-DD` (omita para indefinido)

Ciclos de cobrança

Ciclo	Descrição	Frequência de cobrança
`weekly`	A cada 7 dias	52 cobranças/ano
`biweekly`	A cada 14 dias	26 cobranças/ano
`monthly`	Mesmo dia de cada mês	12 cobranças/ano
`quarterly`	A cada 3 meses	4 cobranças/ano
`semiannually`	A cada 6 meses	2 cobranças/ano
`yearly`	Uma vez por ano	1 cobrança/ano

Campos da resposta

Todos os campos de resposta de Criar cobrança, além de:

Campo	Tipo	Descrição
`subscription.subscription_uuid`	string	Identificador único da assinatura
`subscription.cycle`	string	Ciclo de cobrança
`subscription.status`	string	`active` na criação
`subscription.next_charge_date`	string	Data da próxima cobrança automática
`subscription.end_date`	string	Data de término da assinatura (null se indefinida)

Códigos de status HTTP

Status	Descrição
200	Assinatura criada e primeira cobrança processada
400	Ciclo de assinatura inválido ou campos obrigatórios ausentes
401	Token Bearer inválido ou expirado
403	Permissões insuficientes para esta carteira
404	Carteira não encontrada
409	Duplicado (mesma Idempotency-Key)
422	Erro de validação (cartão inválido, ciclo, datas)
429	Limite de requisições excedido
500	Erro interno do servidor — tente novamente com backoff exponencial

Exemplos de código

cURL
Python
Node.js

curl -s -X POST https://core-manager.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"
    }
  }'

import requests
import os

token = os.environ["A55_ACCESS_TOKEN"]
base = os.environ.get("A55_API_URL", "https://core-manager.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}")

const token = process.env.A55_ACCESS_TOKEN;
const base = process.env.A55_API_URL || "https://core-manager.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);
}

Exemplo de resposta de erro

{
  "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"
    }
  ]
}

Consultar assinatura →Veja os detalhes da assinatura e o histórico de cobranças.Cancelar assinatura →Interrompa cobranças futuras de uma assinatura.Webhooks →Receba notificações para cada cobrança recorrente.

Cabeçalhos da requisição​

Corpo da requisição​

Ciclos de cobrança​

Campos da resposta​

Códigos de status HTTP​

Exemplos de código​

Exemplo de resposta de erro​