> ## Documentation Index
> Fetch the complete documentation index at: https://docs.z2pay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Cartões

> Como funcionam os cartões salvos — quando nascem sozinhos, como cobrar de novo e o que a Z2Pay guarda.

O **cartão salvo** (`crd_`) é um instrumento de pagamento que fica associado a um cliente, para você
cobrar de novo sem pedir os dados outra vez. A Z2Pay guarda bandeira, primeiros e últimos dígitos,
nome do portador e validade — nunca o número completo nem o CVV.

Na maior parte das vezes você **não precisa criar nada**: processar uma transação de cartão com um
`customerId` e um token do [Tokenizer](/pt-BR/tokenizer) já salva o `crd_`, sem nenhuma flag. Criar
explicitamente serve para o caso oposto — guardar a forma de pagamento **antes** de haver o que
cobrar.

<Info>
  Todas as rotas exigem o header `x-api-key` (sua chave de sandbox). Veja
  [Autenticação](/pt-BR/autenticacao). Os exemplos nas páginas de cada endpoint usam a base URL de
  sandbox `https://api.sandbox.z2pay.com/v1`.
</Info>

***

## Endpoints

Cada endpoint tem sua própria página, com os campos aceitos, exemplos e o playground para testar.
Todas vivem sob o cliente — **não existe listagem global de cartões**.

| Método   | Rota                                   | Descrição                                                   |
| -------- | -------------------------------------- | ----------------------------------------------------------- |
| `GET`    | `/customers/:customerId/cards`         | [Lista os cartões do cliente](/pt-BR/cards/list)            |
| `GET`    | `/customers/:customerId/cards/:cardId` | [Busca um cartão por ID](/pt-BR/cards/get)                  |
| `POST`   | `/customers/:customerId/cards`         | [Salva um cartão a partir de um token](/pt-BR/cards/create) |
| `DELETE` | `/customers/:customerId/cards/:cardId` | [Desativa um cartão](/pt-BR/cards/delete)                   |

***

## Como um cartão nasce

**Sozinho, na transação.** Enviar `customerId` **e** um `token` do Tokenizer em
[`POST /transactions`](/pt-BR/transactions) associa aquele instrumento ao cliente e devolve um `crd_`
reutilizável. Não há opção para desligar isso: a única forma de **não** salvar é não mandar o
`customerId`.

Três consequências que costumam surpreender:

* **O cartão é salvo antes da autorização.** Ele existe mesmo que a cobrança seja recusada.
* **O mesmo cartão não vira dois `crd_`.** O salvamento deduplica pela impressão digital do cartão,
  no escopo daquele cliente. Em clientes diferentes, os `crd_` são distintos.
* **Só vale na criação da transação.** Em [`POST /payments/process`](/pt-BR/payments/process) o
  request não carrega `customerId`, então o token é usado só naquela cobrança e nada é salvo.

**Explicitamente, sem cobrar.** [`POST /customers/{customerId}/cards`](/pt-BR/cards/create) salva o
cartão a partir de um token do Tokenizer sem passar pelo gateway — é o caminho para cadastrar a forma
de pagamento antes da primeira compra.

***

## Como cobrar um cartão salvo

Depois de salvo, você cobra pelo `id` do cartão, sem gerar token novo:

| Onde                                                   | Campo                      |
| ------------------------------------------------------ | -------------------------- |
| [Criação da transação](/pt-BR/transactions)            | `payments[].creditCard.id` |
| [Processamento de pagamentos](/pt-BR/payments/process) | `creditCard.cardId`        |

A alternativa é o **token efêmero** (`tok_`): um token novo do Tokenizer a cada compra, em
`payments[].creditCard.token`. Ele expira em 24h e vale uma única vez — com ou sem `customerId`, é
consumido no primeiro uso.

<Note>
  **O `crd_` volta na hora, a listagem demora um instante.** O `id` do cartão já vem na resposta da
  criação da transação e o `GET` por ID o encontra de imediato. Na listagem ele aparece logo depois —
  a persistência é assíncrona, em geral abaixo de um segundo.
</Note>

***

## Veja também

<CardGroup cols={2}>
  <Card title="Tokenizer" icon="lock" href="/pt-BR/tokenizer">
    Como transformar os dados do cartão em `tok_` sem passar por perto de PCI.
  </Card>

  <Card title="Clientes" icon="user" href="/pt-BR/customers">
    O dono do cartão — todas as rotas de cartão vivem sob ele.
  </Card>

  <Card title="Pagamentos" icon="credit-card" href="/pt-BR/payments">
    Onde o `crd_` é cobrado.
  </Card>

  <Card title="Cartões de teste" icon="flask-conical" href="/pt-BR/sandbox/cartoes">
    Números para usar no sandbox.
  </Card>
</CardGroup>