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

After settlement, read the current principal and `availableBalance` from the
API. A repayment applied entirely to interest does not reduce principal.

## Excess funds

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.
The transfer operation does not return funds already applied to a receivable.

For the transfer and withdrawal steps, 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, repayments cover interest first. Always read the
current values from the API rather than deriving them.