# Receivable and repayments

What a receivable records, its statuses, and how repayments are attributed and allocated.

Product: PNSL API
Guides follow API reference 2.0.0 and event reference 1.0.0.
Canonical page: https://docs.axiym.io/pnsl-api/concepts/repayments

A receivable is the obligation created when Axiym funds a client payment. It
records what was funded, what is still outstanding, and every disbursement
and repayment transaction.

## Receivable fields

| Field                   | Meaning                                                  |
| ----------------------- | -------------------------------------------------------- |
| `receivableId`          | Identifier to store when a funding request is accepted.  |
| `initialPrincipal`      | The amount Axiym funded.                                 |
| `currentPrincipal`      | The principal still outstanding.                         |
| `repaymentAmount`       | Everything currently due: principal, interest, and fees. |
| `issueDate`             | When the receivable was created.                         |
| `paymentTransaction`    | The client payment you asked Axiym to fund.              |
| `disbursedTransaction`  | The disbursement to your bank account, once it settled.  |
| `repaymentTransactions` | Each repayment applied to this receivable.               |

The term and due date of a receivable are part of the client arrangement and
are not returned by the API. There is no instalment schedule and no overdue
state: a receivable stays active until it is repaid or canceled.

## Statuses

| Status     | Meaning                                                                                                                                    |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `PENDING`  | The funding request was accepted; the disbursement is in progress.                                                                         |
| `ACTIVE`   | The disbursement settled and principal is outstanding. A partial repayment leaves the receivable `ACTIVE` with a lower `currentPrincipal`. |
| `PAID`     | Fully repaid.                                                                                                                              |
| `CANCELED` | The receivable did not complete.                                                                                                           |

## How incoming funds are attributed

When funds arrive at Axiym, they are matched to a client in this order. The
first match wins.

| Order | Signal                                         | Details                                                                                                                                               |
| ----- | ---------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| 1     | Settlement reference (`RF` number) in the memo | The ISO 11649 reference of the client's settlement account, for example `RF44 0004 4703 01`. It must be the whole memo; spaces are ignored.           |
| 2     | Client `code` in the memo                      | For example `AXI000221`, anywhere in the memo text.                                                                                                   |
| 3     | Sender bank account                            | Used only when the memo has neither. The sending account is compared with the accounts known for the client, including accounts you have paid out to. |

Only the RF number and the client `code` are recognized in a memo.

Funds that match a client go to that client's settlement account and are
applied to its receivables automatically. Funds that match nothing, or whose
memo cannot be resolved, go to your settlement account as unallocated. Apply
them yourself with a
[manual repayment](/pnsl-api/integration-guide/implementation-guides/receivables-funding-and-repayments#manual-repayment).

## How funds are allocated

Funds are applied to the client's oldest active receivable first, then to the
next one (FIFO). Within a receivable, the amount covers accrued interest and
principal. Manual repayment follows the same rule; it does not select a
receivable.

Principal and `availableBalance` change only once the repayment settles.

## Excess funds

A settled repayment is final. Funds that were not needed for repayment stay on
the client's settlement account: an overpayment by the client, or the part of
a manual repayment above `totalRepaymentAmount`. Unallocated funds stay on
your settlement account. Both can be returned to you; see
[Return excess funds](/pnsl-api/integration-guide/implementation-guides/receivables-funding-and-repayments#return-excess-funds).

## Example

A USD 25,000 facility, no interest or fees, one funded payment of USD 10,000.

| Step                             | `creditLimit` | `availableBalance` | `principalOutstanding` | `balance` | `currentPrincipal` |
| -------------------------------- | ------------: | -----------------: | ---------------------: | --------: | -----------------: |
| Before funding                   |        25,000 |             25,000 |                      0 |         0 |                  — |
| Payment funded                   |        25,000 |             15,000 |                 10,000 |         0 |             10,000 |
| USD 6,000 arrives for the client |        25,000 |             15,000 |                 10,000 |     6,000 |             10,000 |
| The USD 6,000 repayment settles  |        25,000 |             21,000 |                  4,000 |         0 |              4,000 |

With interest and fees, part of each repayment covers interest first. Always
read the current values from the API rather than deriving them.