Best practices

Sending data

Send every field you have. The more data you provide, the more effective the subscribed solutions are. Fields such as card_bin, order_number, ip_address and addresses are especially important.
Use batch upload for large volumes. Instead of sending one transaction per request, group up to 1000 transactions on the /transactions/batch endpoint to reduce network overhead.
Keep external_source and external_id consistent. These fields are used for duplicate detection. Use unique and stable identifiers from your source system.
Send transactions as soon as possible. The closer to the moment of sale, the better the coverage of the prevention solutions.

transaction_date in ISO 8601. Use the full format with timezone (e.g. 2026-04-01T15:30:00Z).
currency in uppercase. Use the 3-letter uppercase ISO 4217 code (e.g. USD, BRL, EUR).
card_last4 as a string. Send it as a string of exactly 4 digits (e.g. "0042", not 42).
merchant_id as a UUID. Use the merchant UUID as returned by the API or the dashboard.

Never expose your client_secret. Treat it like a password. Do not include it in frontend code, public repositories or logs.
Always use HTTPS. Every request must be made over HTTPS.
Implement retry with progressive backoff. On a 500 error (internal error), wait before trying again: 1s, 2s and then 4s between attempts. On a 429 there is no need to guess: the response carries the Retry-After header with the exact seconds until the window resets (see Rate limit).

Single transaction: check the data field for the created transaction data and warnings for notices.
Batch upload: iterate over results (successes with tx_id and warnings) and errors (failures with external_id, status and message).
Pay attention to warnings. They do not block creation, but they point to missing fields that affect how effective the solutions are.
Store the returned id. You will need it to retrieve, update or delete the transaction.

Fix mistakes before the first query. Transactions used by the solutions (e.g. queried by Prevention) become immutable. Use PATCH to fix data while the transaction has not been used yet.