Criar uma fatura
Mande a url da fatura ao cliente para ele escolher o meio e pagar na página da PayZu, no cartão ou no Pix.
Crie a fatura
curl -X POST https://api.sandbox.payzu.dev/v1/invoices \
-H "Authorization: Bearer SUA_CHAVE_DE_API" \
-H "Idempotency-Key: 5b8d2f1a-3c4e-4a6b-9d7f-2e1c0b9a8f7d" \
-H "Content-Type: application/json" \
-d '{
"description": "Pedido 1236",
"external_reference": "pedido-1236",
"amount": 20980,
"billing": {
"due_at": "2026-11-18T03:00:00.000Z",
"expires_at": "2026-11-25T03:00:00.000Z"
},
"items": [
{ "name": "Curso de fotografia", "sku": "CURSO-01", "quantity": 1, "unit_price": 15990 },
{ "name": "Apostila impressa", "quantity": 2, "unit_price": 2495 }
],
"payment_settings": {
"accepted_methods": ["credit_card", "pix"],
"credit_card": { "max_installments": 3 }
},
"checkout": {
"redirect_url": "https://loja.exemplo.com.br/obrigado",
"cancel_url": "https://loja.exemplo.com.br/carrinho"
},
"customer_id": "cus_bdQT0ls1QMIXVuhngvhbwC",
"metadata": { "internal_id": "1234" }
}'{
"id": "in_3RtY8mKcVb5NwXz2QdLh7E",
"status": "pending",
"url": "https://invoice.payzu.com.br/pay/in_3RtY8mKcVb5NwXz2QdLh7E",
"description": "Pedido 1236",
"external_reference": "pedido-1236",
"created_at": "2026-11-11T15:24:10.512Z",
"updated_at": "2026-11-11T15:24:10.512Z",
"amounts": {
"subtotal": 20980,
"discount": 0,
"total": 20980,
"paid": 0,
"refunded": 0
},
"billing": {
"cycle_number": null,
"due_at": "2026-11-18T03:00:00.000Z",
"expires_at": "2026-11-25T03:00:00.000Z",
"paid_at": null,
"canceled_at": null,
"refunded_at": null,
"chargedback_at": null
},
"items": [
{ "name": "Curso de fotografia", "sku": "CURSO-01", "quantity": 1, "unit_price": 15990 },
{ "name": "Apostila impressa", "sku": null, "quantity": 2, "unit_price": 2495 }
],
"payment_settings": {
"accepted_methods": ["credit_card", "pix"],
"credit_card": { "max_installments": 3 }
},
"checkout": {
"redirect_url": "https://loja.exemplo.com.br/obrigado",
"cancel_url": "https://loja.exemplo.com.br/carrinho"
},
"customer": {
"id": "cus_bdQT0ls1QMIXVuhngvhbwC",
"name": "Maria Souza",
"email": "maria@exemplo.com.br",
"document": "52998224725",
"document_type": "cpf"
},
"subscription": null,
"payment_link": null,
"payments": [],
"refunds": [],
"cancellation": null,
"chargeback": null,
"metadata": {
"internal_id": "1234"
}
}Referência: Criar uma fatura
A fatura nasce pending, com a página de pagamento em url, e sai o evento invoice.created. Quando o cliente pagar, sai invoice.paid. Para cobrar na mesma chamada, veja Vender no cartão e Vender no Pix.
Escolha o cliente
| Como enviar | O que acontece |
|---|---|
customer_id | A fatura é do cliente já cadastrado. |
customer | A PayZu cadastra o cliente pelo document ou atualiza o que já tem esse documento, com os campos de Cadastrar um cliente. Sem payment, o cadastro só é gravado se a fatura for criada; com payment, ele é gravado antes da cobrança e fica mesmo quando a criação é recusada depois. |
| Nenhum dos dois | A fatura nasce com customer: null. Quem paga informa os dados na página, e a fatura fica ligada a ele na primeira tentativa de pagamento. |
Envie no máximo um dos dois. A fatura sem cliente é de uma pessoa só e é paga só pela página.
{
"description": "Pedido 1239",
"amount": 9900,
"customer": {
"name": "João Lima",
"email": "joao@exemplo.com.br",
"document": "11144477735",
"document_type": "cpf"
}
}Campos
| Campo | Regra |
|---|---|
description | Descrição da cobrança, com até 255 caracteres. |
amount | Valor cheio em centavos, a partir de 500 (R$ 5,00). |
items | Opcional, de 1 a 100 itens. Sem ele, a fatura traz um item só, com a description e o valor. Com ele, a soma de quantity vezes unit_price precisa ser igual a amount. |
external_reference | O identificador do pedido no seu sistema, com até 120 caracteres. Filtra a lista de faturas. |
metadata | Os seus dados na fatura, com os limites de Metadados. |
Idempotency-Key | Cabeçalho obrigatório, com um valor novo para cada fatura. Veja Idempotência. |
| Campo | Regra |
|---|---|
billing.due_at | O vencimento mostrado ao cliente. Não impede pagar antes nem depois. Sem ele, vale o momento da criação. |
billing.expires_at | O limite para pagar. Sem ele, a fatura vale 15 dias contados de due_at. Precisa ser uma data futura e não pode vir antes de due_at. |
Sem pagamento até billing.expires_at, a fatura passa a expired e sai o evento invoice.expired.
| Campo | Regra |
|---|---|
payment_settings.accepted_methods | credit_card, pix ou os dois. Cada um precisa estar habilitado na conta. Sem ele, valem os meios que a conta recebe. |
payment_settings.credit_card.max_installments | O máximo de parcelas no cartão, de 1 a 12. Sem ele, até 12. Só vale com credit_card em accepted_methods. |
checkout.redirect_url | Para onde a página leva o cliente depois de pagar, com https. |
checkout.cancel_url | Para onde a página leva quem desiste, com https. |
| Campo | Regra |
|---|---|
discount.type | percentage ou fixed_amount. |
discount.value | De 1 a 99 no percentage; em centavos e menor que amount no fixed_amount. |
O desconto é aplicado na criação: amounts.subtotal traz o valor cheio, amounts.discount o valor descontado e amounts.total o que o cliente paga. A resposta não tem bloco discount.
O total, já com o desconto, precisa estar no limite por cobrança da sua conta.
Também não pode ficar abaixo de R$ 5,00. Fora do limite da conta, a fatura não é criada e a Idempotency-Key fica liberada para você repetir a chamada.
Campo inválido responde 400, com cada campo recusado em fields. O prazo fora da regra, por exemplo, vem com name igual a billing.expires_at.
Erros desta operação
| Código | HTTP | Mensagem |
|---|---|---|
PZ032 | 403 | Cartão não habilitado para esta conta. Fale com o suporte para habilitar ou ofereça apenas Pix. |
PZ033 | 403 | Pix não habilitado para esta conta. Fale com o suporte para habilitar. |
| - | 404 | Cliente 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. |
Os erros de autenticação, de idempotência e de validação estão no Catálogo de erros.