Disbursements

What a disbursement is

A disbursement pays a third-party payee you choose from your settleable balance in one currency, on your instruction. It isn't the same as a payout:

Disbursements don't go through manual review: once a request passes the acceptance checks, it's submitted. A disbursement isn't a withdrawal either. The platform has no self-service withdrawal of arbitrary amounts to your own account; your own funds reach you only through settlements and payouts. For now only PKR is supported, and there are no cross-currency disbursements. The platform doesn't store payees, so every disbursement carries the full payee details. Disbursements can't be cancelled.

Setup and prerequisites

• Manage API keys: API Key page in the merchant portal (opens the merchant portal in a new tab) (Test environment; Requires Owner, Admin or Developer) (a Developer needs to have been granted the disbursement scopes).
• Subscribe to disbursement events: Webhook settings (opens the merchant portal in a new tab) (Test environment; Requires Owner, Admin or Developer).

Funds rules

• Example: your settleable balance is PKR 1,000.00 and you create a disbursement of 300.00 with a fee of 6.00. After acceptance, settleable is 694.00 and reserved for disbursements is 306.00. On success, the reserved amount drops to zero. If it fails, settleable goes back to 1,000.00.
• Money returned to the settleable balance (failure, reversal, the shortfall of a partial payment) is available right away, without another lock period.
• To check: available and disbursement_pending in GET /v1/balances. In GET /v1/balance-transactions, disbursement entries have source_type disbursement, and the posting types are disbursement_reserved (held), disbursement_succeeded (deducted on success, including any shortfall returned), reservation_released (returned on failure) and disbursement_reversed (returned on reversal). Both endpoints need finance:read.

Create a disbursement

POST/v1/disbursements requires an Idempotency-Key and the scope disbursements:write. The request has no merchant ID, fee or channel fields: the API key alone determines the merchant and environment, and the platform calculates the fee.

For every field and constraint, see API reference: Create a disbursement. Replace the <TEST_SERVER_API_KEY> placeholder with a test key that has disbursements:write. The fee in the examples is for illustration only; your pricing decides the real fee.

curl https://api.fluxan.example/v1/disbursements \
  -H "Authorization: Bearer <TEST_SERVER_API_KEY>" \
  -H "Idempotency-Key: disbursement.create:DSB-DEMO-001:1" \
  -H "Content-Type: application/json" \
  -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": "Example disbursement",
    "metadata": { "customer_ref": "CUSTOMER-DEMO-001" }
  }'

The 201 response (a replay with the same key returns 200 and the latest state of the same 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": "Example 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_101"
}

For a bank account, the request body differs like this: "method": "bank", "payee": { "account": "012345678901", "name": "Test Payee", "bank_code": "MEEZAN" }.

Disbursement object

For the type and nullability of every field, see API reference: Disbursement object.

Query disbursements

GET/v1/disbursements/{disbursement_id} retrieves one by disbursement ID, and GET/v1/disbursements lists them by filter. Both need disbursements:read.

# Query by disbursement ID (scope disbursements:read)
curl https://api.fluxan.example/v1/disbursements/dsb_demo_001 \
  -H "Authorization: Bearer <TEST_SERVER_API_KEY>"

# Query by merchant disbursement ID: after a timeout, check whether it was accepted
curl "https://api.fluxan.example/v1/disbursements?merchant_disbursement_no=DSB-DEMO-001" \
  -H "Authorization: Bearer <TEST_SERVER_API_KEY>"

# Reconciliation: disbursements from one day that are still processing
curl "https://api.fluxan.example/v1/disbursements?status=processing&currency=PKR&created_gte=2026-10-29T00:00:00Z&created_lt=2026-10-30T00:00:00Z&limit=100" \
  -H "Authorization: Bearer <TEST_SERVER_API_KEY>"

• List filters: status, currency, created_gte (inclusive), created_lt (exclusive), merchant_disbursement_no (exact match, case-sensitive) and batch_id. limit defaults to 20, up to 100. For cursor, pass the previous page's next_cursor. Results are sorted by creation time, newest first, then by id descending for the same time (same as pagination). The response has data, has_more, next_cursor and request_id.
• Only disbursements of the current merchant and environment are returned. A disbursement ID from another merchant or environment returns 404, without revealing whether it exists. Requests rejected at acceptance have no disbursement record, so you won't find them.
• Disbursements made in the merchant portal, one by one or in batches, show up too (see source): View disbursements (opens the merchant portal in a new tab) (Test environment; Requires Owner, Admin, Finance or Developer).

