> ## Documentation Index
> Fetch the complete documentation index at: https://docs.atum.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Refunds

> How to interpret settlement statuses and recover your funds.

## Overview

Your funds sit in the [settlement vault](https://docs.atum.xyz/get-started/concepts/settlement-vault.md) on the source chain until delivery is proven. If the payment is not delivered, the refund returns them to the wallet they came from.

You never need to pay again to get your money back. While a refund is in progress, **do not start a new payment** for the same purchase.

## How a refund happens

### When a refund can start

A refund starts after the [delivery deadline](https://docs.atum.xyz/get-started/concepts/deadlines.md#delivery-deadline) passes without a delivery. Atum then waits a few more minutes, and until the destination chain has made those blocks final, so it can be sure no payout landed.

Refunds are not instant: plan for the delivery deadline, plus a few minutes, plus the destination chain's [time to finality](https://docs.atum.xyz/get-started/concepts/finality.md#time-to-finality). That is seconds on some chains and tens of minutes on Ethereum and its rollups.

A shorter delivery deadline gets your funds back sooner. See [Choosing a delivery deadline](https://docs.atum.xyz/get-started/concepts/deadlines.md#choosing-a-delivery-deadline).

### How a refund ends

A refund ends in one of two ways:

1. **The settlement operator returns your funds.** This is the usual case. The status goes from `refunding` to `refunded`, and you do nothing.
2. **You submit the refund yourself.** If the settlement operator does not return your funds, Atum signs the refund for you and the status becomes `refund_available`. Submit it as shown in [Getting your funds back yourself](#getting-your-funds-back-yourself). The status becomes `refunded` once it lands.

What each status means, and what it can turn into, is on [Payment status](https://docs.atum.xyz/get-started/after-submission.md#payment-status). In short:

* **`refunding`:** keep polling `/status`. Do not pay again.
* **`refund_available`:** submit the refund yourself. Do not pay again.
* **`refunded`:** final. To try the purchase again, use a **new** `request_id`.

### A failed payment with a deposit

`failed` is not a refund status. A payment can fail before or after your funds reach the settlement vault. If a `failed` payment has `transactions.deposit` set, your funds went into the vault before it failed.

* The vault can only return them to you, or pay the settlement operator after a verified delivery.
* The settlement operator normally refunds them after the delivery deadline. The status stays `failed` and shows no refund fields, so look for the refund on the source chain.
* Reconcile by `payment_id` before you pay again. If your funds have not come back, contact Atum support with the `payment_id`.

## Why it was refunded

A payment that is `refunding`, `refund_available` or `refunded` can carry `refund_reason`. It says why the settlement operator gave up, using the same shape as `error` (`code`, `message`).

It describes the settlement operator's problem, not your payment. Ignore its `retry_classification` and `request_id_reusable`, and act on `status`.

## Getting your funds back yourself

When the status is `refund_available`, `GET /v1/payments/{paymentId}/status` returns `refund_signature`:

```json theme={"theme":"github-dark"}
{
  "status": "refund_available",
  "refund_signature": {
    "signature": "0x…",
    "message_hash": "…",
    "message_prehash": "{…}"
  }
}
```

| Field | What it is |
| - | - |
| `signature` | The verifier's signature. Starts with `0x` on EVM and Tron. No `0x` on Solana. |
| `message_hash` | The signed digest, without `0x`. |
| `message_prehash` | The signed message as JSON. |

Send the refund to the same settlement vault your payment was deposited into. That is the `escrow_contract_address` in your payment request, which you took from [`GET /v1/defaults`](https://docs.atum.xyz/api-reference/payment-gateway/chain-defaults) (`escrow_contract`).

> [tab] EVM and Tron
>
> `message_prehash` is EIP-712 typed data. Its `message` is the refund details, and its `domain.verifyingContract` is the settlement vault.
>
> Call the vault's `refund` function with `message` as the refund details and `signature` as the refund signature.

> [tab] Solana
>
> `message_prehash` holds the `deposit_hash`, which identifies your deposit account.
>
> Send one transaction with an Ed25519 signature check of `signature` over `message_hash` placed directly before the vault program's `refund` instruction.

Good to know:

* Anyone can submit it, but the vault only ever pays the original payer.
* On Solana, whoever submits it gets back the rent of the accounts the refund closes. If your token account no longer exists, the submitter pays to open it.
* If the settlement operator delivers late and is paid first, the refund no longer goes through. The payment then ends as `completed`.

Until someone submits the refund, your funds stay in the settlement vault. Submitting it yourself is the surest way to get them back.

## Paying with x402 or MPP

x402 and MPP report the refund statuses through their own responses:

| Status | x402 | MPP |
| - | - | - |
| `refunding` or `refund_available` | `errorReason` is `settlement_pending` | A settlement pending error |
| `refunded` | `errorReason` is `settlement_failed` | A settlement failed error |

In both, the payment ID and its current status come with the response (`extensions.atum.state` on x402, `state` on MPP).

If the state is `refund_available`, read `refund_signature` from `GET /v1/payments/{paymentId}/status` and submit it as shown above. Do not pay again with a new purchase identifier. For `refunding` and `refunded`, the usual retry rules apply: [When a payment is still settling](https://docs.atum.xyz/payment-protocols/idempotency.md#still-settling).

## Finding the refund on chain

When the refund lands, `/status` shows it in `transactions.refund`. Use that hash on the source chain explorer and in your [reconciliation](https://docs.atum.xyz/get-started/support/reconciliation.md) records. It can be missing when the refund transaction is not known.

## Next steps

| Topic | Link |
| - | - |
| How retries work | [Idempotency](https://docs.atum.xyz/payment-protocols/idempotency.md) |
| Records to keep for every payment | [Reconciliation](https://docs.atum.xyz/get-started/support/reconciliation.md) |
| Something failing? | [Troubleshooting](https://docs.atum.xyz/get-started/support/troubleshooting.md) |


## Related topics

- [Glossary](https://docs.atum.xyz/get-started/reference/glossary.md)
- [Changelog](https://docs.atum.xyz/changelog.md)
- [Veri-Fill API](https://docs.atum.xyz/api-reference/veri-fill/introduction.md)
- [The settlement lifecycle](https://docs.atum.xyz/settle-payments/settlement-lifecycle.md)
- [After submission](https://docs.atum.xyz/get-started/after-submission.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.