Ciclo da assinatura
Nesta página
OperaçõesStatus da assinaturaDatas de cobrançaFaturas da assinaturaRenovação no cartãoRenovação no PixCarênciaCancelamentoVolta de um cancelamentoCada cobrança da assinatura é uma fatura, da adesão aos ciclos seguintes, e o pagamento de cada uma decide se a assinatura continua ativa.
Operações
Assine um plano ou combine um valor avulso, com a fatura da adesão na mesma chamada.
2. Consultar assinaturasLeia o status e as datas de uma assinatura ou liste as assinaturas da conta.
3. Alterar uma assinaturaReajuste o valor ou troque o metadata de quem já assina.
Encerre as cobranças quando o cliente desistir.
5. Reativar uma assinaturaTraga de volta a assinatura cancelada há até 30 dias.
Status da assinatura
| Status | O que significa |
|---|---|
incomplete | Aguardando o pagamento da fatura da adesão. |
active | Assinatura ativa. Na carência, segue active, com grace preenchido. |
canceled | Assinatura cancelada. O motivo vem em cancellation.reason. |
Datas de cobrança
| Campo | Tipo | Descrição |
|---|---|---|
billing.anchor_at | string | Data de referência dos ciclos: o dia da adesão. |
billing.next_at | string | Data da próxima cobrança; nula na assinatura cancelada. |
billing.canceled_at | string | Data do cancelamento; nula enquanto a assinatura não é cancelada. |
billing.renewal_failures | integer | Recusas seguidas da cobrança do ciclo no cartão. |
Faturas da assinatura
| Fatura | billing.cycle_number | billing.due_at | billing.expires_at |
|---|---|---|---|
| Adesão | 0 | A criação da assinatura. | 1 hora depois de due_at. |
| Ciclo | 1 em diante, somando 1 a cada renovação. | A data do ciclo. | due_at mais o grace_days da conta na criação da fatura. |
Sem pagamento até o billing.expires_at da adesão, a fatura passa a expired, e a assinatura, a canceled, com o motivo initial_payment_failure. Se a última tentativa no cartão segue sem resposta da adquirente nesse momento, a PayZu espera até 48 horas, contadas dessa tentativa, como em Criar uma assinatura. Na fatura do ciclo, o prazo entre due_at e expires_at é a carência.
O desconto da assinatura conta a adesão.
Ele vale nos primeiros discount.cycles ciclos: com cycles igual a 3, as faturas dos ciclos 0, 1 e 2 têm desconto.
Renovação no cartão
A adquirente cobra cada ciclo no cartão da assinatura, sem chamada sua. A primeira cobrança do ciclo cria a fatura dele, com invoice.created, e cada cobrança entra como tentativa em payments.
| Resultado | Fatura | Assinatura | Eventos |
|---|---|---|---|
| Aprovada | paid | Segue active, e billing.next_at passa ao ciclo seguinte. | invoice.paid e subscription.renewed |
| Recusada | pending, com a tentativa failed | Entra na carência. | invoice.payment_failed e, na primeira recusa, subscription.grace_started |
| Sem desfecho | pending, com a tentativa processing | Segue como está até a adquirente aprovar ou recusar. | - |
Na carência, a fatura recusada aceita nova tentativa, como em Pagar uma fatura.
Renovação no Pix
A PayZu cria a fatura do ciclo 5 dias antes de billing.next_at e leva billing.next_at para o ciclo seguinte. Esses 5 dias são o padrão da conta, que o painel altera.
| Momento | Fatura | Assinatura | Eventos |
|---|---|---|---|
| 5 dias antes do ciclo | pending, com billing.due_at na data do ciclo | Segue active. | invoice.created |
| Pix pago | paid | Segue active. | invoice.paid e subscription.renewed |
billing.due_at sem pagamento | pending | Entra na carência. | subscription.grace_started |
billing.expires_at sem pagamento | expired | canceled, com o motivo renewal_failure. | invoice.expired e subscription.canceled |
- Página de pagamento: a fatura traz em
urla página em que o cliente paga o ciclo. Mande esse endereço a ele ou gere o QR Code com Pagar uma fatura. - Uma fatura por vez: a fatura do ciclo seguinte só sai quando a anterior não está mais em aberto.
Carência
Com a recusa no cartão ou o vencimento sem pagamento no Pix, a assinatura entra na carência e segue active, com grace preenchido. A carência vai até o billing.expires_at da fatura do ciclo, e a assinatura só é cancelada se o ciclo não for pago até lá. As regras estão em Carência, e a troca do prazo, em Alterar a carência.
Cancelamento
A assinatura cancelada traz o bloco cancellation.
| Campo | Descrição |
|---|---|
cancellation.reason | Motivo. |
cancellation.note | Observação enviada no cancelamento pela API. |
| Motivo | O que significa |
|---|---|
merchant_request | Cancelada por você, pela API ou pelo painel. |
initial_payment_failure | A fatura da adesão venceu sem pagamento. |
renewal_failure | A carência terminou sem o pagamento do ciclo. |
invoice_refund | Uma fatura da assinatura foi estornada. |
invoice_chargeback | Uma fatura da assinatura foi contestada. |
- Faturas em aberto: as faturas
pendingda assinatura sem pagamento confirmado passam acanceled, comcancellation.reasonigual asubscription_cancellation. A fatura que encerra a assinatura por falta de pagamento passa aexpired. - Contestação: a contestação de uma fatura sempre cancela a assinatura.
- Estorno: o estorno de uma fatura cancela a assinatura conforme
cancel_subscriptionno pedido ou, sem o campo, a configuração da conta, que por padrão cancela, como em Estorno.
Volta de um cancelamento
A assinatura cancelada volta a active por dois caminhos.
| Caminho | Vale para |
|---|---|
| Pagamento confirmado depois do cancelamento | initial_payment_failure, ou renewal_failure na assinatura no Pix. |
| Reativação | Assinatura cancelada há até 30 dias, nas condições da reativação. |
Nos dois caminhos, sai subscription.reactivated, cancellation volta a null, grace volta a null e billing.renewal_failures, a 0. O cancelamento desfeito vai para previous_cancellations, com a data da volta em reactivated_at. A lista vem do cancelamento mais novo para o mais antigo e fica vazia enquanto a assinatura não voltou de nenhum cancelamento.
Os eventos estão listados em Webhooks.