Vender no cartão
Cobre um valor no cartão de crédito, à vista ou em até 12 parcelas, com a fatura e a tentativa de pagamento criadas na mesma chamada.
Cobre no cartão
curl -X POST https://api.sandbox.payzu.dev/v1/invoices \
-H "Authorization: Bearer SUA_CHAVE_DE_API" \
-H "Idempotency-Key: a3f1c9e2-7b4d-4e8a-9c6f-1d2e3f4a5b6c" \
-H "Content-Type: application/json" \
-d '{
"description": "Pedido 1234",
"external_reference": "pedido-1234",
"amount": 15990,
"items": [
{ "name": "Curso de fotografia", "sku": "CURSO-01", "quantity": 1, "unit_price": 15990 }
],
"customer_id": "cus_bdQT0ls1QMIXVuhngvhbwC",
"payment": {
"method": "credit_card",
"credit_card": {
"card": {
"number": "4111111111111111",
"expiration": "12/2030",
"cvv": "123",
"holder_name": "MARIA SOUZA",
"holder_document": "52998224725"
},
"installments": 1,
"save_card": true
}
},
"metadata": { "internal_id": "1234" }
}'{
"id": "in_7Kd2QmXvB9LtYc4WnRz8Hs",
"status": "paid",
"url": "https://invoice.payzu.com.br/pay/in_7Kd2QmXvB9LtYc4WnRz8Hs",
"description": "Pedido 1234",
"external_reference": "pedido-1234",
"created_at": "2026-11-11T15:20:59.333Z",
"updated_at": "2026-11-11T15:20:59.336Z",
"amounts": {
"subtotal": 15990,
"discount": 0,
"total": 15990,
"paid": 15990,
"refunded": 0
},
"billing": {
"cycle_number": null,
"due_at": "2026-11-11T15:20:59.333Z",
"expires_at": "2026-11-26T15:20:59.333Z",
"paid_at": "2026-11-11T15:20:59.335Z",
"canceled_at": null,
"refunded_at": null,
"chargedback_at": null
},
"items": [
{ "name": "Curso de fotografia", "sku": "CURSO-01", "quantity": 1, "unit_price": 15990 }
],
"payment_settings": {
"accepted_methods": ["credit_card", "pix"],
"credit_card": { "max_installments": 12 }
},
"checkout": {
"redirect_url": null,
"cancel_url": null
},
"customer": {
"id": "cus_bdQT0ls1QMIXVuhngvhbwC",
"name": "Maria Souza",
"email": "maria@exemplo.com.br",
"document": "52998224725",
"document_type": "cpf"
},
"subscription": null,
"payment_link": null,
"payments": [
{
"id": "pay_Nfa3VKU4p0ojE3jMQeunRD",
"status": "paid",
"method": "credit_card",
"amount": 15990,
"created_at": "2026-11-11T15:20:59.333Z",
"paid_at": "2026-11-11T15:20:59.335Z",
"failed_at": null,
"failure": null,
"credit_card": {
"installments": 1,
"authorization_code": "123456",
"card": {
"id": "card_GL2pIWf5pznF4qwg2KKd5v",
"brand": "visa",
"last_digits": "1111",
"holder_name": "MARIA SOUZA"
}
}
}
],
"refunds": [],
"cancellation": null,
"chargeback": null,
"metadata": {
"internal_id": "1234"
}
}Referência: Criar uma fatura
Um erro antes do envio da cobrança libera a Idempotency-Key.
Valor fora do limite da conta, token inválido, cartão de outro cliente, parcelas ou meio fora do aceito e o pagamento indisponível no momento são erros desse tipo: a fatura não é criada, e você pode repetir com a mesma chave. Se mandou card_token, gere um token novo, porque o token serve para uma operação só.
Campos
A rota é a de Criar uma fatura, com os mesmos campos e o bloco payment.
| Campo | Regra |
|---|---|
payment.method | credit_card. |
payment.credit_card.installments | De 1 até payment_settings.credit_card.max_installments da fatura, que vai até 12. Sem ele, 1. |
payment.credit_card.save_card | Salva o cartão no cliente, como explica a seção Cartão. |
customer_id ou customer | Obrigatório com payment: a fatura sem cliente só é paga pela página. |
Idempotency-Key | Cabeçalho obrigatório, com um valor novo para cada venda. Veja Idempotência. |
Parcelas acima do aceito ou credit_card fora de payment_settings.accepted_methods respondem 400, com payment.credit_card.installments ou payment.method em fields.
Cartão
O cartão vai em payment.credit_card, por um destes três campos:
| Campo | Cartão |
|---|---|
card | Digitado no seu sistema, com number, expiration no formato MM/AAAA, cvv, holder_name e, se quiser, holder_document. |
card_id | Salvo no mesmo cliente, como em Cartões salvos. Um card_id que não é de um cartão salvo do cliente da fatura responde 404. |
card_token | Cifrado no aparelho do comprador, como em Tokenização de cartão. O token vale 15 minutos e serve para uma operação só. |
save_card: true: salva o cartão decardou decard_tokenno cliente, e oiddele vem empayments[0].credit_card.card.idpara as próximas cobranças. Se a primeira cobrança desse cartão for recusada, ele é apagado.- Sem
save_card: comcardoucard_token,card.idvemnull. Comcard_id, vem oiddo cartão salvo. holder_document: é só de entrada e não volta em nenhuma resposta.
A cobrança no cartão pela API não leva dados de antifraude nem de 3D Secure. Se a sua conta exige antifraude no cartão, a cobrança é recusada, e o Pix segue disponível.
Confirme o pagamento
Criada a fatura, a resposta é 201, com a tentativa em payments[0], inclusive quando ela vem failed ou processing.
| Resultado | Tentativa | Fatura | Evento |
|---|---|---|---|
| Cartão aprovado | paid | paid | invoice.paid |
| Recusa do banco, do antifraude ou da operação | failed, com o motivo em failure | pending | invoice.payment_failed |
| A adquirente não respondeu a tempo | processing | pending | - |
A tentativa processing se resolve sozinha e passa a paid ou a failed:
- A PayZu procura a cobrança na adquirente a partir de 5 minutos da criação.
- Sem cobrança em 30 minutos, ou com a cobrança ainda sem resposta em 24 horas, a tentativa passa a
failede a fatura volta a aceitar tentativa. - Se a cobrança aparecer depois, aprovada, a tentativa ainda passa a
paid.
Enquanto a tentativa estiver processing, não crie outra fatura para o mesmo pedido.
Uma nova tentativa na mesma fatura é recusada até o desfecho. Nas 24 horas seguintes, repetir a mesma criação com a mesma Idempotency-Key retorna a resposta guardada, com Idempotent-Replayed: true, sem cobrar de novo; o número, o CVV e o token do cartão não entram nessa comparação. Trocar o token pelo cartão digitado, ou o contrário, responde 409, assim como a repetição feita antes de a primeira chamada terminar.
Na recusa, failure diz onde a venda parou. failure.code é o código estável da recusa e failure.message é a frase pronta para mostrar ao cliente.
failure.stage | Onde a venda parou |
|---|---|
issuer | O banco do cliente negou. |
antifraud | O antifraude parou a venda antes do banco. |
card_check | A validade não confere com a do cartão. |
split | Falha na divisão do valor da venda. |
processing | Falha na operação, sem resposta do banco. |
{
"id": "in_9Lq4ZnWcVb7TyXm3KdRh2E",
"status": "pending",
"payments": [
{
"id": "pay_6TzR2nXcVb8LwYm4KdQh9E",
"status": "failed",
"method": "credit_card",
"amount": 15990,
"failed_at": "2026-11-11T15:22:41.925Z",
"failure": {
"stage": "issuer",
"code": "PZ230",
"message": "O banco do cliente recusou sem dizer o motivo. O cliente pode usar outro cartão ou falar com o banco."
}
}
]
}A recusa não fecha a fatura: a url segue valendo para o cliente pagar na página, e você pode tentar de novo pela API, como em Pagar uma fatura.
Os eventos trazem a fatura em data.invoice, no formato da resposta. Cadastre o webhook em Cadastrar webhooks e, para conferir um caso específico, consulte a fatura.
Erros desta operação
| Código | HTTP | Mensagem |
|---|---|---|
PZ001 | 400 | A solicitação possui erros de validação. |
PZ201 | 400 | Token de cartão inválido ou vencido. Gere o token de novo. |
PZ032 | 403 | Cartão não habilitado para esta conta. Fale com o suporte para habilitar ou ofereça apenas Pix. |
| - | 404 | Cliente não encontrado para o id informado. |
| - | 404 | Cartão não encontrado para o id informado. |
PZ100 | 422 | A soma dos itens é diferente do valor da fatura. |
PZ101 | 422 | Valor fora do limite desta conta. |
PZ203 | 422 | Esta conta exige os dados de antifraude na cobrança no cartão. |
PZ202 | 503 | Não foi possível processar o cartão agora. Tente de novo. |
PZ900 | 503 | Não foi possível processar o pagamento agora. Tente novamente mais tarde. |
Os erros de autenticação e de idempotência estão no Catálogo de erros.