Skip to main content
Creating a transaction moves money, so a request that times out leaves you unsure whether it happened. Two fields in meta let you retry safely. Both are required on POST /transaction. The API checks each one separately, and each must be unique within your business. A request that reuses either value is a duplicate.

​
What a duplicate returns

A duplicate returns 409 DUPLICATE_REQUEST and creates nothing:
  • The API does not return the original transaction. The 409 tells you the key or reference is taken. To get the transaction, look it up (see below).
  • The rest of the request is not compared. The same key with a different amount, customer, or currency is still a duplicate. The API does not apply the new request.
  • Two cases return the same code. The first transaction already exists, or it is still being processed and a second request arrived at the same time. The message says which.
  • Your business only. Another business can use the same key or reference.

​
Keys and references are used once

Any transaction that was created keeps its key and reference, including one that later fails. To try a failed payout again, create a new transaction with a new idempotencyKey and a new reference. The one case where you reuse a key is a retry of a request whose outcome you don’t know, described next.

​
Retrying after an error or a timeout

Decide from what you received: A failure before any money moves frees the key, so retrying a request that the API refused is safe.

​
Look up the transaction

Find a transaction by the reference you sent:
An empty list means no transaction was created with that reference. The result carries the transaction’s status, and you also receive its webhooks. Use whichever you prefer to confirm the outcome.

​
Swaps keep their key

A SWAP keeps its idempotency key even when it fails, so you can’t retry a failed swap with the same key. Check its status with the lookup above. To make a new attempt, send a new idempotencyKey and a new reference.

​
Choosing keys and references

  • Generate a new UUID for every transaction attempt, and reuse it only to retry that same attempt.
  • Use your own order or payment ID as the reference, so you can find the transaction later.
  • Store the key with the order before you send the request. After a crash, you can then retry with the same key.
  • Don’t build keys from values that repeat, such as a customer ID or an amount.