Integração

Assinaturas

Cobrança recorrente do seu cliente (plano mensal, anual…) sobre a recorrência do provedor. A assinatura gera as cobranças; o seu sistema nunca cria cobrança de assinatura por conta própria.

Criar a assinatura

POST /v1/subscriptions

{
  "customerId": "cus_01JDY8A1B2C3D4E5F6G7H8J9KA",
  "method": "PIX",
  "amountCents": "9900",
  "cycle": "MONTHLY",
  "nextDueDate": "2026-12-10",
  "description": "Plano Órbita Pro",
  "externalReference": "assinatura-42"
}

method: PIX, BOLETO ou CREDIT_CARD. Ciclos: WEEKLY, BIWEEKLY, MONTHLY, BIMONTHLY, QUARTERLY, SEMIANNUALLY, YEARLY. Opcionais: endDate, maxPayments, description, externalReference.
A resposta é 202 com a operação CREATE_SUBSCRIPTION; o resourceId é a assinatura, que começa em PENDING e passa a ACTIVE quando o provedor confirma.
Cartão exige um cartão capturado com uso SUBSCRIPTION e o consentimento (consent.displayedTermsHash, SHA-256 dos termos exibidos: método, valor, ciclo e datas), conferido no servidor.

O provedor gera cada cobrança do ciclo (com antecedência ao vencimento). A plataforma vincula cada uma à assinatura uma única vez, mesmo com webhook repetido, fora de ordem ou perdido (uma consulta periódica busca as que faltarem). Cada cobrança tem um pedido próprio, com fulfillmentPolicy: ON_FULLY_PAID.

subscription.updated avisa quando uma cobrança nasce (data.paymentId) e quando a assinatura muda de situação.
GET /v1/subscriptions/{id}/payments lista as cobranças com o orderId de cada uma: guarde o vínculo pedido → assinatura no seu sistema.
order.payment_completed do pedido do ciclo confirma que aquele ciclo foi pago. Se ele chegar antes do vínculo, consulte as cobranças das assinaturas ativas.

Situações da assinatura
status	Significado
`PENDING`	Criação aceita, aguardando o provedor.
`ACTIVE`	Gerando cobranças.
`PAUSED`	Pausada a pedido: não gera novas cobranças; as existentes continuam valendo.
`INACTIVE`	Inativada pelo provedor.
`EXPIRED`	Chegou ao fim (data final ou número máximo de cobranças).
`BLOCKED_SPLIT`	Divergência de split no provedor: aguarda a equipe.
`CANCELLED`	Cancelada. Cobranças já geradas não são canceladas automaticamente.
`FAILED`	A criação foi recusada pelo provedor.

Alterar, pausar, retomar e cancelar

Toda mudança leva a versão esperada (expectedVersion) e responde 202; só uma alteração por vez (SUBSCRIPTION_OPERATION_IN_PROGRESS). Versão antiga responde 409 VERSION_CONFLICT.
PATCH muda valor, ciclo, vencimento ou descrição e vale só para as próximas cobranças. A tarifa fica congelada na versão da assinatura até refreshFeePolicy: true, que também só afeta as próximas.
pause (com motivo) e resume (com novo vencimento); cancel encerra no provedor.
Guarde a versão esperada junto com a intenção: repetir com a mesma Idempotency-Key exige o mesmo corpo.

Rotas

Rotas de assinaturas
Rota	O que faz	Situação
POST /v1/subscriptions	Criar assinatura SaaS	Implementada
GET /v1/subscriptions	Listar assinaturas (com MRR)	Implementada
GET /v1/subscriptions/{id}	Consultar assinatura	Implementada
PATCH /v1/subscriptions/{id}	Alterar valor, ciclo ou vencimento (só cobranças futuras)	Implementada
POST /v1/subscriptions/{id}/cancel	Cancelar assinatura	Implementada
POST /v1/subscriptions/{id}/pause	Pausar (para de gerar cobranças; existentes mantidas)	Implementada
POST /v1/subscriptions/{id}/resume	Retomar com novo vencimento	Implementada
GET /v1/subscriptions/{id}/payments	Cobranças geradas pela assinatura	Implementada

A integração de referência do Agenda Expert mostra o plano mensal do profissional por Pix: assinatura, ciclos pagos e cancelamento idempotente.

Próximo: Estornos e disputas

Criar a assinatura

Cobranças geradas

Alterar, pausar, retomar e cancelar

Rotas