Idempotency

The API supports idempotent requests to safely retry operations without risk of performing them twice. This is important for payment creation — if a network error occurs mid-request, you can retry with the same idempotency key and either get the original result or learn that the request is still in progress.

How it works

Pass an Idempotency-Key header with any mutating request (create, update, delete). If the API has seen that key before for your account, it returns the cached result instead of executing the request again.

curl -X POST https://api.synaptopay.com/v1/accounts/acct_YOUR_ACCOUNT/payment-intents \
  -H "Authorization: Api-Key $API_KEY" \
  -H "Idempotency-Key: my-unique-key-123" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "10000",
    "currency": "GBP"
  }'

The key can be up to 255 characters. Allowed characters are letters, digits, and ._:+/=-. A UUID is a good choice.

Key rules

• Keys are scoped to your account — different accounts can use the same key without conflict
• The request body must be identical when retrying with the same key. If the body differs, the API returns an error
• If a request with the same key is already in progress, the API rejects the duplicate with an error
• Keys are stored for 96 hours, after which they can be reused
• GET and list requests are not idempotent — they always execute normally

When to use idempotency keys

Idempotency keys are optional — if you omit the header, the API generates a random key internally and the request succeeds normally. However, without an explicit key, retries won't be deduplicated. We recommend always passing a key when creating payment intents, especially with confirm: true, so you can safely retry without risking a double charge.