Skip to main content
Assinaturas são criadas a partir de uma oferta com cadência recorrente (mensal, anual…). A primeira cobrança acontece no checkout; as demais são agendadas automaticamente por ciclo, com faturas que você pode consultar por API.

Ciclo de vida

Cada transição gera um webhook de assinatura.
  • Criação: comprador assina pelo link de pagamento (ou sessão de checkout via API). O token de cartão recorrente é criado pelo provedor no primeiro pagamento.
  • Cobranças: cada ciclo gera uma fatura com o valor da oferta no momento da assinatura. PIX recorrente usa PIX Automático.
  • Cancelamento: pelo próprio comprador no portal do cliente ou por você via API.

Consultar e cancelar

O cancelamento interrompe as renovações na hora: nenhuma nova fatura é gerada e as já pagas não são afetadas. O comprador mantém acesso até accessUntil, quando a assinatura passa a EXPIRED.
  • 200 com status: CANCELED: cancelada.
  • 202 com status: CANCELLATION_REQUESTED: a Korbit está encerrando a autorização recorrente no meio de pagamento. A confirmação chega pelo webhook subscription.canceled.v1.
Se o cancelamento vier acompanhado de pedido de reembolso ou contestação, acompanhe também os eventos refund.* e dispute.*.

Webhooks de assinatura

Assine os eventos subscription.* para manter seu sistema em dia sem polling: liberar acesso na ativação, registrar renovações, avisar o cliente quando uma cobrança falhar e remover o acesso quando a assinatura expirar. Payload, motivos e exemplos estão no Catálogo de eventos.

Faturas

GET /v1/subscriptions/{id}/invoices retorna as faturas por ciclo, com valor, data e estado da cobrança correspondente — a base da sua conciliação de recorrência.

Portal do cliente

O comprador pode gerenciar a assinatura (cancelar, trocar de plano) no portal hospedado da Korbit. Você controla o acesso criando e revogando sessões de portal por cliente:
Sessões de portal são links únicos, de curta duração e revogáveis — nunca armazene o token do portal no seu backend.