# Trocar cartão da assinatura

URL: https://staging.pagpolar.com/docs/referencia/assinaturas/update-subscription-card

> Substitui o cartão de crédito usado nas cobranças de uma assinatura paga com cartão. O novo
cartão é salvo no gateway e passa a ser cobrado a partir do próximo ciclo; o plano, o valor e
as datas de cobrança não mudam.

A troca é aceita em qualquer situação da assinatura — use-a, por exemplo, para regularizar uma
assinatura cuja renovação foi recusada. Se o gateway não aceitar a troca naquele estado, a
requisição retorna `400` com a mensagem do gateway.

A troca não gera cobrança, por isso não exige `Idempotency-Key`. Conta no limite por minuto
da credencial, como qualquer rota.

`PATCH /subscriptions/{id}/card`

## Autenticação

- Token Bearer no header `Authorization` (esquema `BearerAuth`). Token de acesso devolvido por POST /auth/token. Envie como "Authorization: Bearer <token>". Vale 24 horas.

## Parâmetros de caminho

| Parâmetro | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `id` | texto (uuid) | sim | — |

## Corpo da requisição

Content-type: `application/json`.

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `credit_card` | objeto | sim | Dados do cartão de crédito usado na cobrança. |
| `credit_card.holder_name` | texto | sim | Exemplo: `FULANO DE TAL`. |
| `credit_card.holder_document` | texto | sim | CPF (11 dígitos) ou CNPJ (14 dígitos) do titular do cartão, com ou sem pontuação. A API grava só os dígitos. Fora disso, 400. Exemplo: `12345678909`. |
| `credit_card.number` | texto | sim | Exemplo: `4111111111111111`. |
| `credit_card.expiration_month` | inteiro | sim | Exemplo: `12`. |
| `credit_card.expiration_year` | inteiro | sim | Exemplo: `2030`. |
| `credit_card.cvv` | texto | sim | Exemplo: `123`. |

### Exemplo do corpo

Novo cartão:

```json
{
  "credit_card": {
    "holder_name": "FULANO DE TAL",
    "holder_document": "12345678909",
    "number": "4111111111111111",
    "expiration_month": 12,
    "expiration_year": 2030,
    "cvv": "123"
  }
}
```

## Respostas

### 200 — Cartão da assinatura atualizado

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `data` | [Resultado da operação](/docs/referencia/entidades/resultado-da-operacao) | não | — |

## Erros

| Status | Descrição |
| --- | --- |
| `400` | Dados de cartão inválidos, assinatura sem cobrança no cartão ou troca recusada pelo gateway |
| `401` | Token ausente, inválido ou expirado, ou credencial revogada ou expirada. Chame POST /auth/token para obter um token novo. |
| `403` | IP não autorizado |
| `404` | Assinatura não encontrada |
| `429` | Limite de requisições por minuto da credencial excedido na troca de cartão |
| `503` | Serviço de limite indisponível — repita a requisição com a mesma Idempotency-Key |

Lista completa de códigos e como tratá-los: [Erros](/docs/guias/fundamentos/erros).