PayZu PixApoio

Boas práticas


Nesta páginaIdentifique cada operação com clientReferencePrefira o aviso à consultaConsulte a chave antes de pagarTrabalhe com valores em reaisPagine as listasProteja o acesso e os avisos

Identifique 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 2xx antes de processar: a PayZu espera no máximo 5 segundos e, sem 2xx, faz até 12 tentativas no total.
  • Deduplique os avisos de transação por id + updatedAt e os de infração só por infraction.id + infraction.updatedAt.
  • Acompanhe as devoluções parciais por TRANSACTION_REFUNDED: o evento sai a cada devolução concluída, com status: COMPLETED enquanto a soma devolvida não alcança o valor da transação e REFUNDED quando alcança.

Evite

  • Confiar na ordem de chegada. Use updatedAt para avisos de transação e infraction.updatedAt para avisos de infração.
  • Esperar TRANSACTION_EXPIRED para liberar estoque: o evento depende da instituição. No fim de expiresIn, 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, espere retryAfterSeconds (30 segundos nas consultas de chave) antes de consultar de novo.

Evite

  • Enviar pixType diferente 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: cashInTicketMin e cashInTicketMax por cobrança, cashOutTicketMin e cashOutTicketMax por saque ou transferência.
  • Envie no máximo duas casas decimais em cobrança, saque e transferência.
  • Concilie serviceFeeCharged com todas as casas que vierem; a tarifa pode ter mais de duas.

Evite

  • Somar refundAmount do 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

Evite

  • Pedir limit acima 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 com hasSecret: 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 callbackUrl usa 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.