Disbursement Retry & Duplicate Prevention

When initiating a disbursement, merchants must verify the final transaction status before attempting another transfer for the same payment.

This is important to prevent duplicate disbursements, where the same beneficiary may receive funds more than once due to repeated payment requests.

An initial API response, HTTP 5xx error, or timeout does not always represent the final transaction outcome. Merchants must rely on the Disbursement Callback or Status Inquiry API to confirm the transaction result.

Mandatory: If a transaction returns an HTTP 5xx error, 5XX18XX response code, or timeout, merchants must keep the transaction in a Processing state and must not initiate another disbursement until the original transaction outcome has been confirmed.

Transaction Status Handling

Handling HTTP 5xx Errors & Timeouts

An HTTP 5xx response, 5XX18XX response code, or timeout does not necessarily indicate that the disbursement has failed.

The transaction may have already been received or processed by Ayoconnect or the beneficiary bank, even if the merchant did not receive a successful API response.

To prevent duplicate disbursements, merchants must follow these steps:

1. Keep the transaction as Processing. The transaction must not be marked as Failed based solely on an HTTP error or timeout.
2. Do not initiate another disbursement for the same payment while the original transaction remains unresolved.
3. Wait for the Disbursement Callback to receive the latest transaction status.
4. If no callback is received within 30 minutes, call the Status Inquiry API, setting originalExternalId to the X-EXTERNAL-ID value of the original Disbursement request.
5. Continue monitoring the transaction if the status remains Pending or the final outcome cannot be confirmed.

Important: The 30-minute waiting period is for status verification, not permission to retry. If the transaction remains unresolved after 30 minutes, merchants must keep it in Processing and must not automatically initiate another transfer.

When Can Merchants Retry?

Merchants may initiate a new disbursement only when the previous transaction has been definitively confirmed as FAILED, or when Ayoconnect has confirmed that the original transfer was not processed and a new attempt is safe.

Before initiating another transfer, merchants must:

1. Confirm the original transaction outcome through the Disbursement Callback or Status Inquiry API.
2. Review the failure reason and resolve any issues related to beneficiary details, available balance, or transaction restrictions.
3. Perform Account Validation again before initiating the new disbursement.
4. Use a new unique X-EXTERNAL-ID for the new transfer attempt.
5. Ensure that no other transfer attempt for the same payment is still Processing or has an unresolved outcome.

Important: A new X-EXTERNAL-ID represents a new transfer attempt. Submitting another request while the original transaction is still processing may result in duplicate disbursements.

Example: Preventing Duplicate Disbursements

A merchant initiates a disbursement of IDR 1,000,000 to a beneficiary.

1. Disbursement Initiated
   The merchant submits a Disbursement API request, but receives HTTP 500.

2. Transaction Must Remain Processing
   The merchant must keep the transaction as Processing and must not retry or initiate another disbursement for the same payment.

3. Status Verification
   After 30 minutes without receiving a callback, the merchant calls the Status Inquiry API using the original transaction reference.

4. Final Status Received
   The Status Inquiry API returns latestTransactionStatus: "00" (SUCCESS), confirming that the original transfer was completed successfully.

5. Transaction Completed
   The merchant marks the transaction as successful and does not initiate another transfer.

Why is this important?

Even though the initial API request returned HTTP 500, the transfer was successfully processed.

If the merchant had immediately initiated another disbursement, the beneficiary could have received IDR 2,000,000 instead of IDR 1,000,000.

Important Notes

• Merchants MUST keep transactions in Processing when receiving HTTP 5xx, 5XX18XX, or timeout responses until the transaction outcome is confirmed.
• Never retry a disbursement based solely on an HTTP error or timeout.
• Do not retry transactions that are Pending or have an unknown outcome.
• Always use the latest confirmed latestTransactionStatus as the source of truth.
• Prevent multiple simultaneous transfer attempts for the same payment.
• A 07 - NOT FOUND response must not automatically trigger a new transfer without confirming that the original transaction was not processed.
• If the transaction outcome cannot be confirmed, contact Ayoconnect Support before initiating another transfer.

For further information, refer to the Status Inquiry API and Response Codes documentation.