A coleção oficial pronta pra rodar: importa com um clique, já vem com o Bearer configurado e três ambientes montados, incluindo o sandbox público pra você testar antes de ter credencial de produção.
A collection oficial PayZu Pix está publicada em dev.payzu.com.br (Postman) com Bearer Auth via {{token}} e 3 ambientes prontos: Sandbox, Production e Mock.
O JSON servido em docs.payzu.com.br/payzu-pix.postman_collection.json cobre as 48 rotas /v1. As pastas seguem o caminho da rota, um segmento por pasta: POST /user/callbacks/resend/webhook fica em user › callbacks › resend › webhook. Cada request traz um exemplo de resposta salvo por status.
Importar a collection
Abrir no PostmanOu via URL no Postman: Import → Link:
https://docs.payzu.com.br/payzu-pix.postman_collection.jsonSetup em 3 passos
Importar no seu workspace
Clica em Run in Postman acima. A collection é forkada pro seu workspace pessoal, com toda a estrutura: folders, autenticação, exemplos.
Configurar o token
Na collection PayZu Pix → aba Variables:
| Variável | Valor |
|---|---|
baseUrl | https://api.payzu.processamento.com/v1 (padrão) |
token | Seu Bearer token PayZu |
baseUrl e token são as únicas variáveis da collection: a autenticação fica no nível dela e cada requisição herda o header Authorization: Bearer {{token}}, sem token próprio. Isso descreve o JSON servido em docs.payzu.com.br; se no seu fork alguma requisição tiver token próprio, ele veio de uma cópia antiga, e reimportar pelo link resolve.
Testar uma chamada
Antes de mandar qualquer coisa, troque o baseUrl para o sandbox (https://pix.sandbox.payzu.dev/v1) ou selecione o environment Sandbox.
Com o baseUrl padrão você está em produção. A cobrança criada é real, e pagar o QR Code move dinheiro de verdade.
Aí sim: pix → Create Charge (Pix deposit) → Send. O exemplo já vem preenchido com amount e clientReference, e volta o qrCodeText.
Sandbox: o jeito recomendado de testar sem produção
Troque o baseUrl para o sandbox e rode a collection inteira contra uma API de verdade, com credencial de 24 horas e sem cadastro:
https://pix.sandbox.payzu.dev/v1São as mesmas rotas /v1, então o que funciona aqui funciona em produção trocando só o host. Diferente do mock, o sandbox guarda estado: a cobrança que você cria pode ser paga, o saque muda de status e o webhook chega de verdade no seu endpoint.
Mock Server
O mock existe para o caso em que você ainda não quer nem credencial de sandbox, ou precisa contornar CORS em ferramenta web. Ele devolve exemplo fixo e não guarda estado.
https://a8aa4f94-6b53-4994-bc60-7b2347f008e1.mock.pstmn.io/v1Mantenha o /v1 no fim da URL. Sem ele o mock responde 404 em tudo.
| Request | Resposta mock |
|---|---|
POST /v1/pix | { id, status: "PENDING", amount, type: "DEPOSIT", qrCodeText, qrCodeBase64, qrCodeUrl } |
GET /v1/pix?clientReference=... | o mesmo objeto, sempre PENDING |
GET /v1/user/balance | { balanceAvailable: 231.46, balanceBlocked: 0 } |
O mock devolve sempre o mesmo exemplo, independente do que você mandar: o amount da resposta não acompanha o da requisição e o status nunca avança. Para ver transação mudar de estado, use o sandbox.
Boas práticas
- Crie um fork da collection oficial em vez de editar a original. Forks recebem updates upstream.
- Use environments pra trocar
baseUrlentre sandbox e produção (https://pix.sandbox.payzu.dev/v1vshttps://api.payzu.processamento.com/v1). - Snippets de código: clica em
</>no canto direito de qualquer request pra exportar em curl, Node, Python, Go, PHP, etc. - Monitor: ative Postman Monitor pra testar a API a cada 5 min e receber alerta se cair.