Skip to main content
When a request times out, you don’t know whether it reached Spotflow, so you need to be able to retry without charging a customer or paying someone twice. All POST requests that create or initiate transactions take an idempotency key in the reference field of the request body. If you send two requests with the same reference, Spotflow processes it once and returns the same response for the second request.
Idempotent request

Rules

Retrying safely

1

Create the reference once

Generate it from your own record, for example your order ID, and save it before you call the API.
2

Check before you retry

If a request fails or times out, check whether it actually succeeded first. For payments, call Verify Payment with your reference. For disbursements, call Get Transfer by Reference.
3

Retry with the same reference

If the transaction doesn’t exist, send the exact same request again with the same reference.
Never generate a new reference to retry a request whose outcome you don’t know. That’s how a customer gets charged twice or a payout goes out twice.

Failed payments

A FAILED payment can’t be retried with the same reference. Create a new payment with a new reference. See Payment lifecycle.

Webhooks

Each webhook includes a unique webhook-id header. Store it and ignore events you’ve already processed, because the same event can be delivered more than once. See Webhooks.