PayZu Conta Hub

Sobre o PayZu Conta Hub


Nesta páginaComo funcionaO que você consegue fazerO que você precisaRegras que valem para todas as chamadasPróximos passos

Movimente 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 aconteceSaldoAviso
Cobrança pagaCredita.PAYMENT_PAID
Depósito numa chaveCredita.DEPOSIT_RECEIVED
Saque pedidoO valor sai do disponível já no pedido.WITHDRAW_CREATED
Saque entregueNão muda: só confirma a entrega.WITHDRAW_COMPLETED
Saque que falhouO valor volta.WITHDRAW_FAILED
Transferência para outra conta PayZuResolvida 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

O que você precisa

  • Credencial: o client_id e o client_secret da 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 callbackUrl numa operação, como em Segredo dos callbacks.

Quando falta um deles, a API responde com um destes códigos.

CódigoHTTPMensagem
TOKEN_IP_NOT_ALLOWED403Esta credencial não pode ser usada a partir deste IP.
ACCOUNT_NOT_OPERABLE412Esta conta não está ativa e não pode movimentar dinheiro.
CALLBACK_SECRET_MISSING412Gere o segredo de callback da conta antes de informar uma callbackUrl.
PROVIDER_NOT_PROVISIONED412Esta 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-Key controla 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. limit vai de 1 a 100, com 20 quando omitido. Para a página seguinte, envie em cursor o nextCursor recebido; se ele não vier, a lista acabou.
  • Datas e fuso: as respostas trazem ISO 8601 em UTC. Em dateFrom e dateTo, 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 e totalDebited é o débito.
  • Erros: o corpo traz message, code e details. Trate pelo code, nunca pela message.

Próximos passos