Comece aqui

Faça sua primeira chamada


Nesta páginaEscolha o produtoObtenha a credencialGuarde o tokenFaça a primeira chamadaLeia a respostaO que vem depois

Chegue à primeira resposta da API no sandbox do PayZu Pix, que entrega a credencial na hora e sem cadastro.

Escolha o produto

ProdutoPrimeira rotaAutenticação
PayZu PixConsultar o saldoToken Bearer da conta
PayZu Conta HubGerar um token de acesso e depois Consultar o saldoCredencial trocada por token
PayZu PaymentsGerar um token de acesso e depois Consultar a cotação de uma moedaCertificado mTLS com token
PayZu GatewayListar as faturasChave de API em Authorization: Bearer
PayZu OnboardingGerar um token de acesso e depois Listar as propostasConta de serviço com troca de token
PayZu CâmbioConsultar chave de API, em produção, porque não há sandboxChave de API

Em dúvida, leia Qual produto usar.

Obtenha a credencial

No sandbox do PayZu Pix, em Credencial de sandbox, confirme o seu e-mail com o código de seis dígitos enviado a ele e receba o token, válido por 24 horas. Em produção, o token é emitido na abertura da conta.

O sandbox do PayZu Pix responde em https://pix.sandbox.payzu.dev/v1.

A credencial de sandbox e os servidores dos outros produtos estão em Ambientes.

Guarde o token

No PayZu Pix, a credencial já é o token. Guarde-o numa variável de ambiente e mande-o no header Authorization: Bearer de toda chamada.

bash
export PAYZU_TOKEN='<token recebido no sandbox>'

Se o seu produto troca credencial por token, siga o guia dele: PayZu Conta Hub, PayZu Payments ou PayZu Onboarding. A comparação está em Autenticação.

Faça a primeira chamada

bash
curl --request GET \
  --url 'https://pix.sandbox.payzu.dev/v1/user/balance' \
  --header "Authorization: Bearer $PAYZU_TOKEN"

Referência: Consultar o saldo

Para testar sem sair da documentação, abra a rota na aba API: cole o token em Credenciais, confira que o seletor ao lado do caminho está em Servidor de sandbox e clique em Try It!. A resposta aparece no console e a chamada entra em Recent Requests, no alto da página.

Leia a resposta

Os valores do PayZu Pix vêm em reais: 231.46 é R$ 231,46. balanceBlocked é o saldo que não pode ser usado agora.

Se a chamada falhar, decida pelo errorCode, nunca pela mensagem.

CódigoHTTPMensagem
PZA100401Unauthorized
PZA203403Acesso não permitido a partir do endereço de IP 203.0.113.10.
PZA205403Conta com token de saque exige IP cadastrado na whitelist. Cadastre o IP de origem (203.0.113.10) antes de operar.

No PZA100, confira o header Authorization: Bearer e se a credencial de sandbox ainda está dentro das 24 horas. Os outros dois só acontecem em produção e estão em IP cadastrado.

Guarde o requestId de qualquer erro.

É com ele que o suporte localiza a chamada. Os demais códigos estão no Catálogo de erros.