Payee rules

• If a rule fails, the API returns 400 invalid_request with field set to payee.account, payee.name or payee.bank_code.
• Normalize wallet numbers in your system before you submit them: remove spaces and hyphens; replace a leading +92 or 92 followed by 10 digits with 0 and those 10 digits; add a leading 0 to a 10-digit number starting with 3 (a spreadsheet dropped the leading zero). The merchant portal forms and batch files normalize automatically; the API doesn't.
• payee.name can't contain 13–19 consecutive digits (card-number-like). If the name doesn't match the real name on the account, the disbursement is accepted and then fails (payee_account_invalid). The platform doesn't run card-number (Luhn) checks on payee accounts; an account with a valid format that doesn't exist is also accepted and then fails.
• The full payee account appears only in the create request. After that, API responses, events, the merchant portal and exports show only the last 4 digits. Don't record the full account in your logs, error reports or tickets either.

Bank codes

When method=bank, set payee.bank_code to a code from this table (taken from the contract, case-sensitive):

Idempotency and retries

• Derive the idempotency key from the merchant disbursement ID: disbursement.create:<ID>:<attempt>. Increase the attempt number only when you fix and resubmit a request rejected with 4xx. If you use random UUIDs instead, write the key to your database before sending and read it back for retries; never generate a new one.
• All request fields are compared. Idempotency records are kept for 7 days; the merchant disbursement ID stays unique forever.
• For the retry wrapper, reuse postWithRetry from the reference implementation for retries.

Status and outcomes

• There's no cancel, pull-back or retry endpoint. failed and reversed are final. A disbursement becomes failed only when the disbursement channel clearly fails it, when it can't be submitted for 30 minutes in a row, or after the platform's manual review.
• A reversal can appear after success: the platform checks again on day 1 and day 3 after success, and handles reversal notices whenever they arrive.
• Query schedule: rely on webhooks first. If a disbursement is still processing 10 minutes after acceptance and you haven't received an event, query at 30 minutes, 2 hours, 6 hours and 24 hours, then once a day until it reaches a final status. Leave at least 10 seconds between two queries of the same disbursement. Queries only read the platform's current status, so querying more often won't get you a result sooner.
• View one disbursement or export them: Disbursements (opens the merchant portal in a new tab) (Requires Owner, Admin, Finance or Developer).

Failure codes

When status=failed, failure.code takes a value from this table (taken from the contract):

• Every failure has already returned the full amount and fee to the settleable balance.
• Tolerate new failure codes; handle unknown ones as upstream_failed.

Webhook events

data.object is a snapshot of the Disbursement when the event occurred (same fields as the Disbursement object). To fetch a missed disbursement event with GET/v1/events/{event_id}, you need disbursements:read. Subscribe to events in Webhook settings (opens the merchant portal in a new tab) (Requires Owner, Admin or Developer).

