Ambientes
Nesta página
ServidoresComo obter a credencialAntes de ir para produçãoErros de liberaçãoPróximos passosDesenvolva no sandbox de cada produto e vá para a produção trocando só o host e a credencial, porque o caminho de cada rota é o mesmo nos dois ambientes.
Servidores
| Servidor de produção | Produtos atendidos | No sandbox |
|---|---|---|
https://api.payzu.processamento.com/v1 | PayZu Pix | https://pix.sandbox.payzu.dev/v1 |
https://api.hub.payzu.com.br/api/v1 | PayZu Conta Hub | https://api.sandbox.payzu.dev/api/v1 |
https://api.payzu.io/v1 | PayZu Payments e recorrência no cartão | https://api.sandbox.payzu.dev/v1 |
https://api.gateway.payzu.com.br | API e checkout do PayZu Gateway | https://api.sandbox.payzu.dev |
https://api.payzu.dev | PayZu Onboarding | https://api.sandbox.payzu.dev |
https://api.exchange.payzu.com.br | PayZu Câmbio | Não há sandbox |
Na referência, o seletor ao lado do caminho de cada rota troca entre os dois servidores, e o Try It! começa no sandbox. No PayZu Câmbio, o seletor mostra só o servidor de produção.
No PayZu Gateway e no PayZu Onboarding, o /v1 já faz parte do caminho.
As rotas são /v1/invoices e /v1/proposals, e a troca de token do PayZu Onboarding fica na raiz, em /oauth/token. Não acrescente o prefixo ao host.
Como obter a credencial
| Produto | Sandbox | Produção |
|---|---|---|
| PayZu Pix | Credencial de 24 horas, sem cadastro, em Credencial de sandbox | Token Bearer emitido na abertura da conta |
| PayZu Conta Hub | client_id e client_secret trocados em POST /oauth/token, ou o token da credencial direto no Bearer | A mesma forma, com a credencial de produção |
| PayZu Payments e recorrência no cartão | client_id e client_secret trocados em POST /token, mais o certificado mTLS quando a credencial o exige, que é o padrão | A mesma forma, com a credencial de produção |
| Checkout do PayZu Gateway | Chave de checkout da conta, no header x-checkout-key | A chave de checkout de produção |
| API do PayZu Gateway | Chave de API criada no painel, em Authorization: Bearer | A chave de API de produção |
| PayZu Onboarding | Conta de serviço com autorização cadastrada pela PayZu; POST /oauth/token troca o ID token dela pelo token da API | A mesma troca, no servidor de produção |
| PayZu Câmbio | Não há sandbox | Chave de API criada no painel, em Authorization: Bearer |
- Sandbox do PayZu Pix. Você confirma o seu e-mail com o código de seis dígitos enviado a ele e recebe o token.
- Checkout do PayZu Gateway. As rotas de fatura e de link do checkout não pedem chave.
O passo a passo de cada forma está em Autenticação.
Antes de ir para produção
| Exigência | Onde vale |
|---|---|
| IP na lista da conta | Todas as rotas, inclusive cobrança e consulta |
| Pelo menos um IP cadastrado | Conta que envia Pix pela API |
| Contrato assinado pelo representante legal | Rotas que criam ou alteram algo: cobrar, sacar, devolver, cadastrar webhooks, gerar relatórios e reenviar callbacks |
O sandbox do PayZu Pix não confere IP nem contrato. Veja IP cadastrado.
| Exigência | Onde vale |
|---|---|
| IP na lista da credencial | Todas as rotas autenticadas, inclusive a troca de token |
| Exigência | Onde vale |
|---|---|
| Certificado mTLS, por padrão | Todas as rotas do PayZu Payments e da recorrência no cartão, nos dois ambientes |
A PayZu pode desligar essa exigência em cada credencial. Veja Certificado mTLS.
| O que muda | Sandbox | Produção |
|---|---|---|
| Código de confirmação do contato | Sempre 000000; nenhuma mensagem sai ao cliente | Vai ao contato do cliente |
| Consultas cadastrais e análise | Dados de teste | Fontes reais |
A autorização da conta de serviço, a audience e o destino dos callbacks são cadastrados em cada ambiente.
Erros de liberação
| Código | HTTP | Mensagem |
|---|---|---|
PZA203 | 403 | Acesso não permitido a partir do endereço de IP 203.0.113.10. |
PZA205 | 403 | Conta com token de saque exige IP cadastrado na whitelist. Cadastre o IP de origem (203.0.113.10) antes de operar. |
PZA206 | 403 | Conta aguardando assinatura do contrato. Assine o contrato enviado ao representante legal para liberar as operações. |
TOKEN_IP_NOT_ALLOWED | 403 | Esta credencial não pode ser usada a partir deste IP. |
As mensagens de PZA203 e PZA205 trazem o IP de origem da chamada.
Use esse endereço quando a saída passa por proxy ou NAT.