Request an early payout of eligible, not-yet-settled transactions in exchange for a fee
Instant Settlement lets you request an early payout of eligible, not-yet-settled transactions in exchange for a fee, ahead of their normal settlement window.
Feature must be enabled
Instant settlement is gated by the per-merchant instant_settlement_request feature flag, which is off by default. Only Kashier can enable it on your account — you can't toggle it yourself. Separately, each route requires an instant-settlement permission on the calling user's role — instant_settlements.all.view_instant_settlement for the reads on this page, instant_settlements.all.create_instant_settlement for the fee inquiry and for creating a request — so a valid key on a role without them is rejected even when the flag is on.
Both refusals come from the same gate and look alike: a 401 Unauthorized, not a 404. Every path on this page is live on test-api.kashier.io — if you get a 401 on a valid key, the flag or the permission is missing, not the endpoint. (A request with no Authorization header at all is answered with 403 {"message": "No auth token provided"}.)
A typical flow: list your eligible transactions, optionally get amount suggestions or a fee quote, then create a request. Once created, a request moves through a small set of statuses:
Status
Meaning
PENDING
The request has been created and is waiting to be processed.
PROCESSING
The early payout amount has been deducted from your balance.
TRANSFERRED
The payout has reached your payout method.
DECLINED
The request will not be processed. See declineReason on the request for details.
Given a target amount, returns the combination of your eligible transactions whose combined settlementAmount comes closest to that target — one combination just below it and one just above it — so you don't have to hand-pick transactions to hit a number.
Returns a fee breakdown for a set of transactions, without creating a request. Use this to show the merchant the net amount they'd receive before they commit.
Sum of the settlement amounts of the selected transactions.
totalRateFees
Percentage-based instant settlement fee.
vat
VAT on the fee.
flatFees
Flat portion of the fee, if any.
totalFees
totalRateFees + vat + flatFees.
netTransferAmount
What you'd actually receive: totalSettlementAmount - totalFees.
Caps are enforced here too
If the selection would exceed your per-request or daily cap, this call fails before you ever create a request, with a 422 carrying a dedicated code — INSTANT_SETTLEMENT_PER_REQUEST_LIMIT_EXCEEDED or INSTANT_SETTLEMENT_DAILY_LIMIT_EXCEEDED — and the relevant figures:
Cap breaches are the one exception: every other validation failure on this module is a 400, and a 409 means the request exists but is no longer PENDING.
The request's UUID. Use this or requestId to look up the request later.
data.requestId
The request's human-readable ID (e.g. ISR-1042).
data.status
See the status table at the top of this page.
data.declineReason
Set when status is DECLINED; otherwise null.
data.netTransferAmount
The amount you'll receive after fees.
data.statusHistory
A log of status changes for this request.
Only transactions that are currently eligible are accepted — if any transaction in transactionIds is no longer eligible, the request is rejected with a 400 naming the offending transaction, and no partial request is created.
The balance ledger records created for this request, once its early-payout deduction has posted. Empty ([]) while status is PENDING. See Get balance records for the general ledger this is drawn from.
data.linkedBalanceRecords[].isReflected
Whether this deduction has been fully reflected in your balance yet.
Degraded response
If the balance ledger is temporarily unavailable when you call this endpoint, the request details still return, but with linkedBalanceRecords: null and linkedBalanceRecordsUnavailable: true. Retry later to get the linked records.
Calling this with an id/requestId that doesn't belong to you returns a 404.