Example payload (a reversal event in the live environment; reversals can't be triggered in the test environment):

{
  "id": "evt_demo_203",
  "type": "disbursement.reversed",
  "api_version": "v1",
  "created_at": "2026-10-30T02:10:00Z",
  "environment": "live",
  "merchant_id": "mer_demo_001",
  "data": {
    "object": {
      "id": "dsb_demo_009",
      "version": 3,
      "merchant_disbursement_no": "DSB-DEMO-009",
      "environment": "live",
      "amount": 30000,
      "currency": "PKR",
      "fee": 600,
      "method": "easypaisa",
      "payee": {
        "account_last4": "4567",
        "name": "Test Payee",
        "bank_code": null,
        "bank_name": null,
        "utr": "UTR-DEMO-001"
      },
      "customer_ip": "203.0.113.10",
      "status": "reversed",
      "resolution_status": "known",
      "failure": null,
      "paid_amount": 30000,
      "succeeded_at": "2026-10-29T08:01:04Z",
      "failed_at": null,
      "reversed_at": "2026-10-30T02:09:58Z",
      "description": "Example disbursement",
      "metadata": { "customer_ref": "CUSTOMER-DEMO-001" },
      "source": "api",
      "batch_id": null,
      "created_at": "2026-10-29T08:00:00Z",
      "updated_at": "2026-10-30T02:09:58Z"
    }
  }
}

Handle disbursement events (first verify the signature and environment, deduplicate by event ID and return 2xx):

// Verify the signature, check the environment, deduplicate by event ID and return 2xx first (see the Webhooks
// guide), then call this function asynchronously
export async function onDisbursementEvent(event) {
  const d = event.data.object;
  const local = await findDisbursement(d.id); // Your saved snapshot; disbursements made in the portal (source portal or batch) may be missing
  if (local && local.version >= d.version) return; // Older version: discard
  await saveDisbursementSnapshot(d);
  if (d.status === 'succeeded')
    return markPaid(d.merchant_disbursement_no, d.paid_amount, d.payee.utr); // Book the amount actually paid
  if (d.status === 'failed') return markFailed(d.merchant_disbursement_no, d.failure.code); // Funds are back in the settleable balance
  if (d.status === 'reversed') return markReversed(d.merchant_disbursement_no); // Mark it unpaid and alert your ops team; don't resend automatically
  // processing or an unknown status: keep waiting, never treat it as succeeded
}

Events for the same disbursement can arrive out of order or more than once. reversed (version 3) may arrive before succeeded (version 2). If you handle events by version, the late succeeded is discarded and never turns a reversed disbursement back into paid (out-of-order events and version comparison). To pay again after a reversal, create a new disbursement with a new ID. For disbursements made in the merchant portal without an ID, merchant_disbursement_no equals the disbursement ID.

Error codes and rate limits

Creating a disbursement runs the checks below in order. When a check fails, the API returns right away without running the rest. Except for 201, nothing is created and no funds are held.

{
  "error": {
    "code": "insufficient_balance",
    "message": "The settleable balance isn't enough to cover the disbursement amount and fee. Shortfall: PKR 56.00",
    "field": null,
    "related_resource_id": null,
    "retryable": false,
    "details": { "shortfall": 5600, "currency": "PKR" }
  },
  "request_id": "req_demo_102"
}

General errors: 401 unauthenticated; 403 forbidden (the key lacks the required scope) and ip_not_allowed; 404 not_found when you query a disbursement that doesn't exist or doesn't belong to the current merchant and environment; 429 rate_limited; 500 internal_error, and 502 or 503 upstream_unavailable (outcome unknown, handle as in Idempotency and retries). For all error codes, see the error code reference.

Rate limits

Disbursement creation has its own per-merchant rate limit and doesn't use up the payment or refund allowance. A different API key doesn't get around it. Going over returns 429 and the request isn't executed; wait Retry-After seconds and retry with the original idempotency key. When you have many disbursements to make at once, limit concurrency, or use batch disbursements in the merchant portal. Query endpoints follow the API reference rate limits.

Test in the test environment

• The prerequisites are the same as in live (see Setup and prerequisites): the platform enables the disbursements capability for the test environment and sets up a PKR channel and limits, and you use a test key with the disbursement scopes. The test environment moves no real money.
• The test settleable balance also comes from PKR collections, after the test environment's lock period. To rehearse sooner, ask the platform to shorten the lock period for the test environment.
• Disbursements under PKR 500.00 (amount < 50000) succeed; PKR 500.00 and above fail. Take the failure code from failure.code; it isn't fixed to one code.
• Bank accounts that aren't 9–20 characters long are accepted and then fail right away, so a 24-character IBAN always fails in the test environment. Test bank disbursements with a 9–20 digit local account. Live has no such limit.
• Reversals and unknown outcomes (needs_query, manual_review) can't be simulated yet. To test them yourself: in a unit test, pass the example payload to your event handler and confirm it marks the disbursement unpaid again without resending; pass a processing + needs_query response to your code and confirm it isn't treated as a failure and no new disbursement is created; and use "Send test event" in Webhook settings (opens the merchant portal in a new tab) (Test environment; Requires Owner, Admin or Developer) to send a disbursement.reversed, checking only receipt and signature verification (test events don't match a real disbursement, so don't change business data based on them).

For the general test environment notes, see the testing guide.

Go-live checks

Before you go live with disbursements, confirm each item (checkmarks are saved only in this browser; you can copy the list as Markdown). For the general go-live checks, see the go-live checklist.

FAQ