Boas práticas
Nesta página
Idempotency-Key nas saídasValores em centavosPaginação por cursorSegredo dos callbacks antes de cobrarWebhook primeiro, consulta depoisToken e cotasEvite 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ção | Confere a chave | Código do 409 |
|---|---|---|
| Saque e pagamento de copia e cola | Juntos | WITHDRAW_IDEMPOTENCY_KEY_REUSED |
| Transferência entre contas | À parte | TRANSFER_IDEMPOTENCY_KEY_REUSED |
| Devolução | À parte | REFUND_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
netAmountcomo o que entrou na cobrança etotalDebitedcomo 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
amountdo 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
cursorigual aonextCursoranterior e com os mesmos filtros. - Use
limitaté 100 edateFromedateTopara fechar o período. - Na lista de cobranças, se o cursor for recusado como inválido, recomece da primeira página.
Evite:
- Enviar
pageou outro parâmetro que a rota não conhece: a resposta é400comREQUEST_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
hasCallbackSecretno 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 osecretdo 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
2xxem até 10 segundos; sem isso, a entrega volta como nova tentativa. - Deduplique pelo
iddo envelope: a mesma entrega pode chegar mais de uma vez, comsentAtigual. - Confira a assinatura sobre o corpo cru, em tempo constante e com tolerância de tempo, como em Verificar a assinatura.
- Use
externalRefemetadatana 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
dataantes 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_inacabar, com uma troca por processo. - Ao receber
429, aguardeRetry-Afteroudetails.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
429comAUTH_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.