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

# Unmatched Bank Payins Webhooks Overview

> Unmatched bank payin-related webhook events overview

Unmatched bank payin webhooks notify your system about incoming bank transfers that reached one of your pooled receiving accounts but could not be automatically attributed to any payin order — and about how they are eventually resolved.

These events allow you to:

* Detect held funds that require manual attention as soon as they arrive
* Drive your own back-office flow for assigning or rejecting the payin
* Link the resolution to the resulting payin order when funds are credited
* Keep your reconciliation records in sync with the final outcome

***

# Unmatched Bank Payin Lifecycle

An unmatched bank payin follows this state flow:

```
PENDING → ASSIGNED
        ↘ REJECTED
```

### State Definitions

| State    | Description                                                                                                   |
| :------- | :------------------------------------------------------------------------------------------------------------ |
| PENDING  | The transfer was detected as unmatched and awaits resolution. Funds are held and not credited to any account. |
| ASSIGNED | The payin was attributed to one of your accounts and replayed as a regular bank payin order.                  |
| REJECTED | The payin was rejected and is marked to be returned to origin.                                                |

***

# Available Events

| Event                           | Description                                                                              |
| :------------------------------ | :--------------------------------------------------------------------------------------- |
| `unmatched_bank_payin_detected` | An incoming transfer could not be attributed automatically (state → PENDING)             |
| `unmatched_bank_payin_assigned` | The payin was attributed to an account and settled as a regular payin (state → ASSIGNED) |
| `unmatched_bank_payin_rejected` | The payin was rejected and marked to be returned to origin (state → REJECTED)            |

***

# Unmatched Reasons

The `data.reason` field explains why the automatic matching failed:

| Reason               | Description                                                                   |
| :------------------- | :---------------------------------------------------------------------------- |
| `NO_REFERENCE`       | The transfer arrived without any payment reference (concept)                  |
| `NO_VALID_CODE`      | The reference was present but does not correspond to any valid payment code   |
| `AMBIGUOUS_CONCEPT`  | The reference matches more than one candidate and cannot be attributed safely |
| `NO_MATCHING_METHOD` | No active payin method was found for the transfer's rail and currency         |

***

# Payload Fields

All three events share the same `data` structure:

* `id` — Numeric identifier of the unmatched bank payin. Use it with the [unmatched bank payin endpoints](/custom-api-reference/unmatched-bank-payins/overview).
* `state` — Current state: `PENDING`, `ASSIGNED` or `REJECTED`
* `reason` — Why the transfer could not be matched (see table above)
* `amount` / `currency` — Transferred amount in **minor units**, and its currency
* `concept`, `senderName`, `senderAccount`, `rail` — Details of the incoming transfer, when available
* `accountId` — Account the payin was attributed to. **Only on `unmatched_bank_payin_assigned`.**
* `orderId` — The regular payin order created by the resolution. **Only on `unmatched_bank_payin_assigned`.**
* `rejectReason` — Free-text reason provided at rejection. **Only on `unmatched_bank_payin_rejected`.**
* `resolvedAt` — ISO 8601 timestamp of the resolution. Present on `assigned` and `rejected` events.

<Note>
  When a payin is assigned, the funds are credited through the standard payin flow — you also receive the regular [payin events](/webhooks-events/payin/overview) for the resulting order. Use `orderId` to correlate both.
</Note>