# Receivables funding and repayments

Fund a client payment, follow the receivable, and repay it.

Product: PNSL API
Guides follow API reference 2.0.0 and event reference 1.0.0.
Canonical page: https://docs.axiym.io/pnsl-api/integration-guide/implementation-guides/receivables-funding-and-repayments

## 1. Receivables overview

A receivable is the repayment obligation created when Axiym funds a client
payment. Axiym creates the receivable, disburses the funds to your bank
account, and tracks the obligation until it is repaid.

* **Identifier:** every receivable has a `receivableId`.
* **Amounts:** `initialPrincipal` (funded), `currentPrincipal` (still
  outstanding), `repaymentAmount` (total due, including interest and fees).
* **Transactions:** `disbursedTransaction` (the disbursement) and
  `repaymentTransactions` (each repayment).

## 2. The funding flow

### Step 1: Request funding

When you identify a client payment to fund, send it to Axiym.

* **Endpoint:** `POST /clients/{clientId}/receivables`
* **Payload:** `amount`, `currency`, `paymentRails` (when more than one rail
  is configured), and `paymentTransaction` with your payment ID, its
  timestamp, and the payment data.
* **Header:** `Idempotency-Key` (required). Reuse it only when retrying this
  same request; if the response is lost, retry with the same key rather than
  creating a second receivable.
* **Response:** `201 Created` with the receivable in `PENDING`. Store
  `receivableId` together with your payment ID.

### Step 2: Disbursement

Axiym disburses the funds to your bank account. When the disbursement settles:

1. the receivable carries a `disbursedTransaction`;
2. its status becomes `ACTIVE`;
3. `receivable.disbursed` is sent to your webhook.

Execute the client payment in your system once the funds are on your account.

### Step 3: Lifecycle

| Status     | Meaning                                                                                | Event                                       |
| ---------- | -------------------------------------------------------------------------------------- | ------------------------------------------- |
| `PENDING`  | Funding request accepted; disbursement in progress.                                    | `receivable.created`                        |
| `ACTIVE`   | Disbursement settled; principal outstanding. Stays `ACTIVE` after a partial repayment. | `receivable.disbursed`, `receivable.repaid` |
| `PAID`     | Fully repaid.                                                                          | `receivable.settled`                        |
| `CANCELED` | The receivable did not complete.                                                       | `receivable.canceled`                       |

Events tell you that something changed; read the receivable for its current
state.

## 3. Managing repayments

Repayment is automatic whenever Axiym can match incoming funds to a client.
Manual repayment is only needed when it cannot.

### Automatic repayment

Ask payers to identify the client in the memo of every transfer to Axiym:

* **Settlement reference:** the `RF` number Axiym gives you for the client's
  settlement account, as the whole memo.
* **Client code:** the client's `code` from `GET /clients/{clientId}`, for
  example `AXI000221`, anywhere in the memo.

If the memo has neither, Axiym tries to match the sender's bank account to a
client. Matched funds are applied to the client's oldest active receivables
first. No API call is needed.

### Manual repayment

Funds that cannot be attributed to a client are credited to your settlement
account as unallocated funds. Apply them to a client yourself.

**Step A: Check your settlement balance**

* **Endpoint:** [`GET /accounts`](/account-api/api-reference/0.3.0/accounts/listAccounts)
  (Account API)
* **Response:** your accounts with their `currency`, `paymentRails` and
  `balance`. Take the account that matches the currency and the rail the funds
  arrived on. Its `balance` is the total settlement balance, which can
  also include funds transferred from client settlement accounts. Use your
  reconciliation records to identify the amount to apply to this client;
  it must not exceed the selected account's balance.

**Step B: Repay the client**

* **Endpoint:** `POST /clients/{clientId}/repayments`
* **Header:** `Idempotency-Key` (required)
* **Payload:** `amount` to apply, `currency`, and `paymentRails` of that
  account.
* **Response:** `201 Created` with `status: OK`. The amount is applied to
  the client's oldest active receivables first. Any part above the client's
  `totalRepaymentAmount` stays on the client's settlement account.

### Return excess funds

* **Funds on your settlement account:** create a withdrawal with
  [`POST /withdrawals`](/account-api/api-reference/0.3.0/withdrawals/createWithdrawal)
  (Account API). Review the returned details, then confirm it with
  [`POST /withdrawals/{withdrawalId}/confirm`](/account-api/api-reference/0.3.0/withdrawals/confirmWithdrawal)
  using a separate idempotency key. Creation returns `PENDING_CONFIRMATION`;
  execution starts only after confirmation.
* **Funds on the client's settlement account** (`balance` on its credit
  account, for example an overpayment): move them to your account with
  `POST /clients/{clientId}/transfers` (`amount`, `currency`, `paymentRails`),
  then follow the same withdrawal creation, review and confirmation flow.

A settled repayment cannot be reversed.

## 4. Monitoring

* **List receivables:** `GET /clients/{clientId}/receivables`, optionally
  filtered by `status`. Follow the pagination to the end.
* **Get a receivable:** `GET /clients/{clientId}/receivables/{receivableId}`.
  After a repayment settles, `repaymentTransactions` lists it with its
  timestamp and identifier and `currentPrincipal` shows what remains.
* **Credit account:** `GET /clients/{clientId}/credit-accounts` shows
  `availableBalance` (capacity left to fund), `principalOutstanding`,
  `totalRepaymentAmount`, and `balance` (funds received from the client and
  not yet used for repayment). A settled repayment lowers
  `principalOutstanding` and raises `availableBalance`.
* **Events:** `receivable.repaid` for each repayment, `receivable.settled`
  when the receivable is `PAID`.