Salvar um cartão
O salvamento guarda o cartão no cliente sem cobrar nada e retorna o id usado nas próximas cobranças.
Envie o token ou os dados do cartão
curl -X POST https://api.sandbox.payzu.dev/v1/customers/cus_bdQT0ls1QMIXVuhngvhbwC/cards \
-H "Authorization: Bearer SUA_CHAVE_DE_API" \
-H "Content-Type: application/json" \
-d '{ "card_token": "UTYi5E0smwqD8P5U8pupcDtT1aIAbpgkc5HLQFGkb3I" }'curl -X POST https://api.sandbox.payzu.dev/v1/customers/cus_bdQT0ls1QMIXVuhngvhbwC/cards \
-H "Authorization: Bearer SUA_CHAVE_DE_API" \
-H "Content-Type: application/json" \
-d '{
"card": {
"number": "4111111111111111",
"expiration": "12/2030",
"cvv": "123",
"holder_name": "MARIA SOUZA",
"holder_document": "52998224725"
}
}'{
"id": "card_6WnQ2xLmVb8TzYc4KdRh3E",
"brand": "visa",
"last_digits": "1111",
"expiration": "12/2030",
"holder_name": "MARIA SOUZA",
"last_used_at": null,
"created_at": "2026-11-11T15:22:41.207Z",
"updated_at": "2026-11-11T15:22:41.207Z"
}Referência: Salvar um cartão
| Forma | Campos |
|---|---|
| Com token | card_token, gerado na tokenização. |
| Com os dados do cartão | card, com number, expiration (MM/AAAA), cvv, holder_name e, se quiser, holder_document. |
Envie uma das duas formas. A adquirente não confere o cartão no salvamento, e um cartão inválido só aparece na primeira cobrança.
O mesmo cartão do mesmo cliente não se repete. Salvar de novo responde 200, no lugar de 201, com o mesmo id, e atualiza a validade e o nome com o que veio.
Esta rota ignora a Idempotency-Key, e cada chamada roda de novo.
Com os dados do cartão, repetir retorna o mesmo cartão. Com card_token, o token serve para uma operação só, e a repetição é recusada mesmo quando a primeira chamada salvou o cartão. Confira a lista do cliente antes de gerar outro token.
Cobre com o cartão salvo
Envie o id do cartão em payment.credit_card.card_id ao criar uma fatura. Ao pagar uma fatura ou criar uma assinatura, o campo é credit_card.card_id.
{
"description": "Pedido 1234",
"external_reference": "pedido-1234",
"amount": 15990,
"customer_id": "cus_bdQT0ls1QMIXVuhngvhbwC",
"payment": {
"method": "credit_card",
"credit_card": {
"card_id": "card_6WnQ2xLmVb8TzYc4KdRh3E",
"installments": 1
}
}
}Erros desta operação
| Código | HTTP | Mensagem |
|---|---|---|
PZ201 | 400 | Token de cartão inválido ou vencido. Gere o token de novo. |
| - | 404 | Cliente não encontrado para o id informado. |
PZ202 | 503 | Não foi possível processar o cartão agora. Tente de novo. |
Os erros de autenticação e de validação estão no Catálogo de erros.