# Trocar o cartão da assinatura URL: https://staging.pagpolar.com/docs/guias/jornadas/trocar-cartao-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](/docs/guias/jornadas/trocar-de-plano) com `payment_choice: "new_card"`. ## Visão geral O diagrama mostra o caminho de uma troca de cartão. ```mermaid sequenceDiagram autonumber participant I as Seu sistema participant A as API participant G as Gateway I->>A: PATCH /subscriptions/ID/card com credit_card alt assinatura sem cadastro no gateway, como PIX ou boleto A-->>I: 400 invalid_request else permitido A->>G: cadastra o novo cartão A->>G: troca o cartão da assinatura A-->>I: 200 success true end ``` ## Antes de começar * Um token de acesso. Veja [Autenticação](/docs/guias/fundamentos/autenticacao#obter-o-token); os exemplos assumem a variável `accessToken`. * Uma assinatura no cartão e o `id` dela. Veja [Assinar um plano](/docs/guias/jornadas/assinar-um-plano). * Os dados do novo cartão, informados pelo cliente. ## Passo a passo 1. **Confira a assinatura** Confira em [`GET /subscriptions/{id}`](/docs/referencia/assinaturas/get-subscription) se `payment_method` é `CREDIT_CARD`. 2. **Envie o novo cartão** Chame [`PATCH /subscriptions/{id}/card`](/docs/referencia/assinaturas/update-subscription-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](/docs/guias/fundamentos/valores-datas-e-identificadores#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](/docs/guias/fundamentos/ambientes#dados-de-teste). Esta rota **não** usa `Idempotency-Key`, porque não cobra nada. #### cURL ```bash curl -X PATCH "https://api.pagpolar.com/v1/subscriptions//card" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "credit_card": { "holder_name": "MARIA SILVA", "holder_document": "", "number": "", "expiration_month": 12, "expiration_year": 2030, "cvv": "" } }' ``` #### Node.js ```js const response = await fetch( 'https://api.pagpolar.com/v1/subscriptions//card', { method: 'PATCH', headers: { Authorization: `Bearer ${accessToken}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ credit_card: { holder_name: 'MARIA SILVA', holder_document: '', number: '', expiration_month: 12, expiration_year: 2030, cvv: '', }, }), }, ); console.log(response.status, await response.json()); ``` Resposta `200`: ```json { "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](/docs/guias/jornadas/trocar-de-plano) com cartão novo, o objeto se chama `card` e a validade vai em `exp_month` e `exp_year`. 3. **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](/docs/guias/conceitos/ciclo-de-vida-da-assinatura). ## Quando algo dá errado Além dos [erros comuns a todas as rotas](/docs/guias/fundamentos/erros#erros-comuns), 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`. | ## Próximos passos - [Trocar de plano](/docs/guias/jornadas/trocar-de-plano) — Mude a assinatura para outra oferta de plano. - [Ciclo de vida da assinatura](/docs/guias/conceitos/ciclo-de-vida-da-assinatura) — Entenda os status e os eventos das renovações. - [Erros](/docs/guias/fundamentos/erros) — Saiba quais erros é seguro repetir.