Boas práticas
Nesta página
Identifique cada operação com clientReferencePrefira o aviso à consultaConsulte a chave antes de pagarTrabalhe com valores em reaisPagine as listasProteja o acesso e os avisosIdentifique cada operação com clientReference
clientReference aceita até 64 caracteres em POST /pix, POST /withdraw, POST /withdraw/qrcode, POST /internal-transfer e POST /refund/{transactionId}. Uma referência já usada retorna a operação criada com ela, em vez de criar outra.
Faça
- Gere a referência antes da chamada e grave-a junto com o pedido.
- Depois de um timeout, repita a chamada com a mesma referência.
- Consulte pela referência: GET /pix e GET /withdraw aceitam
clientReference.
Evite
- Trocar a referência ao repetir uma chamada que pode ter sido criada: a PayZu trata como operação nova.
- Reaproveitar a referência com valor ou destino diferentes: em saque, pagamento de QR Code, transferência e devolução, a resposta é
409. Veja Idempotência.
Prefira o aviso à consulta
A PayZu avisa as mudanças pelo callbackUrl da transação e pelos webhooks da conta, cada canal com o seu conjunto de eventos. Veja Webhooks e callbacks.
Faça
- Grave o aviso e responda
2xxantes de processar: a PayZu espera no máximo 5 segundos e, sem2xx, faz até 12 tentativas no total. - Deduplique os avisos de transação por
id+updatedAte os de infração só porinfraction.id+infraction.updatedAt. - Acompanhe as devoluções parciais por
TRANSACTION_REFUNDED: o evento sai a cada devolução concluída, comstatus: COMPLETEDenquanto a soma devolvida não alcança o valor da transação eREFUNDEDquando alcança.
Evite
- Confiar na ordem de chegada. Use
updatedAtpara avisos de transação einfraction.updatedAtpara avisos de infração. - Esperar
TRANSACTION_EXPIREDpara liberar estoque: o evento depende da instituição. No fim deexpiresIn, consulte GET /pix.
Consulte a chave antes de pagar
GET /pix/key retorna o titular e a instituição de uma chave. Veja Consultar uma chave Pix e Tipos de chave Pix.
Faça
- Envie a chave num dos formatos aceitos: CPF, CNPJ, e-mail, telefone com
+55(+5511999999999) ou EVP. - Ao receber
429, espereretryAfterSeconds(30 segundos nas consultas de chave) antes de consultar de novo.
Evite
- Enviar
pixTypediferente do tipo da chave consultada em POST /withdraw. - Repetir a consulta de uma chave que voltou
404: a chave não existe no DICT.
Trabalhe com valores em reais
Nos campos de valor, 10.9 é R$ 10,90.
Faça
- Leia os limites da sua conta em GET /user:
cashInTicketMinecashInTicketMaxpor cobrança,cashOutTicketMinecashOutTicketMaxpor saque ou transferência. - Envie no máximo duas casas decimais em cobrança, saque e transferência.
- Concilie
serviceFeeChargedcom todas as casas que vierem; a tarifa pode ter mais de duas.
Evite
- Somar
refundAmountdo aviso sem converter: no aviso ele chega como texto ("30.5"). - Arredondar a tarifa antes de somar o período.
Pagine as listas
Cada lista tem o seu controle de página e o seu limite por página. Veja Paginação.
Faça
- Em GET /user/transactions, filtre por
dateFromedateToe uselimitaté 1.000; a resposta traztotalepages. - Em GET /user/callbacks, use
limitaté 100 e pare quandohasNextPageforfalse. - Para o fechamento do dia, gere o CSV em POST /user/report em vez de percorrer páginas.
Evite
- Pedir
limitacima do máximo da rota: a resposta é400, exceto em depósitos via chave, em que a API usa o padrão no lugar do valor recusado. Veja Paginação.
Proteja o acesso e os avisos
Veja Autenticação.
Faça
- Se a conta envia Pix pela API, cadastre o IP de saída antes da primeira chamada: sem nenhum IP cadastrado, toda rota responde
403, e com IP cadastrado as chamadas de outro IP também. Veja IP cadastrado. - Crie o segredo dos callbacks em POST /user/callbacks/secret e cadastre webhooks com
generateSecret: true. - Rejeite aviso sem assinatura no canal que tem segredo: o
callbackUrl, quando a conta tem segredo de callback, e cada webhook comhasSecret: true. - Troque o segredo se houver suspeita de vazamento; a troca vale na hora.
Evite
- Validar o aviso com o segredo do canal errado: o
callbackUrlusa o segredo da conta, e cada webhook usa o seu.
Teste tudo isso no sandbox antes da produção.
O servidor é https://pix.sandbox.payzu.dev/v1. Os caminhos são os mesmos; muda só o servidor e o token.