Idempotency and retries

Deposit creation

merchant_id is unique within an organization.

For H2H, a repeated request returns the existing deposit with HTTP 200 only when these immutable fields match:

• numeric amount;
• requested payment method;
• normalized payer phone;
• redirect URL;
• metadata, compared with object keys canonically sorted.

The original creation returns 201. Reusing the ID with different immutable fields returns 409 merchant_id_exists.

{
  "error": {
    "code": "merchant_id_exists",
    "message": "Merchant ID already exists with different immutable deposit fields."
  }
}

If another request is actively creating the same H2H ID, OmniPay can return 409 asking you to retry shortly. Retry the exact request; do not generate a second merchant ID unless you intend to create a second payment.

Redirect checkout retains its previous uniqueness behavior and does not use the H2H immutable-field replay contract.

Verification transaction IDs

The tuple of payment method and normalized payment transaction ID is unique. Retrying the same transaction ID for the same deposit returns its existing attempt and does not consume another of the three allowed attempts.

After a network failure:

1. keep the same request JSON and payment transaction ID;
2. generate a fresh current timestamp;
3. recompute the signature;
4. retry;
5. accept either 200 or 202 and continue from the returned attempt/deposit state.

Status reads

GET requests are safe to retry. H2H status reads may also persist a clock-driven terminal transition after a deadline, so two consecutive reads can legitimately show a pending state followed by expired or failed.

Webhook consumers

Treat delivery as at least once. Persist the verified Svix message ID and apply your business transition in one transaction. A duplicate should return 2xx without repeating fulfillment.

Retry matrix