PayZu GatewayCobranças

Criar uma fatura


Nesta páginaCrie a faturaEscolha o clienteCamposErros desta operação

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

bash
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" }
  }'

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 enviarO que acontece
customer_idA fatura é do cliente já cadastrado.
customerA 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 doisA 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.

Corpo com o cliente no corpo
{
  "description": "Pedido 1239",
  "amount": 9900,
  "customer": {
    "name": "João Lima",
    "email": "joao@exemplo.com.br",
    "document": "11144477735",
    "document_type": "cpf"
  }
}

Campos

CampoRegra
descriptionDescrição da cobrança, com até 255 caracteres.
amountValor cheio em centavos, a partir de 500 (R$ 5,00).
itemsOpcional, 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_referenceO identificador do pedido no seu sistema, com até 120 caracteres. Filtra a lista de faturas.
metadataOs seus dados na fatura, com os limites de Metadados.
Idempotency-KeyCabeçalho obrigatório, com um valor novo para cada fatura. Veja Idempotência.

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ódigoHTTPMensagem
PZ032403Cartão não habilitado para esta conta. Fale com o suporte para habilitar ou ofereça apenas Pix.
PZ033403Pix não habilitado para esta conta. Fale com o suporte para habilitar.
-404Cliente não encontrado para o id informado.
PZ100422A soma dos itens é diferente do valor da fatura.
PZ101422Valor fora do limite desta conta.

Os erros de autenticação, de idempotência e de validação estão no Catálogo de erros.