Payment returns

A returned payment is a payment that was previously marked as COMPLETED, but was later reversed by the payout partner or network. When this happens, the payment’s state changes to RETURNED.

Returned payments are distinct from failed payments:

FAILED - The payment could not complete. No funds were debited from your account.
RETURNED - The payment initially completed, and funds were debited and invoiced. Later, the payout partner returned the funds. Ripple credits your balance automatically, and adjustments are reflected in invoices and reports.

How payment returns work

Who triggers returns: Only Ripple can initiate a return in this first release. Customers and payout partners cannot trigger returns directly.
What changes:
- The payment state changes to RETURNED in the Payments API, UI, and reports.
- A new state-transition record is added (from COMPLETED to RETURNED).
- Webhook notifications are sent for the return event.
Error details (reason code, type, description, timestamp) are included in the errors[] field of the payment object.

Where returned payments are seen

Payments API:

paymentState is RETURNED.
errors[] provides the return reason. Example:

{
    "paymentId": "a9171c23-ac54-478b-92eb-5d64ac7489a2",
    "paymentState": "RETURNED",
    "errors": [
        {
        "code": "SYS_120",
        "type": "SYSTEM_ERROR",
        "title": "Bank-Initiated Return",
        "description": "The destination bank returned the funds on behalf of their customer or based on internal policy.",
        "status": 500,
        "timestamp": "2026-01-07T18:27:57.129Z"
        }
    ]
}

Payment UI: The payment detail view shows the RETURNED status and the associated error reason.
Reports: Sender and receiver reports list returned payments in the status column.
Notifications: You receive webhook notifications when a payment transitions to RETURNED, including the reason code and timestamp.

Return reasons

Return reasons are provided in the errors[] object of the payment. These use the standard Ripple error schema (code, type, title, description, timestamp). Examples include:

Examples:

Invalid Account Number (USER error)
Invalid Bank Identifier (USER error)
Compliance Reason (SYSTEM error)
Account Frozen or Blocked (SYSTEM error)

Note

The full list of possible return reasons may evolve. Always handle unknown codes gracefully.

Timing

The time it takes to confirm a return depends on the payment rail. For example, some domestic rails (such as ACH) may take multiple days to process a return.

Customer Actions