Assinatura por cartão

A assinatura por cartão usa os mesmos endpoints do Pix Automático. O que muda é o plano: com paymentMethods: ["CREDIT_CARD"], a criação devolve um link de checkout no lugar do código Pix. O pagador cadastra o cartão nessa página; os dados do cartão não passam pela Gates2b.

O primeiro ciclo é cobrado quando o pagador conclui o checkout; os seguintes, no mesmo dia a cada período (MONTHLY: todo mês nessa data). Se algum aviso entre a operadora e a Gates2b se perder, o último passo, a reconciliação, coloca o registro de volta em ordem.

1. Criar o plano e a assinaturaCopiar link da seção

Crie um plano de cartão em Criar plano:

{
  "name": "Plano Mensal Premium",
  "amountCents": 9990,
  "frequency": "MONTHLY",
  "type": "RECURRENT",
  "paymentMethods": ["CREDIT_CARD"]
}

Depois chame Criar assinatura. Do cliente, o cartão exige só name e email; documento e endereço são opcionais, o que permite assinante de fora do Brasil.

{
  "planId": "01JB7Y9C8D7E6F5G4H3J2K1M0N",
  "dayGenerateCharge": 25,
  "customer": {
    "name": "Maria Souza",
    "email": "cliente@example.com"
  },
  "gatewayOptions": {
    "redirectUrl": "https://sualoja.example.com/assinatura/obrigado",
    "cancelUrl": "https://sualoja.example.com/assinatura/cancelada"
  }
}

A assinatura nasce em AWAITING_PAYER_AUTHORIZATION e nada é cobrado nesse momento. A resposta traz o link em activation.checkout.url:

"activation": {
  "status": "open",
  "pixRecurring": null,
  "checkout": {
    "url": "https://checkout.example.com/session/a1B2c3D4",
    "expiresAt": 1780059900
  },
  "nextBillingAt": null,
  "postCancelCycles": null
}

Erros na criaçãoCopiar link da seção

Assinatura de cartão nunca fica em PENDING_CUSTOMER: cadastro incompleto é recusado na criação.

2. Autorização pelo pagadorCopiar link da seção

Envie activation.checkout.url ao pagador. Enquanto ele não conclui o checkout, a assinatura fica em AWAITING_PAYER_AUTHORIZATION e needsPayerAuthorization vem true.

A sessão expira em 24 horas e não é renovada. Se o pagador não concluir a tempo, cancele a assinatura e crie outra.

Depois do checkout, o pagador volta para gatewayOptions.redirectUrl; se desistir, para gatewayOptions.cancelUrl. Sem essas URLs, valem os endereços padrão da conta. cancelUrl não herda redirectUrl, para quem desistiu não cair na sua página de sucesso. As URLs ficam gravadas na assinatura.

3. AtivaçãoCopiar link da seção

Quando o pagador conclui o checkout, a assinatura vai para ACTIVE e activation.nextBillingAt passa a trazer a data da próxima cobrança.

O ciclo conta a partir do dia em que o pagador concluiu o checkout, não do dayGenerateCharge. No cartão, dayGenerateCharge é só informativo: para mostrar a próxima cobrança, use activation.nextBillingAt.

Se o aviso de conclusão do checkout se perder, a assinatura já cobra o cartão mas continua em AWAITING_PAYER_AUTHORIZATION do nosso lado. A reconciliação corrige isso.

4. Ciclos de cobrançaCopiar link da seção

A cada ciclo pago no cartão:

• uma cobrança PAID é criada, com o externalReference da assinatura. O mesmo ciclo nunca gera duas cobranças;
• o valor é creditado no seu saldo e o evento charge.paid é enviado às suas inscrições de webhook;
• ciclos de valor zero (período de teste, ajuste proporcional) não geram cobrança.

Quando um ciclo falha, a operadora do cartão faz as novas tentativas. Nesta versão, a falha de um ciclo não muda o status da assinatura nem gera aviso.

5. CancelamentoCopiar link da seção

Uma assinatura chega a CANCELLED por três caminhos:

• Por você: Cancelar assinatura.
• Pelo pagador, no portal do assinante.
• Pela operadora, quando as tentativas de cobrança se esgotam ou o contrato é encerrado fora da Gates2b. Se esse aviso se perder, a assinatura segue ACTIVE do nosso lado, com uma próxima cobrança que não vai acontecer.

CANCELLED é definitivo: tentar reativar responde 409.

Ciclos cobrados depois do cancelamentoCopiar link da seção

Se o cartão for cobrado depois do cancelamento, o ciclo não vira cobrança nem crédito no saldo: ele fica registrado para reembolso e o cancelamento é reenviado à operadora. O resumo aparece em activation.postCancelCycles:

"postCancelCycles": {
  "count": 1,
  "lastAt": "2026-07-28T13:05:00.000Z",
  "lastAmountCents": 9990,
  "totalAmountCents": 9990
}

O reembolso desses ciclos é manual e não é feito por esta API.

Colocando a assinatura de volta em sincroniaCopiar link da seção

Todos os casos abaixo se resolvem com Reconciliar assinatura. Ela pode ser chamada quantas vezes for preciso, até 10 por minuto.

Se a listagem de ciclos falhar durante a reconciliação, o cancelamento ainda é enviado, mas postCancelInvoices volta 0. Confira errors antes de concluir que não houve cobrança indevida.