Idempotency

In MBanq's API ecosystem, idempotency ensures that a request accidentally sent more than once is executed only once. You attach an idempotency key — a unique value you generate — to a request, and Mbanq Cloud rejects any later request that carries the same key within the key's lifetime.

Why is Idempotency Important?

Consider a FinTech sending a request to initiate an ACH payment. Because of network issues or latency, the response is delayed or lost, and the FinTech can't tell whether the payment was created. Resending without an idempotency key risks a double payment. Resending with the same key guarantees the payment is not created twice.

Which Requests Support the Idempotency Key

Send the key in the x-idempotency-key header. It is honoured on:

The key is only checked on authenticated requests.

How Idempotency Works

1. When a request with an x-idempotency-key arrives, Mbanq Cloud checks the key before it starts processing the request.
2. If the key has not been used in the last 60 minutes, the request is processed normally and the key is recorded.
3. If the key has already been used, the request is rejected and not processed:

HTTP/1.1 403 Forbidden

This request already processed before.

Concurrent duplicates

Because the key is checked before processing starts, a duplicate that arrives while the first request is still running is rejected immediately with the same 403. The second request is never processed.

Key Scope and Lifetime

• Scope: a key is tied to your tenant, your user, and the key value. Another user in the same tenant, or a user in another tenant, can use the same key value without conflict.
• Not tied to endpoint or body: reusing a key on a different endpoint, or with a different request body, within its lifetime is rejected as a duplicate. Use a new key for every distinct operation.
• Lifetime: a key lasts 60 minutes from the first request. After that it is treated as fresh and can be used again.
• Failed requests still use up the key: if the first request fails, the key remains used for the full 60 minutes. To retry an operation that failed, send it with a new key.

Example

Creating a transfer with an idempotency key:

POST /v1/transfers?command=create HTTP/1.1
Host: api.cloud.mbanq.com
Content-Type: application/json
x-idempotency-key: 3f9c2a7e-8b41-4d6a-9e0f-5c1b7d2e4a90

{
  "type": "CREDIT",
  "paymentType": "INTERNAL",
  "amount": "122",
  "debtor": {
    "identifier": "id:5",
    "accountType": "SAVINGS"
  },
  "creditor": {
    "identifier": "id:3",
    "name": "Rakesh Ranjan Behera",
    "accountType": "SAVINGS"
  },
  "reference": [
    "internal tran"
  ]
}

On success, the response includes the resource ID of the new transfer:

{
  "clientId": 2,
  "savingsId": 5,
  "resourceId": 17,
  "resourceIdentifier": "1677572588398mP"
}

Sending the same request again with the same key within 60 minutes returns 403 "This request already processed before." and no second transfer is created.

For GraphQL, send the same header with the mutation request:

POST /graphql HTTP/1.1
Host: api.cloud.mbanq.com
Content-Type: application/json
x-idempotency-key: 7d1e4b2c-0a93-4f58-b6c1-2e8f9a3d5b47

{ "query": "mutation { createPayment(...) { ... } }" }

Best Practices

• Generate a new random key (we recommend a UUID v4) for every distinct operation. Because a key applies across all endpoints for your user, never reuse a key for a different operation.
• If a request times out or you lose the connection, retry with the same key. A 403 duplicate response means the original request was received; check the resource to see its outcome.
• If a request returned an error and you want to try again, use a new key.