Create a disbursement
API contract v1.0.0
createDisbursement/v1/disbursementsThe Developer role can't grant disbursements:write by default. Use a key created by an Owner or Admin.
Note
The disbursement endpoints require the platform to enable disbursements for the current environment; otherwise they return 403 capability_disabled. For funds rules, payee rules and handling outcomes, see Disbursements.
Pays a third-party payee from your settleable balance in the currency, on your instruction. The merchant and environment come only from the API key, and the platform calculates the fee, so the request has no merchant ID, fee or channel field. The disbursements capability must be enabled in the current environment; merchant_disbursement_no is unique within the merchant and environment, and an idempotency key is required. At acceptance, the amount plus fee are held in a single atomic operation; if settleable isn't enough, the API returns 422 insufficient_balance and creates nothing. Checks run in this order: request format, idempotency, merchant status and capability, currency and channel, whole-unit amount and payee details, unique merchant disbursement ID, fee, limits, platform pause, risk lists, settleable balance. The first failed check returns, and any response other than 201 creates no disbursement and holds no funds. 201 and 200 only mean accepted (status=processing). Whether the money was paid shows in status or in a disbursement.* event whose signature you've verified. After a timeout or a 5xx, only retry with the original idempotency key or look the disbursement up by its merchant disbursement ID; never resend with a new ID or a new key: money that has been paid out can't be pulled back. There is no cancel endpoint.
Request headers
| Request headers | Required | Format | Description |
|---|---|---|---|
| Authorization | Yes | Bearer <API_KEY> | Server-side key, to be used only on the merchant's server. The merchant and environment are derived from the key. A missing, invalid, revoked or expired key returns 401. |
| Content-Type | Yes | application/json | The request body is UTF-8 encoded JSON. |
| Idempotency-Key | Yes | 1–255 visible ASCII characters | Idempotency key, 1–255 visible ASCII characters. The scope is merchant, environment, method and path: with the same key and matching core business parameters, the original business object is reused, and conflicting parameters return 409 idempotency_conflict. Use one key per submission, and reuse the same key when you retry after a network error; use a new key for a new submission, such as a card change. For concurrent requests with the same key, only one request gets to run, and the others wait for its transaction to commit and then return the same object (200). If the wait times out, the API returns 409 operation_in_progress (retryable=true); retry later with the original key. A request rejected with 400, 401, 403 or 422 doesn't consume the idempotency key; fix it and submit with a new key. |
Request body
JSON object CreateDisbursementRequest
| Name | Type | Required | Description |
|---|---|---|---|
merchant_disbursement_no | string | Required | Merchant disbursement ID: 1-64 letters, numbers, periods, underscores, colons or hyphens. It's unique within one merchant and environment and case-sensitive. Generate and save it before you send the request, and use it to look the disbursement up after a timeout. Constraints: Example: |
amount | integer(int64) | Required | Disbursement amount, in the smallest currency unit. For a currency whose disbursement channel takes whole units only, it must be a whole number of currency units: 30000 is fine for PKR, 30050 isn't. Constraints: Example: |
currency | string | Required | Uppercase three-letter currency code; only PKR for now. Constraints: Example: |
method | string | Required | Receiving method.
Example: |
payee | CreateDisbursementPayee | Required | Payee. The full payee account appears only in the create request; later responses, events, the merchant portal and exports return only the last 4 digits. Don't record the full account in your logs, error reports or tickets either. A disbursement can't be pulled back once paid: if the account number is wrong and the name happens to match, the money goes into that account. |
account | string | Required | Payee account. If it's invalid, the API returns 400 invalid_request (field is payee.account).
Constraints: Example: |
name | string | Required | Payee name. It must match the real name on the account: if it doesn't, the request is accepted and the disbursement fails later (payee_account_invalid). It can't contain digits that look like a card number (400 sensitive_data_rejected). Constraints: Example: |
bank_code | string | No | Payee bank code; required when method is bank, and not allowed for other receiving methods.
Example: |
customer_ip | string | No | The IPv4 or IPv6 address the payee (your user) used to submit this payout request in your system. Resolve it through a trusted proxy chain, and don't send your server's IP address. Used for risk checks; optional. Constraints: Example: |
description | string | No | Disbursement description, for your own reconciliation. It can't contain digits that look like a card number. Constraints: Example: |
metadata | object | No | Custom key-value pairs set by the merchant: up to 20 keys. A key can be up to 40 characters, and a value is a string of up to 200 characters. Don't put sensitive data such as card numbers in it. The platform checks for such data and rejects the request. Constraints: Example: |
Request example
Wallet disbursement: a PKR amount must be a multiple of 100
curl -X POST 'https://api.fluxan.co/v1/disbursements' \
-H 'Authorization: Bearer <TEST_SERVER_API_KEY>' \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: <UNIQUE_OPERATION_KEY>' \
-d '{
"merchant_disbursement_no": "DSB-DEMO-001",
"amount": 30000,
"currency": "PKR",
"method": "easypaisa",
"payee": {
"account": "03001234567",
"name": "Test Payee"
},
"customer_ip": "203.0.113.10",
"description": "Sample disbursement",
"metadata": {
"customer_ref": "CUSTOMER-DEMO-001"
}
}'Placeholders to replace
<TEST_SERVER_API_KEY>: Test-environment server API key, created on the "API Key" page of the merchant portal<UNIQUE_OPERATION_KEY>: The idempotency key you generate for this request (for example, a UUID); reuse the same key when you retry after a network error
Bank account disbursement: bank_code is required when method=bank
curl -X POST 'https://api.fluxan.co/v1/disbursements' \
-H 'Authorization: Bearer <TEST_SERVER_API_KEY>' \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: <UNIQUE_OPERATION_KEY>' \
-d '{
"merchant_disbursement_no": "DSB-DEMO-002",
"amount": 30000,
"currency": "PKR",
"method": "bank",
"payee": {
"account": "012345678901",
"name": "Test Payee",
"bank_code": "MEEZAN"
}
}'Placeholders to replace
<TEST_SERVER_API_KEY>: Test-environment server API key, created on the "API Key" page of the merchant portal<UNIQUE_OPERATION_KEY>: The idempotency key you generate for this request (for example, a UUID); reuse the same key when you retry after a network error
Note
Server API keys must only be used on your own server, so the docs site doesn't offer interactive API testing. Get a test key: API Key page in the merchant portal (opens the merchant portal in a new tab) (Test environment; Requires Owner, Admin or Developer)
Responses
An idempotent replay with the same key; returns the latest state of the original disbursement.
{
"id": "dsb_demo_001",
"version": 1,
"merchant_disbursement_no": "DSB-DEMO-001",
"environment": "test",
"amount": 30000,
"currency": "PKR",
"fee": 600,
"method": "easypaisa",
"payee": {
"account_last4": "4567",
"name": "Test Payee",
"bank_code": null,
"bank_name": null,
"utr": null
},
"customer_ip": "203.0.113.10",
"status": "processing",
"resolution_status": "known",
"failure": null,
"paid_amount": null,
"succeeded_at": null,
"failed_at": null,
"reversed_at": null,
"description": "Sample disbursement",
"metadata": {
"customer_ref": "CUSTOMER-DEMO-001"
},
"source": "api",
"batch_id": null,
"created_at": "2026-10-29T08:00:00Z",
"updated_at": "2026-10-29T08:00:00Z",
"request_id": "req_demo_103"
}Response fields
Returns an object. See the object section for field descriptions.
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | Disbursement ID (dsb_). Example: |
version | integer(int64) | Required | Object version, which increases with every effective change. Compare it when you process events, and don't order events by status name. Constraints: Example: |
merchant_disbursement_no | string | Required | Merchant disbursement ID, unique within one merchant and environment and case-sensitive. When a disbursement created in the merchant portal didn't set one, it equals the disbursement ID. Example: |
environment | string | Required | Environment: test is the test environment and live is the live environment. Test and live objects are isolated from each other.
Example: |
amount | integer(int64) | Required | Disbursement amount, in the smallest currency unit. Constraints: Example: |
currency | string | Required | Uppercase three-letter currency code. Constraints: Example: |
fee | integer(int64) | Required | Disbursement fee, in the smallest currency unit. It's calculated and held at acceptance with the rate version in effect then; later rate changes don't affect it. Constraints: Example: |
method | string | Required | Receiving method.
Example: |
payee | DisbursementPayee | Required | Payee. The full payee account appears only in the create request; responses, events, the merchant portal and exports return only the last 4 digits. |
account_last4 | string | Required | Last 4 digits of the payee account. Example: |
name | string | Required | Payee name, as sent in the request. Example: |
bank_code | DisbursementBankCodeNullable | Required | Bank code; null when the receiving method isn't bank.
|
bank_name | stringNullable | Required | Name of the payee's bank, as returned by the disbursement channel; may be null. Example: |
utr | stringNullable | Required | Reference number from the payee's wallet or bank, only after success; the payee uses it to trace the money with the wallet or bank. Kept after a reversal. Example: |
customer_ip | stringNullable | Required | The IP address the payee used to submit the payout request in your system; null for disbursements created in the merchant portal. Example: |
status | string | Required | Disbursement status. Clients must not treat an unknown status as success; treat it as not finished and query it.
Example: |
resolution_status | string | Required | Outcome confirmation.
Example: |
failure | DisbursementFailureNullable | Required | The reason when status is failed; otherwise null. |
code | string | Required | Failure reason code; see x-failure-codes.disbursement for the values. Tolerate new values, and handle any code you don't recognize as upstream_failed. Example: |
message | string | Required | Sanitized description. Example: |
paid_amount | integer(int64)Nullable | Required | Amount paid, only after success. It may be less than amount, and the difference is back in settleable; kept after a reversal. Constraints: Example: |
succeeded_at | string(date-time)Nullable | Required | The time the disbursement succeeded; kept after a reversal. Example: |
failed_at | string(date-time)Nullable | Required | The time the disbursement failed. Example: |
reversed_at | string(date-time)Nullable | Required | The time the disbursement was reversed. Example: |
description | stringNullable | Required | Disbursement description, for your own reconciliation. Constraints: Example: |
metadata | object | No | Custom key-value pairs set by the merchant: up to 20 keys. A key can be up to 40 characters, and a value is a string of up to 200 characters. Don't put sensitive data such as card numbers in it. The platform checks for such data and rejects the request. Constraints: Example: |
source | string | Required | Disbursement source.
Example: |
batch_id | stringNullable | Required | Batch ID (dsbb_), only for disbursements created by a batch in the merchant portal. Example: |
created_at | string(date-time) | Required | The time the request was accepted. Example: |
updated_at | string(date-time) | Required | The time of the latest change. Example: |
request_id | string | Required | Unique identifier of this request, used for troubleshooting and support. Example: |
Possible error codes
| HTTP | Error code | When it occurs | How to handle |
|---|---|---|---|
| 400 | invalid_request | Idempotency-Key is missing; the order ID contains invalid characters; payment_method_data and payment_method_id are submitted together; confirm=false carries card details; confirm=true has no return_url; a checkout session request sends both groups of identity parameters, or neither; a browser_info / billing_details field the provider requires is missing; the currency's provider takes whole units only (such as PKR) but amount has a fraction; a disbursement's payee details (payee.account, payee.name, payee.bank_code) or customer_ip are invalid; the cursor, time format or limit is invalid | Fix the request according to error.field and resubmit it; don't charge again automatically |
| 400 | sensitive_data_rejected | Digits that look like a card number, or similar data, appear in description or metadata; a disbursement's payee.name is checked the same way | Remove the sensitive content and resubmit; check why your system wrote card data into these fields |
| 403 | capability_disabled | Direct card isn't enabled; the payment or refund request capability has been turned off; the currency isn't enabled; the disbursements capability isn't enabled in the current environment | Use hosted checkout instead, or contact platform Operations |
| 403 | merchant_not_active | The merchant has been suspended or closed; callbacks, queries and notifications for business that was already accepted aren't affected | Contact platform Operations |
| 409 | idempotency_conflict | The key was reused but the amount, currency, order ID or similar parameters differ; for disbursements, the same key with any request field different (payee details included) | An integration defect: check how idempotency keys are generated; don't replay the original key with changed parameters; use a new key for a new operation. A disbursement conflict carries related_resource_id, pointing to the disbursement already accepted with this key: retrieve it first, and don't pay another one |
| 409 | operation_in_progress | Requests with the same key were sent concurrently | Retry later with the same key, or retrieve related_resource_id; don't switch to a new key |
| 422 | currency_not_supported | The intersection of the merchant's settings and the provider's capabilities doesn't include the currency; for disbursements: the currency isn't enabled for the merchant, has no available disbursement channel, or has no disbursement limits or disbursement rate configured | Use an enabled currency or contact platform Operations |
| 409 | disbursement_no_conflict | The same merchant disbursement ID is submitted again with a different idempotency key | Retrieve the disbursement that related_resource_id points to; this ID has already been paid or is being paid, so don't resend it under a new ID |
| 422 | fee_exceeds_amount | The amount is too small, and the fee calculated from the rate exceeds it; for disbursements, the amount isn't greater than the fee calculated from the disbursement rate | Increase the amount or contact the platform to adjust the configuration |
| 422 | amount_out_of_range | Below the minimum or above the maximum amount per payment, or over the daily cumulative limit; for disbursements, below the per-disbursement minimum, above the per-disbursement maximum, or over the daily amount or daily count; the error doesn't return the specific thresholds | Adjust the amount or contact the platform |
| 503 | temporarily_unavailable | The platform has paused new transactions on this channel, or paused disbursements; the response doesn't give the internal reason | Retry later with the original idempotency key; this request created no Payment or charge; if it keeps happening, contact platform Operations |
| 422 | risk_rejected | The request matched a basic rule such as a risk list, which disbursements are checked against too; the specific rule and threshold aren't disclosed | Don't try to work around it; contact the platform if you have questions |
| 422 | insufficient_balance | The settleable balance in the currency is less than the disbursement amount plus the disbursement fee | message and error.details (shortfall, currency) give the shortfall; this request creates no disbursement and holds no funds; once the settleable balance is enough, submit again with the same merchant disbursement ID and a new idempotency key; the platform never reduces the amount for you |
| 401 | unauthenticatedCommon | No Authorization header was sent; the key was copied incompletely; the old key expired after a rotation; the key was revoked | Check your credentials: on the API Key page in the merchant portal, verify the key's status and environment |
| 403 | forbiddenCommon | Creating a refund with a read-only key; creating or retrieving a disbursement with a key that lacks the disbursement scope; calling getEvent without the read scope for the event's business area; if the request's source IP isn't on the key's allowlist, the more specific ip_not_allowed is returned | Use a key that has the required scope; don't work around the restriction |
| 429 | rate_limitedCommon | A rate limit per merchant and per key; switching keys doesn't get around the merchant's overall limit; disbursement creation is counted separately per merchant | Wait for Retry-After seconds, then retry with the original idempotency key |
| 500 | internal_errorCommon | — | Retry with the original idempotency key, or query by merchant order ID / refund ID / merchant disbursement ID; never charge again with a new key |
| 502 / 503 | upstream_unavailableCommon | A provider or platform dependency failed, and the platform can't confirm whether this request took effect; not the same as the disbursement failure code upstream_unavailable, despite the name | Same as above |
Notes
- The platform must enable the disbursements capability for the current environment. Otherwise the API returns 403
capability_disabled. A disbursement pays a third-party payee from your settleable balance on your instruction. It isn't a payout, and it isn't a withdrawal. merchant_disbursement_nois unique within the merchant and environment. Resubmitting the same ID with a different idempotency key returns 409disbursement_no_conflict(related_resource_idis the existing disbursement ID), and no second disbursement is created.- The request has no merchant ID, fee or channel fields: the API key determines the merchant and environment, and the platform calculates the fee. PKR amounts must be multiples of 100.
- On acceptance, the amount plus fee is held. If the settleable balance falls short, the API returns 422
insufficient_balance(error.detailscarriesshortfallandcurrency) and creates nothing. Going over a limit returns 422amount_out_of_rangewithout the threshold. - 201 and 200 only mean the disbursement was accepted (
status=processing). Whether the money was paid depends onstatusor thedisbursement.*events. There's no cancel endpoint. - For the acceptance order and payee rules, see Disbursements: errors and rate limits and payee rules.
Warning
After a timeout or 5xx, only retry with the original idempotency key or query by merchant disbursement ID. Never resend with a new ID or a new key: money that has been paid out can't be pulled back.