PayZu Conta HubApoio

Boas práticas


Nesta páginaIdempotency-Key nas saídasValores em centavosPaginação por cursorSegredo dos callbacks antes de cobrarWebhook primeiro, consulta depoisToken e cotas

Evite saídas duplicadas, conciliações quebradas e avisos forjados seguindo as regras que o PayZu Conta Hub aplica em cada chamada.

Idempotency-Key nas saídas

Saque, pagamento de copia e cola, transferência entre contas e devolução aceitam o cabeçalho Idempotency-Key, que vale por conta e não expira. Com ela, uma retentativa com os mesmos dados retorna a operação original em vez de criar outra. A chave é opcional, mas sem ela a API não reconhece a repetição.

Faça:

  • Gere uma chave nova por operação (um UUID serve) e grave-a junto com o pedido antes de chamar a API.
  • Na retentativa por timeout ou 502, reenvie exatamente a mesma chave e o mesmo corpo.
  • Use de 1 a 255 caracteres ASCII visíveis, sem espaço.

Evite:

  • Reaproveitar a chave em outra operação.
  • Repetir um saque ou uma devolução sem chave depois de um erro de rede.

No mesmo tipo de operação, a chave repetida com outros dados retorna 409. Num tipo diferente, a chave não é reconhecida e cria uma operação nova.

OperaçãoConfere a chaveCódigo do 409
Saque e pagamento de copia e colaJuntosWITHDRAW_IDEMPOTENCY_KEY_REUSED
Transferência entre contasÀ parteTRANSFER_IDEMPOTENCY_KEY_REUSED
DevoluçãoÀ parteREFUND_IDEMPOTENCY_KEY_REUSED

Valores em centavos

Todo valor é um inteiro em centavos, e 1500 são R$ 15,00. Percentuais vêm em basis points: 150 são 1,5%.

Faça:

  • Guarde e calcule em inteiros; converta para reais só na exibição.
  • Leia netAmount como o que entrou na cobrança e totalDebited como o que saiu no saque e na devolução.
  • Valide o valor contra Limites e tarifas antes de enviar.

Evite:

  • Enviar reais. Em JSON, 15.00 é o número 15, ou seja, 15 centavos. Valor em texto, como "15,00", não é inteiro e é recusado.
  • Somar amount do extrato sem olhar o sinal: entrada é positiva, saída é negativa.

Paginação por cursor

As listas de cobranças, saques, transferências, infrações e o extrato paginam por cursor. A resposta traz nextCursor enquanto houver mais páginas; a última vem sem o campo.

Faça:

  • Repita a chamada com cursor igual ao nextCursor anterior e com os mesmos filtros.
  • Use limit até 100 e dateFrom e dateTo para fechar o período.
  • Na lista de cobranças, se o cursor for recusado como inválido, recomece da primeira página.

Evite:

  • Enviar page ou outro parâmetro que a rota não conhece: a resposta é 400 com REQUEST_UNKNOWN_QUERY_PARAM.

Segredo dos callbacks antes de cobrar

Operação com callbackUrl exige o segredo dos callbacks da conta. Sem ele, a API responde 412 com CALLBACK_SECRET_MISSING.

Faça:

  • Crie o segredo na configuração inicial da conta, em Segredo dos callbacks, e guarde-o no seu cofre: ele aparece uma única vez.
  • Confira hasCallbackSecret no deploy de um ambiente novo.
  • Ao trocar o segredo, siga a ordem de Trocar o segredo dos callbacks: o anterior para de valer na hora.

Evite:

  • Confundir os segredos: o segredo dos callbacks assina a callbackUrl, e o secret do webhook assina o webhook cadastrado.

Webhook primeiro, consulta depois

O estado final de saque, devolução e cobrança chega por webhook; a resposta 201 do saque não é dinheiro entregue.

Faça:

  • Responda 2xx em até 10 segundos; sem isso, a entrega volta como nova tentativa.
  • Deduplique pelo id do envelope: a mesma entrega pode chegar mais de uma vez, com sentAt igual.
  • Confira a assinatura sobre o corpo cru, em tempo constante e com tolerância de tempo, como em Verificar a assinatura.
  • Use externalRef e metadata na cobrança para casar o evento com o seu pedido sem consulta extra.

Evite:

  • Consultar a operação em loop no lugar do webhook. Use a consulta para conciliar e para recuperar um aviso que não chegou.
  • Processar o data antes de validar a assinatura.
  • Deixar o endpoint fora do ar. Enquanto uma entrega espera nova tentativa, os avisos seguintes da conta também esperam, inclusive os de outros webhooks.

Token e cotas

O token de POST /oauth/token vale 15 minutos. A rota limita as trocas por client_id e por IP, e a lista de IPs da credencial vale nela também.

Faça:

  • Guarde o token e renove-o antes de expires_in acabar, com uma troca por processo.
  • Ao receber 429, aguarde Retry-After ou details.retryAfterSeconds.

Evite:

  • Repetir em loop um 403: a recusa não muda com nova tentativa.
  • Pedir um token a cada requisição: a troca passa a responder 429 com AUTH_TOO_MANY_REQUESTS.
  • Chamar a API de um IP que não está na lista da credencial, inclusive em ambientes efêmeros sem IP fixo.