Handling Pay Out Reversals

Most pay outs reach a final status (success or failed) and need no further action. In two cases, extra handling is required after submission: a disbursement that already succeeded can later be reversed, or a transaction can stay in processing for longer than expected.

What you receive for a reversal depends on which API you use and whether you have registered the reversal webhook. Find your setup below.

Handling Reversals

A reversal happens when a disbursement that was previously marked successful is later returned and reversed. Reversals are initiated from the provider or bank side and are rare in practice, well under 0.03% of transactions.

A reversal can occur up to 9 working days after the original success, though in most cases it is detected and processed on D+1. The most common causes are a wrong or invalid beneficiary account, or a compliance or fraud review.

What happens during a reversal

Regardless of your integration type:

• The disbursement status becomes failed. This is the transaction's own status, shown on the Dashboard and returned by status inquiry.
• The full reversed amount, including the disbursement fee, is credited back to your Durianpay balance.

What differs between integration types is how you are notified, covered in the options below.

1. SNAP API with the reversal webhook (recommended)

This applies only if you use the SNAP Disbursement API and have registered the reversal webhook event.

This is the only setup where a reversal is clearly distinguishable from a normal failed transfer.

Reversal webhook event

Status handling

Webhook sample

transfer.bank.reversal

{
  "originalPartnerReferenceNo": "1000-1000-1000-1180",
  "originalReferenceNo": "dis_item_Jl2HIglkQN4340",
  "latestTransactionStatus": "04",
  "transactionStatusDesc": "Refunded",
  "amount": {
    "value": "10000.00",
    "currency": "IDR"
  },
  "beneficiaryAccountNo": "3370018285",
  "beneficiaryAccountName": "John Doe",
  "beneficiaryBankCode": "014",
  "additionalInfo": {
    "failureReason": "Reversal Transaction"
  }
}

How to handle it

1. Validate the digital signature and headers using the same SNAP scheme as transfer-bank.notify. See Handling Webhooks for the verification steps.
2. Look up the original transaction using originalReferenceNo or originalPartnerReferenceNo.
3. Mark that transaction as reversed, treating it as a failed disbursement with a reversal reason, and adjust your settlement, ledger, or finance records accordingly.
4. Make the handling idempotent. The event may be retried, so guard against processing the same reversal twice.
5. Return an HTTP 200 OK response so Durianpay does not retry the delivery.

Registering the reversal webhook

Register the event the same way as any other Pay Out webhook: go to Settings > Webhooks > Create New, select the reversal event, and set your callback URL. See Handling Webhooks for the full setup walkthrough.

2. SNAP API without the reversal webhook

This applies if you use the SNAP Disbursement API but have not registered the reversal webhook event.

Your integration continues to work with no change. Reversals are still delivered, but through the existing transfer-bank.notify flow:

What to watch out for

• A transaction you previously recorded as successful may later arrive as failed. Your handler must be able to move a transaction from a success state to a failed state, not only from pending to failed.
• Reconciling a reversal against your ledger may require manual confirmation, since no reversal reason is provided.
• Check the Dashboard, or contact support with the disbursement ID (dis_item_xx), if you need to confirm whether a specific failed transaction was a reversal.

Recommended next step

Register the transfer.bank.reversal webhook so reversals arrive as a distinct event carrying 04 / Refunded and a reversal reason. This removes the ambiguity and the manual follow-up. See SNAP API with the reversal webhook.

3. Legacy (non-SNAP) Disbursement API

This applies if you use the Legacy Disbursement API (disbursement.completed and disbursement.validation.completed) rather than the SNAP API.

The dedicated reversal webhook is a SNAP-only feature, so there is no distinct reversal event on the Legacy Disbursement API.

You are still notified. When a reversal occurs, Durianpay re-sends the webhook for that transaction with the item status changed from done to failed. The full amount, including the fee, is credited back to your Durianpay balance.

How to handle it

1. Look up the transaction by disbursement item ID (dis_item_xx).
2. If your records show that item was previously done, treat the change to failed as a reversal.
3. Mark the transaction as failed and adjust your settlement, ledger, or finance records. The amount has been credited back to your balance.
4. Make the handling idempotent, so a repeated webhook does not adjust your ledger twice.
5. Return an HTTP 200 OK response so Durianpay does not retry the delivery.

What to watch out for

• Your system must accept a done item later becoming failed. This is the most common integration gap. If your handler ignores webhooks for transactions already recorded as successful, or treats done as final and never re-reads it, you will miss reversals entirely and your balance will drift from your ledger.
• Do not treat a successful disbursement as final for reconciliation purposes until 9 working days have passed.
• To confirm whether a specific failed transaction was a reversal, check the Dashboard or contact support with the disbursement ID.