Sobre o PayZu Conta Hub
Nesta página
Como funcionaO que você consegue fazerO que você precisaRegras que valem para todas as chamadasPróximos passosMovimente a sua conta PayZu pelo seu sistema.
Como funciona
Sua aplicação troca a credencial por um token de 15 minutos e chama as rotas de /transactions com Authorization: Bearer. A cobrança gera um Pix copia e cola, e o saque e o pagamento de copia e cola saem por Pix pelo banco parceiro. As rotas GET servem para conferir e conciliar.
| O que acontece | Saldo | Aviso |
|---|---|---|
| Cobrança paga | Credita. | PAYMENT_PAID |
| Depósito numa chave | Credita. | DEPOSIT_RECEIVED |
| Saque pedido | O valor sai do disponível já no pedido. | WITHDRAW_CREATED |
| Saque entregue | Não muda: só confirma a entrega. | WITHDRAW_COMPLETED |
| Saque que falhou | O valor volta. | WITHDRAW_FAILED |
| Transferência para outra conta PayZu | Resolvida na própria resposta, ou REQUESTED com o valor reservado se o banco parceiro não responder a tempo. | INTERNAL_TRANSFER_SENT |
O que você consegue fazer
Cobrança copia e cola, devolução total ou parcial e depósitos recebidos numa chave da conta.
Pagar com PixEnvio para uma chave, pagamento de copia e cola e transferência entre contas PayZu.
ContaSaldo e extrato, limites e tarifas, métricas, chaves Pix e infrações MED.
WebhooksUm aviso assinado por evento, nos webhooks cadastrados e, se informada, também na callbackUrl da operação.
O que você precisa
- Credencial: o
client_ide oclient_secretda conta, trocados por token em Gerar um token de acesso. - IP aceito: quando a credencial tem lista de IPs, toda chamada precisa sair de um deles, inclusive a troca do token.
- Conta aberta e ativa: as rotas que movem dinheiro só respondem numa conta ativa.
- Segredo dos callbacks: criado antes de informar
callbackUrlnuma operação, como em Segredo dos callbacks.
Quando falta um deles, a API responde com um destes códigos.
| Código | HTTP | Mensagem |
|---|---|---|
TOKEN_IP_NOT_ALLOWED | 403 | Esta credencial não pode ser usada a partir deste IP. |
ACCOUNT_NOT_OPERABLE | 412 | Esta conta não está ativa e não pode movimentar dinheiro. |
CALLBACK_SECRET_MISSING | 412 | Gere o segredo de callback da conta antes de informar uma callbackUrl. |
PROVIDER_NOT_PROVISIONED | 412 | Esta conta ainda não terminou de ser aberta. |
Os caminhos são os mesmos no sandbox e na produção.
O sandbox responde em https://api.sandbox.payzu.dev/api/v1 e a produção em https://api.hub.payzu.com.br/api/v1.
Regras que valem para todas as chamadas
- Valores: inteiros em centavos. Um saque de R$ 100,00 leva
"amount": 10000. Percentuais, como nas métricas, vêm em basis points. - Conta: sempre a da credencial. Nenhuma rota recebe identificador de conta, e um recurso de outra conta responde
404, como se não existisse. - Cobrança repetida: o seu identificador é
externalRef, único na conta. Reenviar com os mesmos dados retorna a cobrança existente, e com dados diferentes dá409. - Saída repetida: no saque, no pagamento de copia e cola, na transferência e na devolução, o cabeçalho opcional
Idempotency-Keycontrola a repetição. A mesma chave com os mesmos dados retorna a operação original, e com outros dados dá409. - Paginação: as listas usam cursor.
limitvai de 1 a 100, com 20 quando omitido. Para a página seguinte, envie emcursoronextCursorrecebido; se ele não vier, a lista acabou. - Datas e fuso: as respostas trazem ISO 8601 em UTC. Em
dateFromedateTo, uma data sem hora, ou um instante exatamente à meia-noite UTC, cobre o dia inteiro no horário de Brasília. - Tarifas: no que entra, a tarifa sai do valor e
netAmounté o crédito. No que sai, ela se soma ao valor etotalDebitedé o débito. - Erros: o corpo traz
message,codeedetails. Trate pelocode, nunca pelamessage.