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

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)
• 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). Review the returned details, then confirm it with POST /withdrawals/{withdrawalId}/confirm 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.