Idempotency Requests

An API call or operation is idempotent if it produces the same result regardless of how many times it’s executed. This ensures that repeated calls do not cause unintended side effects, protecting against accidental duplicate requests.

The Fluz API supports idempotency requests to safeguard against accidental duplication of operations. By using a client-generated, unique idempotency key, the API ensures that the same request is not processed multiple times within a 10-minute window if provided with the same idempotency key.

How It Works

When an idempotency key is provided with a request:

• The server caches the initial response body and its status code.
• If a duplicate request with the same idempotency key and response code is received, the API will return the cached result instead of re-executing the operation, especially if an error occurs within the operation. This mechanism helps prevent unintended duplicate processing by returning consistent results even in error scenarios.

Generating Unique Idempotency Keys

Clients are responsible for creating and refreshing their idempotency keys. To ensure uniqueness:

• We strongly recommend using V4 UUIDs, which can be generated with libraries such as these: https://github.com/uuidjs/uuid
• As a best practice, idempotency keys should expire after some time to avoid reuse and ensure the uniqueness of requests. Fluz expires each unique idempotency keys after 10 minutes.

Clients will need:

1. An operation to generate and store a new idempotency key
2. An operation to remove an old key according to the client’s expiration policy

Required Operations

Not all API operations require idempotency keys. Fluz requires idempotency for certain critical operations to ensure data consistency for the following operations:

• purchaseGiftCard (View here)
• depositCashBalance (View here)

For these operations, an idempotencyKey input variable is required.

Example Input

{  
  "idempotencyKey": "2c29e5ad-bb36-4b7f-b012-b7d6031566e0",  
  "offerId": "2c29e5ad-bb36-4b7f-b012-b7d6031566e0",  
  "amount": 123.45,  
  "balanceAmount": 987.65,  
  "bankAccountId": "2c29e5ad-bb36-4b7f-b012-b7d6031566e0",  
  "bankCardId": "2c29e5ad-bb36-4b7f-b012-b7d6031566e0",  
  "paypalVaultId": "2c29e5ad-bb36-4b7f-b012-b7d6031566e0",  
  "exclusiveRateId": "2c29e5ad-bb36-4b7f-b012-b7d6031566e0",  
  "merchantSlug": "xyz789"  
}

// disclaimer for purchase gift card and deposit cash balance pages

📘

Fluz requires an idempotency key for this operation

To learn more on how to use idempotency keys, please see Idempotency Requests