Idempotency

Network failures, timeouts, and unexpected errors are inevitable in any integration. Idempotency ensures that retrying a request does not result in duplicate transactions.

#How It Works

Exirom handles idempotency automatically via the requestId field. When you submit a request, the system records the requestId and mid (Merchant ID) combination. If a subsequent request arrives with the same requestId + mid pair, Exirom returns the original response without re-processing the transaction.

No special headers are required. The idempotency mechanism is built into the standard request payload.

{
  "mid": "your-merchant-id",
  "requestId": "550e8400-e29b-41d4-a716-446655440000",
  ...
}

#Scope

Idempotency applies to the following operations:

• Card payments
• Card payouts
• Card refunds
• APM payments
• APM payouts

#Best Practices

Generate a UUID for each new transaction. Every distinct transaction attempt should have a unique requestId. A v4 UUID is recommended.

Retry with the same UUID on network failure. If your request times out or you receive a network error, resend the exact same request (including the same requestId). Exirom will return the original result if the first request was already processed.

Never reuse a requestId for a different transaction. Reusing a requestId with different transaction parameters will return the response from the original transaction, not process a new one.

#Example: Safe Retry Flow

1. Generate a UUID: 550e8400-e29b-41d4-a716-446655440000
2. Send payment request with this requestId.
3. Request times out — no response received.
4. Resend the identical request with the same requestId.
5. Exirom detects the duplicate and returns the original response.
6. Your system processes the response normally.

This guarantees the customer is only charged once, regardless of how many times you retry.

#Related

• Error Recovery Patterns — retry strategies and fallback handling beyond idempotency