Operational lifecycle
Funding disbursements and repayments settle asynchronously. A successful funding or repayment response acknowledges acceptance; use events and resource reads to follow settlement. Transfers from a client's settlement balance to your settlement account are instant book transfers.
1. Onboard the client
POST /onboardings
submits the client with its currency, payment rail, and funding destination.
Review is asynchronous. Track the case with
GET /onboardings/{clientId} until it is APPROVED, then verify that
GET /clients/{clientId} returns an ACTIVE client.
2. Check capacity
GET /clients/{clientId}/credit-accounts
returns the client's credit accounts. Pick the active one for the payment's
currency and rail and check its availableBalance.
3. Fund the payment
POST /clients/{clientId}/receivables
with the amount, currency, rail, and the client payment's details. Axiym
creates the receivable in PENDING and starts the disbursement to your bank
account.
4. Wait for the disbursement
When the disbursement settles, the receivable becomes ACTIVE and carries a
disbursedTransaction. Follow it with the receivable.* events or
GET /clients/{clientId}/receivables/{receivableId}.
Execute the client payment in your system once the funds are on your account.
5. Repay
Funds the client sends to Axiym with its settlement reference or client code
in the memo are applied to its receivables automatically. Funds that cannot be
attributed to a client land on your settlement account; apply them with
POST /clients/{clientId}/repayments.
Return an overpayment with
POST /clients/{clientId}/transfers
and an Account API withdrawal. Rules are in
Receivable and repayments.
6. Track to completion
Each settled repayment lowers currentPrincipal and restores
availableBalance. The receivable becomes PAID when nothing is outstanding.
Use events for notification and GET reads for the current state;
de-duplicate events by their id.
Checklist
| Stage | What to verify |
|---|---|
| Onboarding | The client is ACTIVE with the expected currency, rail, and funding destination. |
| Capacity | The credit account is active and availableBalance covers the payment. |
| Funding | The receivable was accepted with the intended payment details. |
| Disbursement | The receivable is ACTIVE and has a disbursedTransaction. |
| Repayment | Repayments reduce currentPrincipal; the receivable ends PAID. |
| Reconciliation | Your payment records, the receivables, and the events agree. |
Amounts are decimal strings. Treat unknown status values as non-terminal.