Skip to main content
Uma assinatura é uma sequência de cobranças no mesmo cartão, sem o comprador na tela. Quem cobra assim tem duas obrigações que uma venda avulsa não tem: guardar o cartão antes e declarar cada cobrança como parte da série.

​
Guardar o cartão

O cofre se enche de duas formas, e a melhor depende de haver ou não uma primeira venda:

Há uma primeira cobrança

Mande save_card: true nela. O cartão entra no cofre com uma autorização real no histórico, e é uma chamada a menos.

Não há (trial, cobrança adiada)

POST /v1/cards guarda sem cobrar. Passa por uma verificação sem valor, que é menos que uma autorização.
O pm_ que volta é o que cobra depois, em card.id. Ver Cofre de cartões.

​
Declarar a série

O campo é recurrence, em POST /v1/charges, e ele só existe no cartão.
Primeira cobrança
Guarde o id (ch_…) que voltou. Toda cobrança seguinte aponta para ele:
Cobranças seguintes
Omitir recurrence não dá erro nenhum — e é exatamente por isso que ela está documentada aqui. A cobrança é aceita, a venda acontece, e a falta vira multa de bandeira semanas depois. Mastercard, Visa e Elo exigem a declaração em transações iniciadas pelo lojista.

​
A série reinicia mais vezes do que parece

Trocar o cartão, trocar o meio de pagamento ou mudar o valor encerra a série. A cobrança seguinte a qualquer uma dessas mudanças é uma nova first, e é o ch_ dela que as próximas passam a apontar. Continuar apontando para a origem antiga declara uma série que a bandeira não reconhece mais. Na prática: um reajuste de plano abre série nova. Um upgrade também.

​
Uma parcela, sempre

installments aceita apenas 1 numa cobrança recorrente. A bandeira não parcela uma assinatura — quem quer dividi-la cobra mais vezes, não uma vez em doze. Mandar outro número volta 422.

​
O que a declaração NÃO faz

Não devolve a transferência de responsabilidade. Declarar a recorrência é conformidade: evita multa. A proteção numa contestação por fraude continua vindo da autenticação do portador, e um cartão guardado não consegue autenticar — o desafio precisa do número em claro. O caminho que preserva a proteção é autenticar a primeira cobrança, com o comprador na tela e o cartão digitado, e deixar as seguintes correrem declaradas com o pm_. Numa loja que exige autenticação, cobrar a primeira já com card.id e recurrence funciona — e corre sem liability shift, por sua conta.

​
O que você recebe de volta

card.recurrence_cycle traz o ciclo declarado, e null em toda cobrança fora de uma série. É por ele que você responde “quais destas cobranças foram de assinatura?” ao conciliar.

​
O que dá errado

​
Veja também

Cofre de cartões

Guardar o cartão e cobrar de novo sem pedir nada ao comprador.

Autenticação do portador

Por que o cofre e o 3DS não convivem, e o que isso custa numa assinatura.
Ficou algo de fora? Chame no WhatsApp. Se o assunto for uma chamada específica, informe o horário dela; se for uma entrega de webhook, informe o X-Vext-Delivery — é por ele que localizamos a tentativa, a resposta do seu servidor e o horário.