Schedule & Limits
Before submitting a settlement, check the active schedule to understand allowed days, cutoff times, and amount limits.GET /api/v3/integrator/settlements/schedule
See Settlement Schedule.| Field | Type | Description |
|---|---|---|
enabled | boolean | Whether settlements are currently open for requests |
allowedDays | number[] | Days of the week accepted (0 = Sunday … 6 = Saturday) |
cutoffEnabled | boolean | Whether a daily cutoff time is enforced |
cutoffTime | string | Cutoff in HH:MM format — requests after this are queued to the next allowed day |
timezone | string | IANA timezone for cutoff evaluation (e.g. "Africa/Nairobi") |
minAmount | number | Minimum settlement amount in USD |
maxAmount | number | Maximum settlement amount in USD |
Fee Preview
Preview the fee before submitting.GET /api/v3/integrator/settlements/fee-preview
See Settlement Fee Preview. Query parameters:amount (required), walletId (required).
| Field | Type | Description |
|---|---|---|
amount | number | The queried amount in local currency |
fee | number | Fee amount in local currency |
feePercentage | number | Fee as a percentage of amount |
netAmount | number | Amount received after fee (amount - fee) |
currency | string | Local currency code |
usdRate | number | Exchange rate used to convert to USD |
usdAmount | number | amount in USD |
usdNetAmount | number | netAmount in USD |
Single Settlement Requests
POST /api/v3/integrator/settlements
See Request Settlement.| Field | Type | Required | Description |
|---|---|---|---|
walletId | string | Yes | Fiat wallet to settle from |
amount | number | Yes | Amount in the wallet’s local currency |
balanceSource | string | Yes | PAYOUT or DEPOSIT |
beneficiaryDetails | object | Conditional | Inline beneficiary — required if savedBeneficiaryId is omitted |
savedBeneficiaryId | string | Conditional | Saved beneficiary ID — required if beneficiaryDetails is omitted |
integratorNote | string | No | Internal memo |
callbackUrl | string | No | URL to receive webhook on status change |
GET /api/v3/integrator/settlements
See List Settlements. Query:limit, offset, status, from, to.
GET /api/v3/integrator/settlements/:id
See Get Settlement.DELETE /api/v3/integrator/settlements/:id
See Cancel Settlement. OnlyPENDING settlements can be cancelled.
Batch Settlements
Group multiple wallet settlements into one operation under a single admin approval.POST /api/v3/integrator/settlements/batch
See Create Batch Settlement.| Field | Type | Required | Description |
|---|---|---|---|
requests | object[] | Yes | Array of settlement sub-requests. Each accepts walletId, amount, balanceSource, and optionally beneficiaryDetails or savedBeneficiaryId |
batchReference | string | No | Your own idempotency reference for the batch |
integratorNote | string | No | Internal memo for the batch |
GET /api/v3/integrator/settlements/batch
See List Settlement Batches.GET /api/v3/integrator/settlements/batch/:batchId
See Get Settlement Batch.DELETE /api/v3/integrator/settlements/batch/:batchId
See Cancel Settlement Batch. Cancels all children still inPENDING.
Merge Into Batch
Convert two or more existing settlements into a batch after the fact.POST /api/v3/integrator/settlements/merge
See Merge Settlements into Batch.| Field | Type | Required | Description |
|---|---|---|---|
settlementIds | string[] | Yes | IDs to merge. Minimum 2. All must be PENDING or UNDER_REVIEW and not already in a batch |
integratorNote | string | No | Internal memo for the resulting batch |
Notification Preferences
PATCH /api/v3/integrator/settlements/notification-preferences
See Update Notification Preferences.| Field | Type | Description |
|---|---|---|
settlementNotificationEmail | string | Email address for settlement notifications |
settlementNotificationsEnabled | boolean | Toggle email notifications |
settlementSlackWebhookUrl | string | Slack incoming webhook URL |
settlementSlackEnabled | boolean | Toggle Slack notifications |
Saved Beneficiaries
Store destination account details once and reuse withsavedBeneficiaryId.
GET /api/v3/integrator/settlement-config/beneficiaries
See List Beneficiaries.POST /api/v3/integrator/settlement-config/beneficiaries
See Create Beneficiary.PATCH /api/v3/integrator/settlement-config/beneficiaries/:id
See Update Beneficiary.DELETE /api/v3/integrator/settlement-config/beneficiaries/:id
See Delete Beneficiary.Related
Settlement Flow
Lifecycle states, batch flow, webhooks, and schedule rules
Balances & Settlement
How deposit and payout balances work
Webhook Notifications
How to verify and handle signed webhook events
Transaction Statuses
All status codes used across the API