Boas práticas de integração

Boas práticas#

• Armazene clientChargeId, paymentId, valor e situação de forma correlacionada.
• Gere um novo clientChargeId para cada cobrança.
• Em timeout depois de uma criação, não gere outra cobrança automaticamente sem conciliação: isso pode produzir duplicidade.
• Consulte pagamentos pendentes com intervalo progressivo e limite de tentativas. Evite polling agressivo.
• Só marque como pago quando a consulta retornar Paid.
• No cartão, trate Challenge como continuação da mesma transação, nunca como uma nova cobrança.
• Reutilize o token de autenticação até perto de expiresIn e implemente a renovação protegida contra chamadas concorrentes.
• Valide no seu backend a soma dos itens, os documentos, a validade do cartão e os campos obrigatórios antes de chamar a API.

Checklist de integração#

1. A x-api-key e as credenciais pertencem ao mesmo ambiente.
2. O token é armazenado e reutilizado até expiresIn.
3. Authorization é enviado sem o prefixo Bearer.
4. Os valores são inteiros em centavos.
5. A soma dos itens menos o desconto é igual ao total.
6. CPF/CNPJ e e-mail são válidos.
7. O IP público real e o User-Agent do comprador são enviados.
8. O sessionId é único por tentativa e reutilizado em todo o fluxo 3DS.
9. O número do cartão só vai para a tokenização e o CVV nunca é armazenado.
10. O fluxo sem desafio foi testado.
11. O fluxo com Challenge, callback e validação foi testado.
12. O pedido só é confirmado quando a consulta do paymentId retorna Paid.
13. Logs e alertas não contêm credenciais nem dados sensíveis.