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

# Overview

> Understand what unmatched bank payins are, why they happen, and how to resolve them via API.

## What an unmatched bank payin is

An **unmatched bank payin** is an incoming bank transfer that reached one of your pooled receiving accounts but could not be automatically attributed to any of your payin orders — typically because the transfer reference (concept) was missing, invalid, or ambiguous. Instead of being credited, the funds are held and the payin is surfaced to you for manual resolution: you either **assign** it to the account it belongs to, or **reject** it so it can be returned to origin.

## Why a payin ends up unmatched

The `reason` field tells you 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         |

## Lifecycle and states

| State      | Description                                                                                                       |
| ---------- | ----------------------------------------------------------------------------------------------------------------- |
| `PENDING`  | Detected and awaiting resolution. Funds are held and not credited to any account.                                 |
| `ASSIGNED` | You attributed the payin to one of your accounts. The provider replays it and it settles as a regular bank payin. |
| `REJECTED` | You rejected the payin; it is marked to be returned to origin.                                                    |

<Info>
  When you assign an unmatched bank payin, the funds are credited through the standard payin flow: a regular bank payin order is created for the selected account, and you also receive the usual [payin events](/webhooks-events/payin/overview) for it. The [`unmatched_bank_payin_assigned`](/webhooks-events/unmatched-bank-payin/unmatched-bank-payin-assigned) webhook carries the resulting `orderId`.
</Info>

## Available endpoints

* [List unmatched bank payins](/api-reference/account-unmatched-bank-payins/list-the-merchants-unmatched-bank-payins): returns your unmatched bank payins with filtering, search and sort.
* [Get unmatched bank payin](/api-reference/account-unmatched-bank-payins/get-one-of-the-merchants-unmatched-bank-payins): retrieves one unmatched bank payin by ID.
* [Assign unmatched bank payin](/api-reference/account-unmatched-bank-payins/assign-one-of-the-merchants-unmatched-bank-payins-to-an-account): attributes the payin to one of your accounts.
* [Reject unmatched bank payin](/api-reference/account-unmatched-bank-payins/reject-one-of-the-merchants-unmatched-bank-payins): rejects the payin so it can be returned to origin.

## How to resolve them

<Steps>
  <Step title="Get notified">
    Subscribe to the [`unmatched_bank_payin_detected`](/webhooks-events/unmatched-bank-payin/unmatched-bank-payin-detected) webhook event to know when a transfer could not be attributed automatically.
  </Step>

  <Step title="Review the payin">
    Use [List unmatched bank payins](/api-reference/account-unmatched-bank-payins/list-the-merchants-unmatched-bank-payins) or [Get unmatched bank payin](/api-reference/account-unmatched-bank-payins/get-one-of-the-merchants-unmatched-bank-payins) to inspect the sender, amount, concept and destination bank details.
  </Step>

  <Step title="Assign it to the right account">
    Call [Assign unmatched bank payin](/api-reference/account-unmatched-bank-payins/assign-one-of-the-merchants-unmatched-bank-payins-to-an-account) with the `accountId` the funds belong to. The account must support payins on the transfer's rail.
  </Step>

  <Step title="Or reject it">
    If the transfer is not yours (or cannot be attributed), call [Reject unmatched bank payin](/api-reference/account-unmatched-bank-payins/reject-one-of-the-merchants-unmatched-bank-payins) with a `reason`, and the payin is marked to be returned to origin.
  </Step>

  <Step title="Track the resolution">
    You will receive [`unmatched_bank_payin_assigned`](/webhooks-events/unmatched-bank-payin/unmatched-bank-payin-assigned) (with the resulting `orderId`) or [`unmatched_bank_payin_rejected`](/webhooks-events/unmatched-bank-payin/unmatched-bank-payin-rejected) once the resolution is processed.
  </Step>
</Steps>

<Check>
  All amounts are expressed in **minor units** (e.g. `150000` = 1,500.00 EUR).
</Check>