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

# Payin Webhooks Overview

> Payin-related webhook events overview

Payin webhooks notify your system about changes in the lifecycle of a funding operation.\
A payin represents any incoming payment into a wallet, whether it comes from bank transfers, cards, crypto networks, or internal transfers.

These events allow you to:

* Reconcile incoming funds
* Update user balances
* Trigger business logic (e.g., grant access, release goods)
* Handle failures or cancellations

***

# Payin Lifecycle

A payin moves through the following states:

```
PROCESSING → COMPLETED
            ↘ FAILED
```

## State Definitions

| State      | Description                                     | Types                                        |
| ---------- | ----------------------------------------------- | -------------------------------------------- |
| PROCESSING | Funds received but not yet settled or confirmed | cardPayin                                    |
| COMPLETED  | Funds settled and credited to the wallet        | cardPayin<sub>,</sub> bankPayin, cryptoPayin |
| FAILED     | The funding process failed                      | cardPayin<sub>,</sub> bankPayin, cryptoPayin |

***

# Available Webhook Events

Each state transition triggers a webhook event.

| Event             | Description                                            |
| ----------------- | ------------------------------------------------------ |
| payin\_processing | Notifies when a funding is pending confirmation        |
| payin\_completed  | Notifies when a funding are fully settled and credited |
| payin\_failed     | Notifies when a funding has failed                     |

***

# Payin Types

A payin can originate from different funding sources:

| Type        | Description           |
| ----------- | --------------------- |
| bankPayin   | Bank transfer funding |
| cryptoPayin | Blockchain transfer   |
| cardPayin   | Card payment          |

The `payinType` field in the webhook payload identifies the origin of the funds.

***

# Important Behavior

* `payin_completed` guarantees funds are available in the wallet.
* Only `COMPLETED` payins increase the wallet balance.
* Fees and FX conversion (if applicable) are already calculated in the payload.
* Always use `orderId` or `own_reference` for reconciliation.