Every API call can include a Nonce, which is a random UUID string defined by the partner, in the format (example): "dae62579-4ad6-47e6-acea-91ff3e2f8c9c". For simplification purposes, it is optional, but it is highly recommended to be used the right way.Each new request intention must have a new nonce.
If you do not send a nonce, by default a new one will be generated and returned via headers in the request.
How to Use the Nonce#
To send a nonce to our API, use the HTTP header in the following format:Replacing <nonce> with your client-side generated nonce in the format random UUID string.What is a Nonce?#
A nonce is a unique value generated by the client to represent a single, specific request INTENT. If a request fails or times out and needs to be retried, the same nonce must be reused to prevent duplicate actions. For new requests with different intents, a new nonce should be generated. Unlike transaction IDs (returned in headers) or entry IDs (typically in the response body), a nonce is created by the client to uniquely define the intent behind an API call.Retry Attempts#
For retries of the same request, always reuse the original nonce. Recalling the same API with the same parameters and nonce multiple times is safe and will not cause duplication.Using a new nonce (or omit it) for a retry may result in the system treating it as a new transaction, potentially duplicating the operation.If you choose not to pass a nonce, make sure that the library you are using does not perform an automatic retry to avoid unintentionally duplicating actions.
Why use a nonce? How is it different from other IDs?#
Transaction IDs, entry IDs and nonce serve different purposes.A transaction ID tracks the server's processing of a request for debugging or auditing. It is generated on the server side, logged at every step of the system in the backend, and returned to the client via header.An entry ID, also generated on the server, uniquely identifies a resource created by the request. You can delete or retrieve the status of an entry using the entry ID.A nonce, on the other hand, prevents duplicate actions by ensuring client-side INTENT, focusing on the request rather than the server's response. It is usually generated on the client side to express an intention. 