Idempotency ensures that repeating a request always produces the intended outcome, no matter how many times it’s sent. This is especially important when network errors or interruptions make it unclear whether an operation has already completed. For operations where duplicates could cause unintended effects, PaySway requires an idempotency key. Including the same key in a retried request lets PaySway recognize it as a duplicate and return the existing result instead of performing the operation again. This ensures you can safely retry requests without the risk of creating duplicates or executing the same action twice.

​
Implementation

1

Generate an idempotency key

The idempotency key must be a valid UUID. Generate a unique UUID for each distinct request you intend to make.
import { v4 as uuidv4 } from 'uuid';

const idempotencyKey = uuidv4();
2

Include the header in your request

Add the Idempotency-Key header to your HTTP request with the generated UUID.
Idempotency-Key: 9678e160-38b3-4182-851e-9ca1d925f6ce
3

Handle retries

When you need to retry a previous request due to network issues or timeouts, always use the same idempotency key as the original request.
Store the idempotency key alongside your request metadata until you receive a successful response. This way, retries for the same entity state will always result in the same key.
If a retried request uses the same idempotency key but different parameters, PaySway will reject it. This prevents accidental misuse and ensures the idempotency key always refers to the same request.