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

# Payouts Webhooks Overview

> Payout-related webhook events overview

Payout webhooks notify your system about lifecycle changes of an outgoing payment initiated from a wallet.

A payout represents any movement of funds leaving a wallet, whether sent to a bank account or a blockchain address. These events allow you to track execution status, update balances, notify users, and reconcile outgoing transactions in your accounting systems.

Only payouts with status `COMPLETED` represent successfully executed fund transfers.

***

# Payout Events

Events represent lifecycle transitions of a payout.

A payout follows this state flow:

```
PROCESSING → COMPLETED
            ↘ FAILED
```

* `PROCESSING` — The payout has been created and is being processed.
* `COMPLETED` — Funds have been successfully sent.

***

# Available events

| Event               | Description                                                                      | Types                    |
| :------------------ | :------------------------------------------------------------------------------- | ------------------------ |
| `payout_processing` | The payout has been created and is being processed by the system or payment rail | cryptoPayout, bankPayout |
| `payout_completed`  | The payout has been successfully executed and funds have been sent               | cryptoPayout, bankPayout |

***

# Payout types

A payout can be executed through different payment rails depending on configuration.

| Type           | Description                                                      |
| :------------- | :--------------------------------------------------------------- |
| `bankPayout`   | Funds are sent to a bank account (e.g. IBAN, SWIFT, local rails) |
| `cryptoPayout` | Funds are sent to a blockchain address (e.g. USDC, USDT)         |

The `payoutType` field in the webhook payload identifies which rail was used.

***

# Amount behavior (Important)

For payouts, the `amounts` object describes the full flow of funds:

| Field             | Description                                                                                                               |
| :---------------- | :------------------------------------------------------------------------------------------------------------------------ |
| `debitedAmount`   | Amount deducted from the source wallet, expressed in the wallet's currency.                                               |
| `fees`            | Execution costs charged on the payout. Includes `currency`, `total` and a `breakdown` with `systemFee` and `merchantFee`. |
| `amountAfterFees` | `debitedAmount` minus `fees.total`, in the same currency as `debitedAmount`. Present whenever fees apply.                 |
| `fx`              | Conversion details when origin and destination currencies differ. Includes `pair` and `rate`.                             |
| `creditedAmount`  | Final amount received by the beneficiary, expressed in the destination currency. Present whenever an FX leg applies.      |

Notes:

* Do not assume that `debitedAmount.currency` matches `creditedAmount.currency`. Always rely on the explicit currency fields provided in the payload.
* `fees`, `amountAfterFees`, `fx` and `creditedAmount` are only included when applicable to the payout (no fees, same-currency payouts, etc.).
* All monetary amounts are expressed in minor units (e.g. cents).