Integration Guide
Idempotency & Rate Limits
Prevent duplicate transactions with idempotency keys and handle rate limiting gracefully.
Ensure reliable integration with idempotency for financial operations and graceful rate limit handling.
Idempotency
For financial operations (credit, debit, reversal), use idempotency keys to prevent duplicate processing.
How It Works
Idempotency Keys
| Key | Where | Description |
|---|---|---|
externalTransactionId | Request body | Your unique transaction reference. M2P deduplicates on this field within a configurable window |
X-Request-Id | HTTP header | Optional request-level identifier for tracing and debugging |
Always use a unique externalTransactionId for every new transaction. UUIDs are recommended. If the same ID is sent again, the original response is returned without processing a new transaction.
Rate Limits
API rate limits protect the platform and ensure fair usage across all tenants.
| Tier | Requests per Minute | Burst Capacity |
|---|---|---|
| Standard | 600 | 100 |
| Premium | 3,000 | 500 |
| Enterprise | Custom | Custom |
Handling Rate Limits
When rate-limited, you will receive an HTTP 429 Too Many Requests response.
Recommended approach: Implement exponential backoff with jitter.
Retry Decision Matrix
| HTTP Status | Action | Retry? |
|---|---|---|
| 200 | Success | No |
| 400 | Fix request — validation error | No |
| 401 | Re-authenticate, then retry | Yes (once) |
| 409 | Duplicate — already processed | No |
| 429 | Rate limited — wait and retry with backoff | Yes |
| 500 | Server error — retry with backoff | Yes (max 3) |
| 502 | Bad gateway — retry with backoff | Yes (max 3) |
| 503 | Service unavailable — retry with backoff | Yes (max 5) |
| 504 | Gateway timeout — retry with backoff | Yes (max 3) |