Assinaturas

Quick Reference

WhatCobrança recorrente com cartão de crédito

WhyAutomatize ciclos de faturamento — geridos pela A55 ou pelo comerciante

DifficultyIntermediate

PrerequisitesAutenticação → Criar cobrança

Crie cobranças recorrentes incluindo um objeto subscription na requisição de cobrança. A A55 suporta duas estratégias de recorrência dependendo do nível de controle que você precisa.

Parcela única apenas

Somente transações de cartão de crédito em parcela única são permitidas para assinaturas.

Por que assinaturas

Benefício	Detalhe
Receita recorrente	Automatize o faturamento sem criação manual de cobranças
Ciclos flexíveis	Semanal, quinzenal, mensal, trimestral, semestral, anual
Conformidade CIT/MIT	Indicadores corretos de transação iniciada conforme regras das bandeiras
Três modos de entrada de cartão	PAN bruto, DPAN + criptograma, ou token A55
Notificações por webhook	Eventos para cada tentativa de cobrança e mudança de ciclo de vida

Modelos de recorrência

Modelo	Quem agenda as cobranças	Indicadores MIT	Gestão de retentativas
Interna (controlada pela A55)	A55 gera cobranças automaticamente por ciclo	Não utilizado	A55 gerencia
Externa (controlada pelo comerciante)	Comerciante dispara cada cobrança	C1 / M1 obrigatórios	Comerciante gerencia

Recorrência interna (controlada pela A55)

A A55 cria cobranças automaticamente conforme o ciclo de faturamento. Esforço mínimo do comerciante.

Ciclos de faturamento

Ciclo	Intervalo
`weekly`	A cada 7 dias
`biweekly`	A cada 14 dias
`monthly`	Todo mês
`quarterly`	A cada 3 meses
`semiannually`	A cada 6 meses
`yearly`	Todo ano

Criar assinatura (interna)

JSON body

{
  "wallet_uuid": "00000000-0000-4000-8000-000000000001",
  "merchant_id": "11111111-1111-1111-1111-111111111111",
  "payer_name": "Jane Doe",
  "payer_tax_id": "12345678901",
  "payer_email": "jane@example.com",
  "payer_cell_phone": "+5511999999999",
  "items": [{"name": "Premium Plan", "quantity": 1, "total_amount": 99.90, "unit_amount": 99.90}],
  "currency": "BRL",
  "installment_value": 99.90,
  "due_date": "2026-12-31",
  "description": "Monthly premium subscription",
  "type_charge": "credit_card",
  "card_name": "JANE DOE",
  "card_number": "4111111111111111",
  "card_expiry_month": "12",
  "card_expiry_year": "2030",
  "card_cvv": "123",
  "subscription": {
    "cycle": "monthly",
    "end_date": "2027-06-30"
  },
  "webhook_url": "https://merchant.example/webhooks/a55"
}

Recorrência externa (controlada pelo comerciante)

O comerciante controla o momento de cada cobrança. Necessário para faturamento orientado por CRM, valores variáveis ou lógica de retentativa customizada.

Indicadores de transação iniciada

Indicador	Significado	Quando
`C1`	Transação iniciada pelo cliente	Primeiro pagamento da assinatura (portador presente)
`M1`	Cobrança recorrente iniciada pelo comerciante	Todos os pagamentos subsequentes

Primeiro pagamento (CIT)

Raw PAN
A55 Token
DPAN + Cryptogram

{
  "wallet_uuid": "00000000-0000-4000-8000-000000000001",
  "merchant_id": "11111111-1111-1111-1111-111111111111",
  "payer_name": "Jane Doe",
  "payer_tax_id": "12345678901",
  "payer_email": "jane@example.com",
  "currency": "BRL",
  "installment_value": 99.90,
  "type_charge": "credit_card",
  "card_name": "JANE 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://merchant.example/webhooks/a55"
}

{
  "wallet_uuid": "00000000-0000-4000-8000-000000000001",
  "merchant_id": "11111111-1111-1111-1111-111111111111",
  "payer_name": "Jane Doe",
  "currency": "BRL",
  "installment_value": 99.90,
  "type_charge": "credit_card",
  "card_token": "7c2a9b6e-4f6a-4e3d-9d8b-0e3f9c6b1a42",
  "subscription": {
    "external_recurrence": true,
    "initiated_transaction_indicator_category": "C1"
  },
  "webhook_url": "https://merchant.example/webhooks/a55"
}

{
  "wallet_uuid": "00000000-0000-4000-8000-000000000001",
  "merchant_id": "11111111-1111-1111-1111-111111111111",
  "payer_name": "Jane Doe",
  "currency": "BRL",
  "installment_value": 99.90,
  "type_charge": "credit_card",
  "card_number": "4500000000000000",
  "card_cryptogram": "AAABBBCCCDDDEEFF==",
  "card_expiry_month": "12",
  "card_expiry_year": "2030",
  "subscription": {
    "external_recurrence": true,
    "initiated_transaction_indicator_category": "C1"
  },
  "webhook_url": "https://merchant.example/webhooks/a55"
}

Cobranças subsequentes (MIT)

Referencie o cit_charge_uuid do pagamento inicial e altere para M1:

{
  "wallet_uuid": "00000000-0000-4000-8000-000000000001",
  "merchant_id": "11111111-1111-1111-1111-111111111111",
  "payer_name": "Jane Doe",
  "currency": "BRL",
  "installment_value": 99.90,
  "type_charge": "credit_card",
  "card_token": "7c2a9b6e-4f6a-4e3d-9d8b-0e3f9c6b1a42",
  "subscription": {
    "cit_charge_uuid": "ce4ccc7f-d3f7-46eb-a912-d4a6bc0423d1",
    "external_recurrence": true,
    "initiated_transaction_indicator_category": "M1"
  },
  "webhook_url": "https://merchant.example/webhooks/a55"
}

Ciclo de vida do status da assinatura

Status	Descrição
`pending`	Pagamento inicial ainda não confirmado
`active`	Assinatura ativa, cobranças sendo geradas
`error`	Última tentativa de cobrança falhou
`cancelled`	Cancelada manualmente pelo comerciante ou cliente
`expired`	Data final atingida ou falhas de ciclo esgotadas

Consultar assinatura

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": "2027-06-30",
  "status": "active",
  "next_due_date": "2026-04-30",
  "charges": [
    {
      "charge_uuid": "e7a22849-5a1b-41c8-b244-f7b8f2acfa1f",
      "value": 99.90,
      "currency": "BRL",
      "status": "confirmed"
    }
  ]
}

Cancelar assinatura

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

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

Cobranças pendentes

O cancelamento interrompe futuros ciclos de faturamento. Cobranças já liquidadas permanecem conforme seu contrato. Reconcilie eventos de webhook e atualize os direitos de acesso adequadamente.

Zero Auth →Valide cartões antes de armazenar.Tokenização de cartão →Tokens para renovações de cartão em arquivo.Webhooks →Inscreva-se em eventos de assinatura.

Quick Reference

Por que assinaturas​

Modelos de recorrência​

Recorrência interna (controlada pela A55)​

Ciclos de faturamento​

Criar assinatura (interna)​

Recorrência externa (controlada pelo comerciante)​

Indicadores de transação iniciada​

Primeiro pagamento (CIT)​

Cobranças subsequentes (MIT)​

Ciclo de vida do status da assinatura​

Consultar assinatura​

Cancelar assinatura​