# 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:

```json
{
    "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

* **No action is required to reclaim funds.** Ripple automatically re-credits your balance.
* **Review error details** to understand why the payment was returned. In many cases, you may need to update beneficiary information before retrying.
* **Use reports and notifications** to reconcile returned payments with your internal systems.