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

# FX Swaps Webhooks Overview

> FX swap-related webhook events overview

FX swap webhooks notify your system about lifecycle changes of currency conversions between two wallets of the same user inside the RALIO ecosystem.

An FX swap debits an origin wallet in one currency and credits a destination wallet in another, at an exchange rate set by the external liquidity provider.

These events allow you to:

* Track the progress of a conversion in real time
* Update wallet balances when the swap settles
* Detect and react to provider rejections
* Reconcile fees and applied rates

Only swaps with status `COMPLETED` represent finalized balance movements.

***

# FX Swap Events

Events represent lifecycle transitions of an FX swap.

An FX swap follows this state flow:

```
PROCESSING → COMPLETED
            ↘ FAILED
```

### State Definitions

| State      | Description                                                               |
| :--------- | :------------------------------------------------------------------------ |
| PROCESSING | The swap has been delegated to the external provider for execution        |
| COMPLETED  | The conversion settled and the destination wallet has been credited       |
| FAILED     | The provider rejected the swap; the hold on the origin funds was released |

***

# Available Events

| Event             | Description                                                       |
| :---------------- | :---------------------------------------------------------------- |
| `swap_processing` | The swap was accepted and delegated to the external provider      |
| `swap_completed`  | The conversion settled in the user's wallets and balances updated |
| `swap_failed`     | The provider rejected the swap and the origin hold was reverted   |

<Note>
  The webhook `data.status` values (`PROCESSING` / `COMPLETED` / `FAILED`) differ from the REST order `state` (`PENDING` / `SETTLED` / `FAILED`) returned by the [FX swap endpoints](/custom-api-reference/fx/overview#lifecycle). They describe the same lifecycle.
</Note>

***

# FX Swap Behavior

FX swaps are internal conversions between two wallets of the same user:

* `data.swapType` is always `fxSwap`
* `source.type` and `destination.type` are always `account`
* The `source` wallet is debited in the origin currency; the `destination` wallet is credited in the destination currency
* Fees are charged in the origin currency
* The applied provider rate and pair are reported in `amounts.fx`

***

# Amount Flow (Important)

The `amounts` object represents how funds move through the conversion:

* `debitedAmount` — Gross amount deducted from the origin wallet
* `fees` — Total fees in the origin currency, with a `breakdown` of `systemFee` and `merchantFee`. Omitted when no fees apply.
* `amountAfterFees` — Net origin amount actually converted (`debitedAmount - fees.total`)
* `fx` — The applied `pair` (e.g. `EUR/USD`) and provider `rate`
* `creditedAmount` — Final amount received by the destination wallet, in the destination currency. **Omitted on `swap_failed`.**

On `swap_failed`, the payload additionally carries a `failure` object with `code` and `reason` describing the provider rejection.

All amounts are expressed in **minor units**.