Skip to main content

Idempotent Request

An Idempotency Key is a unique identifier included in the header of API requests. Flip for Business API uses the Idempotency-Key to safely manage retry requests, ensuring the same operation is not executed multiple times. This is particularly useful when you don't receive a response due to network issues or other unexpected errors.

When to Use Idempotency Keys​

The Idempotency-Key is mandatory for all Disbursement APIs, including:

When you initiate a disbursement and the request fails due to network issues or other factors, you can retry the request with the same idempotency key to ensure only one disbursement is created.

Implementation Guidelines​

To ensure your disbursement requests are idempotent, follow these guidelines:

  1. Generate Unique Idempotency Keys: Create a unique identifier for each new disbursement request. Include this key in the idempotency-key header. The string length is limited to 255 characters. Only alphanumeric characters and hyphens (-) are allowed.

  2. Reuse Keys for Retries: When retrying a failed request, always use the same idempotency key from the original request. The server will recognize it and return the previous response without processing the request again, preventing duplicate disbursements.

  3. Handle Timeouts Gracefully: In case of network timeouts or transient errors, retry the request using the same idempotency key. The server ensures only one instance of the request is processed.

  4. Avoid Side Effects on Retries: Ensure your disbursement request doesn't trigger additional side effects (such as duplicate transactions or notifications) when retried with the same idempotency key.

  5. Keep Operations Independent: Each disbursement operation should not depend on the state of other requests. When processed with the same key, it should produce the same outcome regardless of retry count.

Key Deletion on Cancellation

If a transaction is cancelled due to a wrong account number or other reasons, the idempotency key will be deleted. You can use the same key to retry the transaction with corrected information.

Duplicate Prevention

If two or more requests with the same beneficiary account, bank, and amount are made within a 10-minute interval without using an idempotency key, we will process the first request and temporarily hold subsequent ones to prevent duplicate transfers. Our team will notify you and seek confirmation on whether the held transaction should be processed.

Use Case Example​

Sequence Diagram
idempotent request sequence diagram

Here's an example of proper idempotency key usage:

  1. A Flip for Business merchant sends a disbursement request to Flip, including an idempotency key in the header.
  2. If Flip responds with a status that is not PENDING (e.g., 500 Internal Server Error), the merchant can retry the transaction using the same idempotency key from the initial request.
  3. Continue retrying with the same key until Flip responds with PENDING, CANCELLED, or DONE status.

Key Takeaway: Always retry requests with the same idempotency key if the status is not PENDING, CANCELLED, or DONE. Using different idempotency keys will result in separate transactions being created.

We strongly recommend implementing idempotency keys in your disbursement requests and storing these keys for future retries to ensure consistency and safety of your transactions.

Sample Request​

curl -X POST 'https://bigflip.id/big_sandbox_api/v3/disbursement' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-H 'Accept: application/json; charset=UTF-8' \
-H 'Authorization: Basic <Base64(Your-API-SecretKey + :)>' \
-H 'idempotency-key: Unique-ID-1234' \  # <-- Idempotency-Key 
-d 'account_number=5465327020' \
-d 'bank_code=bca' \
-d 'amount=10000' \
-d 'remark=test' \

Did this answer your question?