Boas práticas

Envio de dados

Envie todos os campos disponíveis. Quanto mais dados você fornecer, maior a eficácia das soluções contratadas. Campos como card_bin, order_number, ip_address e addresses são especialmente importantes.
Use envio em lote para grandes volumes. Em vez de enviar uma transação por requisição, agrupe até 1000 transações no endpoint /transactions/batch para reduzir overhead de rede.
Mantenha external_source e external_id consistentes. Esses campos são usados para detecção de duplicatas. Use identificadores únicos e estáveis do seu sistema de origem.
Envie transações o mais rápido possível. Quanto mais próximo do momento da venda, melhor a cobertura das soluções de prevenção.

transaction_date em ISO 8601. Use o formato completo com timezone (ex: 2026-04-01T15:30:00Z).
currency em maiúsculas. Use o código ISO 4217 com 3 letras maiúsculas (ex: USD, BRL, EUR).
card_last4 como string. Envie como string de exatamente 4 dígitos (ex: "0042", não 42).
merchant_id como UUID. Use o UUID do merchant conforme retornado pela API ou painel.

Nunca exponha seu client_secret. Trate como senha. Não inclua em código frontend, repositórios públicos ou logs.
Use sempre HTTPS. Todas as requisições devem ser feitas via HTTPS.
Implemente retry com espera progressiva. Em erro 500 (erro interno), aguarde antes de tentar novamente: 1s, 2s e depois 4s entre tentativas. No 429 não precisa chutar, a resposta traz o header Retry-After com os segundos exatos até a janela virar (ver Rate limit).

Transação única: verifique o campo data para os dados da transação criada e warnings para avisos.
Envio em lote: itere sobre results (sucessos com tx_id e warnings) e errors (falhas com external_id, status e mensagem).
Atente-se aos warnings. Não bloqueiam a criação, mas indicam campos ausentes que impactam a eficácia das soluções.
Guarde o id retornado. Você precisará dele para consultar, atualizar ou deletar a transação.

Corrija erros antes da primeira consulta. Transações utilizadas pelas soluções (ex: consultadas pela Prevenção) se tornam imutáveis. Use PATCH para corrigir dados enquanto a transação ainda não foi utilizada.