Como começar a usar o PayZu Gateway
Siga estes passos para fazer a primeira cobrança pela API e, depois, levar a integração para a produção.
Crie a chave de API
A conta do PayZu Gateway nasce no primeiro acesso ao painel, e é lá que você cria a chave de API. Veja Autenticação e Ambientes de teste e produção.
A chave aparece uma única vez, na criação.
Guarde a chave no seu servidor, fora do código e do navegador.
Teste a chave listando a fatura mais recente da conta:
curl "https://api.sandbox.payzu.dev/v1/invoices?limit=1" \
-H "Authorization: Bearer SUA_CHAVE_DE_API"Com a chave aceita, a resposta é 200, com a fatura em items, ou com items vazio numa conta sem faturas. Na Referência API, o mesmo teste está em Listar as faturas: cole a chave em Credenciais e clique em Try It!.
Faça a primeira cobrança
Crie uma fatura com a descrição e o valor em centavos. Para o cliente escolher o meio na página da PayZu, mande a ele a url da resposta. Para mostrar o Pix no seu sistema, envie também payment e o cliente.
curl -X POST https://api.sandbox.payzu.dev/v1/invoices \
-H "Authorization: Bearer SUA_CHAVE_DE_API" \
-H "Idempotency-Key: 3e7a1c5b-8d2f-4a9e-b6c4-0f1d2e3a4b5c" \
-H "Content-Type: application/json" \
-d '{
"description": "Pedido 1242",
"amount": 9900
}'curl -X POST https://api.sandbox.payzu.dev/v1/invoices \
-H "Authorization: Bearer SUA_CHAVE_DE_API" \
-H "Idempotency-Key: 7d2e9b4c-1f3a-4c8e-b5d6-0a9f8e7c6b5a" \
-H "Content-Type: application/json" \
-d '{
"description": "Pedido 1235",
"external_reference": "pedido-1235",
"amount": 5990,
"customer_id": "cus_bdQT0ls1QMIXVuhngvhbwC",
"payment": {
"method": "pix",
"pix": { "expires_in": 3600 }
}
}'{
"id": "in_2QwT6nXcVb4LzYm9KdRh5E",
"status": "pending",
"url": "https://invoice.payzu.com.br/pay/in_2QwT6nXcVb4LzYm9KdRh5E",
"description": "Pedido 1242",
"amounts": {
"subtotal": 9900,
"discount": 0,
"total": 9900,
"paid": 0,
"refunded": 0
},
"customer": null,
"payments": []
}{
"id": "in_5Hn9WqZc2LmXv6BtYr1dKe",
"status": "pending",
"url": "https://invoice.payzu.com.br/pay/in_5Hn9WqZc2LmXv6BtYr1dKe",
"payments": [
{
"id": "pay_EHbu1cBNxmis3c7Ftz2Dg7",
"status": "pending",
"method": "pix",
"amount": 5990,
"pix": {
"qr_code_text": "00020126MOCKEHbu1cBNxmis3c7Ftz2Dg7",
"expires_at": "2026-11-11T16:20:59.344Z",
"end_to_end_id": null,
"payer": null
}
}
]
}- Resposta:
201, com a faturapending. No Pix, o copia e cola vem empayments[0].pix.qr_code_text. - Cliente: com
payment, a fatura precisa de cliente. Troque ocustomer_iddo exemplo peloidde um cliente da sua conta, criado em Cadastrar um cliente, ou envie o cliente inteiro emcustomer. Idempotency-Key: cabeçalho obrigatório, com um valor novo para cada fatura.- Recorrência: a fatura não depende dela.
Os campos estão em Criar uma fatura e Vender no Pix.
Receba os avisos
Cadastre um webhook com o endereço do seu sistema e os eventos que você quer receber. Guarde o segredo que vem na resposta, porque ele só aparece na criação e na troca.
Quando o cliente paga, a fatura passa a paid e sai o evento invoice.paid, com a fatura em data.invoice. Antes de dar baixa no pedido, confira a assinatura de cada aviso. Se o aviso não chegar, consulte a fatura pelo id, como em Consultar faturas.
Passe para a produção
Em produção, chame https://api.gateway.payzu.com.br, com os mesmos caminhos.
| Recurso | Quem libera | Sem a liberação |
|---|---|---|
| Cartão | Suporte da PayZu | As cobranças no cartão respondem 403. |
| Pix | Suporte da PayZu | As cobranças no Pix respondem 403. |
| Recorrência | Você, no painel | As rotas de planos, assinaturas e configurações respondem 404. As faturas funcionam sem ela. |
Veja Ambientes de teste e produção e o Checklist de produção.