The PayMongo API supports idempotency, which lets you safely retry requests without accidentally performing the same operation twice.

When creating or updating an object, include Idempotency-Key in your request headers. If a network error or timeout occurs, you can repeat the request with the same key and get back the original result instead of creating duplicates or applying the update again.

How it works

A client generates a unique idempotency key (we recommend UUID v4 or any random string with high entropy, up to 255 characters).
The API stores the result of the first request associated with that key—whether successful or failed.
Subsequent retries with the same key return the saved response, ensuring consistency.
If parameters differ between retries, the API will reject the request to prevent unintended behavior.
Idempotency keys automatically expire after 24 hours. If you reuse a key after expiry, a new request will be processed.

Notes

Idempotency applies to resource creation requests only.
Do not send idempotency keys with retrive, list or delete requests, as these are already idempotent by definition.
Results are saved only after the API starts executing an operation. If a request fails validation or conflicts with another concurrent request, no result is stored and you can safely retry.