Idempotency ensures that the same API call doesn’t create duplicates, even when retried due to network issues.

​
Why it matters

Without idempotency, a connection timeout or retry can cause the same payment to be processed twice — resulting in double charges for your customer.

​
How it works

1

Generate a unique key

For each payment, generate a UUID v4 as your idempotency key.
2

Send the key with your request

Add the Idempotency-Key header to your payment creation request:
curl -X POST https://api.simiz.io/v1/transactions \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -d '{
    "amount": 5000,
    "currency": "XAF",
    "payment_method": "ORANGE_MONEY",
    "payer": {
      "phone": "237690000000",
      "name": "John Doe"
    },
    "description": "Order #12345"
  }'
3

Handle the response

  • First request → Creates the transaction normally
  • Subsequent requests with the same key → Returns the existing transaction without creating a new one

​
Key format

PropertyValue
FormatAny string up to 255 characters (UUID v4 recommended)
UniquenessOne key per operation — reuse the same key only for retries

​
Best practices

Use UUID v4

UUID v4 guarantees sufficient uniqueness. Avoid time-based or sequential keys.

One key per operation

Create a new key for each new operation. Reuse the same key only for retries of the same request.

Store the key

Save the idempotency key alongside the transaction in your database for audit trails.

Don't reuse across operations

Using the same key for different operations may return unexpected results.

​
Common errors

ScenarioResult
Same key, same parametersReturns the original response
Same key, different parametersReturns the original response (new params ignored)
Key too long (>255 chars)400 Bad Request