Trocar o cartão da assinatura
Troque o cartão de crédito de uma assinatura sem cancelar, sem mudar o plano e sem cobrar o cliente.
Quando usar
Use este guia quando o cliente quer pagar a assinatura com outro cartão. Exemplos: o cartão venceu, foi perdido ou o cliente prefere outro.
A troca:
- não cobra nada;
- não muda o plano, o valor nem as datas da assinatura;
- não cancela a assinatura.
Só funciona em assinatura no cartão.
Se o cliente quer mudar de plano e pagar a diferença com um cartão novo, use Trocar de plano com payment_choice: "new_card".
Visão geral
O diagrama mostra o caminho de uma troca de cartão.
Antes de começar
- Um token de acesso. Veja Autenticação; os exemplos assumem a variável
accessToken. - Uma assinatura no cartão e o
iddela. Veja Assinar um plano. - Os dados do novo cartão, informados pelo cliente.
Passo a passo
Confira a assinatura
Confira em GET /subscriptions/{id} se payment_method é CREDIT_CARD.
Envie o novo cartão
Chame PATCH /subscriptions/{id}/card com os dados do cartão dentro de credit_card.
| Campo | Obrigatório | O que é |
|---|---|---|
credit_card.holder_name | Sim | Nome impresso no cartão. |
credit_card.holder_document | Sim | CPF ou CNPJ do titular do cartão, com ou sem pontuação. Veja o formato em Documento e telefone. |
credit_card.number | Sim | Número do cartão. A API confere se o número é válido antes de enviar. |
credit_card.expiration_month | Sim | Mês de validade, número de 1 a 12. |
credit_card.expiration_year | Sim | Ano de validade com 4 dígitos, número. |
credit_card.cvv | Sim | Código de segurança, texto com 3 ou 4 caracteres. |
No ambiente de testes, use os cartões de Comprar no ambiente de testes.
Esta rota não usa Idempotency-Key, porque não cobra nada.
curl -X PATCH "https://api.pagpolar.com/v1/subscriptions/<ID_DA_ASSINATURA>/card" \
-H "Authorization: Bearer <SEU_TOKEN_DE_ACESSO>" \
-H "Content-Type: application/json" \
-d '{
"credit_card": {
"holder_name": "MARIA SILVA",
"holder_document": "<CPF_DO_TITULAR>",
"number": "<NUMERO_DO_CARTAO>",
"expiration_month": 12,
"expiration_year": 2030,
"cvv": "<CVV>"
}
}'const response = await fetch(
'https://api.pagpolar.com/v1/subscriptions/<ID_DA_ASSINATURA>/card',
{
method: 'PATCH',
headers: {
Authorization: `Bearer ${accessToken}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
credit_card: {
holder_name: 'MARIA SILVA',
holder_document: '<CPF_DO_TITULAR>',
number: '<NUMERO_DO_CARTAO>',
expiration_month: 12,
expiration_year: 2030,
cvv: '<CVV>',
},
}),
},
);
console.log(response.status, await response.json());Resposta 200:
{
"data": {
"success": true
}
}Os nomes dos campos são diferentes na troca de plano
Aqui o objeto se chama credit_card e a validade vai em expiration_month e expiration_year. Na troca de plano com cartão novo, o objeto se chama card e a validade vai em exp_month e exp_year.
Registre a troca no seu sistema
Com a resposta 200, o novo cartão já está na assinatura do gateway. As próximas cobranças da assinatura usam esse cartão.
- A resposta não traz os dígitos do cartão. Se quiser mostrar ao cliente, guarde os 4 últimos dígitos no seu sistema antes de enviar.
GET /subscriptions/{id}continua igual: plano, valor e datas não mudam.
Eventos de webhook deste fluxo
Nenhum webhook avisa a troca: use a resposta 200 como confirmação. As cobranças seguintes da assinatura continuam gerando os eventos de sempre. Veja Ciclo de vida da assinatura.
Quando algo dá errado
Além dos erros comuns a todas as rotas, este fluxo pode responder:
| Passo | Situação | Resposta | Como resolver |
|---|---|---|---|
| 1 e 2 | A assinatura não existe na sua conta | 404 not_found com Assinatura não encontrada | Confira o id da assinatura. |
| 2 | Valor inválido, como mês 13, ano fora de 2000 a 2100 ou número de cartão inválido | 400 invalid_request, em geral com message vazia | Confira os campos na tabela do passo 2. |
| 2 | Assinatura sem cadastro no gateway. Acontece com assinatura em PIX ou boleto. | 400 invalid_request com Assinatura não possui ID externo no gateway. | Não há cartão para trocar nesta assinatura. |
| 2 | Assinatura sem cliente vinculado | 400 invalid_request com Cliente não encontrado na assinatura. | Fale com o suporte informando o request_id. |
| 2 | O gateway recusou o cadastro do cartão | 400 invalid_request. Exemplos de message: Dados do cartão inválidos. Verifique o número, validade e CVV e tente novamente. ou Não foi possível processar o cartão de crédito. Verifique os dados e tente novamente. | Peça ao cliente para conferir os dados ou usar outro cartão. |
| 2 | Erro inesperado, inclusive quando o gateway recusa a troca na assinatura | 500 internal_error | A troca não cobra nada, então repetir é seguro: cada chamada só cadastra o cartão de novo e o coloca na assinatura. Se o erro continuar, fale com o suporte informando o request_id. |