Manage repayments and refunds
Repayment reduces a client's outstanding receivables. A refund is a separate adjustment request. Treat both as financial operations that require stable identifiers, idempotency, asynchronous tracking, and reconciliation.
Trigger repayment from the linked client account
Use POST /clients/{clientId}/repayments to trigger FIFO repayment from the
client's linked account balance.
- Confirm the linked client account has a usable balance.
- Choose the client, currency, and optional payment rail.
- Send an idempotency key and persist it with the repayment intent.
- Track the affected receivables and credit accounts after acceptance.
The API does not accept an amount. It applies available linked-account funds across outstanding receivables in FIFO order. Do not assume the result maps to only one receivable unless current API state confirms that outcome.
Refund request
Use POST /clients/{clientId}/refunds with the amount, currency, and applicable
payment rail defined by the API contract.
Before submitting, establish the business reason and retain the internal record that authorizes the adjustment. After acceptance, follow related events and retrieve current resources rather than assuming the request completed synchronously.
Retry safety
For either operation:
- reuse the same idempotency key only for the same client, endpoint, and body;
- do not issue another financial instruction after a timeout until you have retried or resolved the original request; and
- retain request IDs for support and audit investigation.
Finish by reconciling activity.