PayZu GatewayClientes e cartões
Tokenização no app
Num app que não roda o script, o próprio aparelho do comprador pede o token à PayZu com a chave de checkout, sem a chave de API.
Gere o token
bash
curl -X POST https://api.sandbox.payzu.dev/v1/card-tokens \
-H "x-checkout-key: SUA_CHAVE_DE_CHECKOUT" \
-H "Content-Type: application/json" \
-d '{
"card": {
"number": "4111111111111111",
"expiration": "12/2030",
"cvv": "123",
"holder_name": "MARIA SOUZA",
"holder_document": "52998224725"
}
}'json
{
"id": "UTYi5E0smwqD8P5U8pupcDtT1aIAbpgkc5HLQFGkb3I",
"expires_at": "2026-11-11T15:37:41.207Z",
"card": {
"id": null,
"brand": "visa",
"last_digits": "1111",
"holder_name": "MARIA SOUZA"
}
}Referência: Gerar um token de cartão
- Cabeçalho:
x-checkout-key, com a chave de checkout. - Cartão:
card, comnumber,expiration(MM/AAAA),cvveholder_name. - Opcional:
card.holder_document, que segue dentro do token.
| Campo da resposta | O que traz |
|---|---|
id | O token. |
expires_at | Até quando o token vale, 15 minutos depois de gerado. |
card | A bandeira, o final e o nome, para a tela de confirmação. |
card.id | Sempre null, porque gerar o token não salva o cartão. O cartão só ganha id quando é salvo. |
Cada IP faz até 10 chamadas por minuto.
Acima disso, a resposta é 429.
Cobre com o token
O seu servidor recebe o token do aparelho do comprador e o envia em payment.credit_card.card_token ao criar uma fatura, com a chave de API. Com save_card: true, a cobrança também salva o cartão para as próximas cobranças.
Corpo de POST /v1/invoices
{
"description": "Pedido 1234",
"external_reference": "pedido-1234",
"amount": 15990,
"customer_id": "cus_bdQT0ls1QMIXVuhngvhbwC",
"payment": {
"method": "credit_card",
"credit_card": {
"card_token": "UTYi5E0smwqD8P5U8pupcDtT1aIAbpgkc5HLQFGkb3I",
"installments": 1,
"save_card": true
}
}
}Gere um token novo para cada operação nova.
Um token já usado responde 400. A repetição da mesma fatura com a mesma Idempotency-Key segue as regras de Idempotência.
Erros desta operação
| Código | HTTP | Mensagem |
|---|---|---|
| - | 401 | Chave de checkout ausente. |
| - | 401 | Chave de checkout inválida. |
| - | 429 | Muitas tentativas. Aguarde um minuto. |
A chave de uma conta suspensa também responde Chave de checkout inválida. Os erros de validação estão no Catálogo de erros.