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
Thereason 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. |
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 for it. The
unmatched_bank_payin_assigned webhook carries the resulting orderId.Available endpoints
- List unmatched bank payins: returns your unmatched bank payins with filtering, search and sort.
- Get unmatched bank payin: retrieves one unmatched bank payin by ID.
- Assign unmatched bank payin: attributes the payin to one of your accounts.
- Reject unmatched bank payin: rejects the payin so it can be returned to origin.
How to resolve them
Get notified
Subscribe to the
unmatched_bank_payin_detected webhook event to know when a transfer could not be attributed automatically.Review the payin
Use List unmatched bank payins or Get unmatched bank payin to inspect the sender, amount, concept and destination bank details.
Assign it to the right account
Call Assign unmatched bank payin with the
accountId the funds belong to. The account must support payins on the transfer’s rail.Or reject it
If the transfer is not yours (or cannot be attributed), call Reject unmatched bank payin with a
reason, and the payin is marked to be returned to origin.Track the resolution
You will receive
unmatched_bank_payin_assigned (with the resulting orderId) or unmatched_bank_payin_rejected once the resolution is processed.All amounts are expressed in minor units (e.g.
150000 = 1,500.00 EUR).