Skip to main content
Para cobrar de forma recorrente na Z2Pay, você cria uma assinatura — ela gera uma fatura a cada ciclo, e cada fatura cobrada vira uma transação (visível no dashboard com origem billing).
Os exemplos desta seção usam a base de sandbox https://api.sandbox.z2pay.com/v1 e o header x-api-key com a sua chave de sandbox. Veja Autenticação e Ambientes.

​
O modelo: Plano → Preço → Assinatura → Fatura

A recorrência é construída a partir de quatro recursos encadeados. Entender essa cadeia é o primeiro passo para integrar.

Plano (Plan)

O catálogo da oferta recorrente: nome, código e os itens que a compõem. Nasce publicado (active), pode ser pausado (inactive, pelo painel) e arquivado (archived).

Preço (Price)

Uma versão de preço de um item do plano: define amount (em centavos) e a recurrence (a cada quanto cobra). Versionado — criar um novo Preço desativa o anterior da mesma moeda/recorrência.

Assinatura (Subscription)

Vincula um cliente a um plano (ou a itens avulsos). É o contrato vivo: tem status, método de pagamento padrão, data da próxima fatura e ciclos.

Fatura (Invoice)

O documento de cobrança de um ciclo. Nasce de uma assinatura, é cobrada e transiciona entre open, paid, past_due, etc.
Você não precisa criar um Plano para ter uma assinatura. É possível criar uma assinatura com itens avulsos (inline), informando description e unitAmount diretamente — nesse caso recurrence e currency passam a ser obrigatórios no corpo da assinatura. O caminho via Plano é o recomendado quando você vende a mesma oferta para muitos clientes.

​
Como os ciclos funcionam

Depois que a assinatura existe, o nosso agendador cuida do resto. A cada ciclo ele gera a próxima fatura, dispara a cobrança e atualiza o status da assinatura conforme o resultado.
1

Criação

Você cria a assinatura (POST /subscriptions). Sem trial nem adesão: com defaultPaymentMethodRef ela nasce active; sem forma de pagamento, nasce incomplete. Trial e adesão têm estados iniciais próprios — veja a tabela completa.
2

Geração da fatura

Por padrão (invoiceGenerationMode=just_in_time) o agendador gera uma fatura por ciclo. Em upfront, todas as maxCycles faturas são emitidas já na criação (cada uma com vencimento próprio).
3

Cobrança

Cobramos a forma de pagamento padrão da assinatura, e cada cobrança vira uma transação. Sem forma de pagamento definida, a fatura é emitida e fica aguardando — use o link público dela para o cliente pagar.
4

Próximo ciclo

Paga a fatura, o agendador avança a assinatura para o próximo ciclo e repete — até atingir maxCycles (se definido) ou até cancelamento.
Checkout como porta de entrada — além do POST /subscriptions, uma assinatura pode nascer de um link de Checkout com mode=subscription: o comprador paga a Session e a ativação da assinatura é automática após o pagamento — a 1ª fatura já nasce paga, sem nova cobrança. Com trial configurado, a assinatura nasce trialing e a cobrança do Checkout é apenas a validação do cartão, estornada automaticamente. A assinatura criada assim carrega o Link e a Session de origem no metadata — veja Assinaturas via Checkout.
Para testar ciclos sem esperar, use os recursos de simulação do sandbox. Veja Sandbox: simular e Ciclos e cobrança.

​
Onde ficam os endpoints

São 21 rotas, e cada recurso mantém o mapa das suas — com os campos, os exemplos e o playground: Todas exigem o header x-api-key.
A criação e as ações aceitam o header opcional Idempotency-Key. Reenviar a mesma requisição com a mesma chave devolve o mesmo resultado, sem duplicar a operação. Veja Convenções.

​
Ligar a fatura à transação

Toda cobrança da engine cria uma transação comum, das que aparecem em Transações. Três marcas permitem reconciliar as duas pontas: O mesmo par origin/billingInvoiceId vai no additionalInfo de cada pagamento da transação.
Nenhuma das três é garantia. referenceCode e additionalInfo são campos de entrada do POST /transactions — uma transação criada por você pode ter exatamente os mesmos valores. Elas servem para reconhecer uma cobrança da engine no meio das suas, não para provar de onde ela veio.Para saber se uma fatura foi paga, pergunte à fatura, não à transação: GET /invoices/{id} responde com status, paidAt, amountPaid e amountRemaining. Use a transação quando quiser os detalhes do processamento — gateway, parcelas, código de autorização.

​
Primeiro contato (sandbox)

Um GET rápido para confirmar que a sua chave de sandbox alcança a API e lista as assinaturas existentes (a lista vem vazia se você ainda não criou nenhuma).
Resposta (lista paginada):
Os campos e o formato exato da resposta de cada recurso estão documentados nas páginas de referência específicas. A resposta acima é ilustrativa para você reconhecer a forma da lista paginada — confira Assinaturas para o objeto completo.

​
Erros

Estes endpoints seguem o mesmo padrão de erro do resto da API. Status comuns nesta seção:
  • 404 — recurso não encontrado (assinatura, plano, preço ou cliente inexistente).
  • 409 — operação inválida para o estado atual (ex.: cancelar uma assinatura já cancelada, retomar uma assinatura que não está pausada, ou conflito de validação ao criar).
  • 400 — corpo inválido (ex.: campos obrigatórios ausentes ou combinação proibida de campos).
Formato completo e tabela de códigos em Erros.

​
Veja também

Planos e Preços

Monte o catálogo da sua oferta recorrente.

Assinaturas

Crie, cancele, pause e retome contratos.

Faturas

Consulte as cobranças geradas a cada ciclo.

Ciclos e cobrança

Entenda geração de fatura, cobrança e avanço de ciclo.

Clientes

A assinatura sempre aponta para um cliente.

Webhooks

Assine os 17 eventos subscription.* e invoice.* (ex.: invoice.paid, subscription.past_due). Nem toda mudança de status gera evento — completed e incomplete_expired não têm webhook próprio.