Guide
Payments and allocation
The four types of payment, how Fence places each on its asset, and how it works out what each paid.
A payment is money that moved, or an amount a borrower no longer owes, as you declare it. Fence places each payment on its asset and works out what it paid: its allocation.
Four types of payment
Type | What it is | Fields to know |
|---|---|---|
| Money paid out to the borrower. It opens the asset and makes its payout row. |
|
| Money the borrower paid. |
|
| Money of a collection that came back: a bounced debit, a chargeback. A payment of its own, never a negative one. |
|
| Lowers what the asset owes, with no money moving: a credit note, goods returned, a discount. |
|
Amounts are decimal text. A payment may not be dated more than a day after Fence receives it.
{"records": [
{"payment_id": "dA", "type": "disbursement", "currency": "EUR", "asset_id": "L-123",
"gross_amount": "12000.00", "paid_on": "2026-10-01"},
{"payment_id": "cA", "type": "collection", "currency": "EUR", "asset_id": "L-123",
"gross_amount": "1054.99", "paid_on": "2026-11-01", "instalment_keys": ["L-123-1"]}
]}Send them to POST …/submissions/payments. A dilution's reason is one of goods_returned, credit_note, discount, invoice_cancelled or price_correction.
Placing a payment on its asset
Fence places a payment on the asset its asset_id names, or on the asset whose expected payments carry its instalment_keys. A payment that names neither, or keys that several assets carry, is accepted but waits for its asset, until you send it again naming one. Once placed, a payment never moves to another asset.
Allocation
Fence applies payments in date order. A collection pays the expected payments its keys name, each only up to what it still owes, in your split if you sent one or else in your program's order of parts. Whatever is left is held, with one reason.
Fence never guesses. A collection that names no instalment is held (no_link) until you name its instalments, even when the asset has only one due.
A return takes money back from the rows its collection paid, and those rows owe again, as if the money never came.
Your program may set a payment tolerance per currency: a collection that leaves its instalment short by no more than that amount (bank fees, currency conversion) pays it in full.
Allocation status | Meaning |
|---|---|
| Applied in part or in full, nothing held. |
| Some applied, some held. |
| Nothing applied: all held, not allocated yet, or waiting for its asset. |
| Its returns took all of it back. |
Held reasons about the asset: nothing_owed, no_link, more_than_owed, payout_not_expected. About one of the payment's keys: instalment_not_found, wrong_kind, reference_ambiguous.
Withdraw a payment
Send a record with only its payment_id and a withdrawal_reason. A withdrawn payment then counts nowhere, and its payment_id can never be sent again.
Read them back
To read | Route |
|---|---|
An asset's payments and what each paid |
|
Which payment paid which expected payment |
|
Payments of a period, with filters |
|
Totals of a period by type and currency |
|