Idempotent Request

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

The Idempotency-Key is mandatory for all Disbursement APIs, including Money Transfer, Special Money Transfer, Agent Money Transfer, and International Transfer. If 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, ensuring that only one disbursement is created.

To ensure that your request for disbursement is idempotent, please follow these general guidelines:

1. Use Idempotency Keys: An idempotency key is a unique identifier that you can generate for each request. Include this key in the header of your disbursement API request. If the same key is used again for an identical request, the server will recognize it and return the previous response without processing the request again. This prevents unintended double disbursements. The string length is limited to 255 characters.
2. Handle Timeouts Gracefully: In case of network timeouts or other transient errors, clients should retry the request using the same idempotency key. This way, the server will ensure that only one instance of the request is processed.
3. Avoid Side Effects on Retries: Make sure that your disbursement request does not trigger additional side effects, such as creating duplicate transactions or notifications, when retried with the same idempotency key.
4. Idempotent Operations: Ensure that your disbursement operation does not depend on the state of other requests. Each request, when processed with the same key, should result in the same outcome, regardless of how many times it's retried.

These steps will help ensure that disbursement requests remain safe, even when there are retries due to network failures or other issues. Please refer to the implementation guide below.

warning

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

Use Case Sample

Sequence Diagram

Here’s an example of proper usage of the idempotency key:

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

In summary, always retry requests with the same idempotency key if the status is not PENDING, CANCELLED, or DONE. Submitting requests with different idempotency keys will result in them being treated as separate transactions.

We strongly recommend that your request implements idempotency keys in your disbursement requests and stores these keys for future retries to ensure the 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' \