List disbursements

API contract v1.0.0

On this page

listDisbursements

GET/v1/disbursements

Required scopesdisbursements:read

The Developer role can't grant disbursements:read 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.

Lists disbursements for the current merchant and environment, filtered by status, currency, merchant disbursement ID and batch. Results are ordered by creation time descending, with ties broken by id descending, so the order is stable. It uses cursor pagination; created_gte is inclusive and created_lt is exclusive. Requests rejected at acceptance have no disbursement record.

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.

Query parameters

Name	Type	Required	Description
`status`	string	No	Filter by disbursement status. `processing`: Accepted, and the amount plus fee are held; the money is being paid or the outcome isn't confirmed yet. This isn't a failure `succeeded`: The disbursement succeeded; the amount paid may be less than amount, and the difference is back in settleable `failed`: The disbursement clearly failed, and the amount and fee are back in settleable; terminal state `reversed`: Sent back by the payee's wallet or bank after it succeeded, so the payee didn't receive the money; the principal and fee are back in settleable; terminal state More values may be added in the future. Don't treat a status you don't recognize as success. Example: `processing`
`currency`	string	No	Filter by currency. Constraints: `Format ^[A-Z]{3}$` Example: `PKR`
`merchant_disbursement_no`	string	No	Exact match on the merchant disbursement ID, case-sensitive. After a timeout, use it to confirm whether the disbursement was accepted. Constraints: `Format ^[A-Za-z0-9._:-]{1,64}$` Example: `DSB-DEMO-001`
`batch_id`	string	No	Filter by batch ID. Only disbursements created by a batch in the merchant portal have a batch ID. Constraints: `Length 1–64` Example: `dsbb_demo_001`
`limit`	integer	No	Number of items per page. The default is 20 and the maximum is 100. Constraints: `1–100Default 20`
`cursor`	string	No	The next_cursor from the previous page's response. An opaque string: don't parse it or build one yourself. Send the same filters as for the first page. Constraints: `Length 1–512`
`created_gte`	string(date-time)	No	Lower bound of the creation time (inclusive), as ISO 8601 with a time zone. Example: `2026-09-23T00:00:00Z`
`created_lt`	string(date-time)	No	Upper bound of the creation time (exclusive), as ISO 8601 with a time zone. Example: `2026-09-24T00:00:00Z`

Request example

curl

curl -X GET 'https://api.fluxan.co/v1/disbursements?limit=20' \
  -H 'Authorization: Bearer <TEST_SERVER_API_KEY>'

Placeholders to replace

<TEST_SERVER_API_KEY>: Test-environment server API key, created on the "API Key" page of the merchant portal

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

The disbursement list.

Disbursement list

{
  "data": [
    {
      "id": "dsb_demo_002",
      "version": 2,
      "merchant_disbursement_no": "DSB-DEMO-002",
      "environment": "test",
      "amount": 60000,
      "currency": "PKR",
      "fee": 800,
      "method": "jazzcash",
      "payee": {
        "account_last4": "7654",
        "name": "Test Payee",
        "bank_code": null,
        "bank_name": null,
        "utr": null
      },
      "customer_ip": null,
      "status": "failed",
      "resolution_status": "known",
      "failure": {
        "code": "upstream_rejected",
        "message": "The disbursement channel rejected this disbursement."
      },
      "paid_amount": null,
      "succeeded_at": null,
      "failed_at": "2026-10-29T09:00:05Z",
      "reversed_at": null,
      "description": null,
      "metadata": {},
      "source": "portal",
      "batch_id": null,
      "created_at": "2026-10-29T09:00:00Z",
      "updated_at": "2026-10-29T09:00:05Z"
    },
    {
      "id": "dsb_demo_001",
      "version": 2,
      "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": "UTR-DEMO-001"
      },
      "customer_ip": "203.0.113.10",
      "status": "succeeded",
      "resolution_status": "known",
      "failure": null,
      "paid_amount": 30000,
      "succeeded_at": "2026-10-29T08:01:04Z",
      "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:01:04Z"
    }
  ],
  "has_more": false,
  "next_cursor": null,
  "request_id": "req_demo_105"
}

Response fields

Paginated list: data is an array of objects. When has_more is true, use next_cursor to fetch the next page. See the object section for field descriptions.

Name	Type	Required	Description
`data`	array<Disbursement>	Required
`id`	string	Required	Disbursement ID (dsb_). Example: `dsb_demo_001`
`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: `≥ 1` Example: `1`
`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: `DSB-DEMO-001`
`environment`	string	Required	Environment: test is the test environment and live is the live environment. Test and live objects are isolated from each other. `test` `live` More values may be added in the future. Don't treat a status you don't recognize as success. Example: `test`
`amount`	integer(int64)	Required	Disbursement amount, in the smallest currency unit. Constraints: `≥ 1` Example: `30000`
`currency`	string	Required	Uppercase three-letter currency code. Constraints: `Format ^[A-Z]{3}$` Example: `PKR`
`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: `≥ 0` Example: `600`
`method`	string	Required	Receiving method. easypaisa: EasyPaisa wallet jazzcash: JazzCash wallet bank: bank account `easypaisa`: EasyPaisa wallet `jazzcash`: JazzCash wallet `bank`: Bank account More values may be added in the future. Don't treat a status you don't recognize as success. Example: `easypaisa`
`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.
`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: `203.0.113.10`
`status`	string	Required	Disbursement status. Clients must not treat an unknown status as success; treat it as not finished and query it. processing: accepted, and the amount plus fee are held; the money is being paid or the outcome isn't confirmed yet. This isn't a failure succeeded: the disbursement succeeded; the amount paid may be less than amount, and the difference is back in settleable failed: the disbursement clearly failed, and the amount and fee are back in settleable; terminal state reversed: sent back by the payee's wallet or bank after it succeeded, so the payee didn't receive the money; the principal and fee are back in settleable; terminal state `processing`: Accepted, and the amount plus fee are held; the money is being paid or the outcome isn't confirmed yet. This isn't a failure `succeeded`: The disbursement succeeded; the amount paid may be less than amount, and the difference is back in settleable `failed`: The disbursement clearly failed, and the amount and fee are back in settleable; terminal state `reversed`: Sent back by the payee's wallet or bank after it succeeded, so the payee didn't receive the money; the principal and fee are back in settleable; terminal state More values may be added in the future. Don't treat a status you don't recognize as success. Example: `processing`
`resolution_status`	string	Required	Outcome confirmation. known: outcome confirmed needs_query: outcome unknown; the platform is running a status query against the provider using the original identifiers manual_review: past the automatic query window and handed over to manual follow-up; never marked as failed automatically `known`: Outcome confirmed `needs_query`: Outcome unknown; the platform is running a status query against the provider using the original identifiers `manual_review`: Past the automatic query window and handed over to manual follow-up; never marked as failed automatically More values may be added in the future. Don't treat a status you don't recognize as success. Example: `known`
`failure`	DisbursementFailureNullable	Required	The reason when status is failed; otherwise null.
`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: `≥ 0` Example: `null`
`succeeded_at`	string(date-time)Nullable	Required	The time the disbursement succeeded; kept after a reversal. Example: `null`
`failed_at`	string(date-time)Nullable	Required	The time the disbursement failed. Example: `null`
`reversed_at`	string(date-time)Nullable	Required	The time the disbursement was reversed. Example: `null`
`description`	stringNullable	Required	Disbursement description, for your own reconciliation. Constraints: `Max length 256` Example: `Sample disbursement`
`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: `Up to 20 keysMax value length 200` Example: `{"business_order_type":"one_time_purchase"}`
`source`	string	Required	Disbursement source. api: API portal: merchant portal, single batch: merchant portal, batch `api`: API `portal`: Merchant portal (single) `batch`: Merchant portal (batch) More values may be added in the future. Don't treat a status you don't recognize as success. Example: `api`
`batch_id`	stringNullable	Required	Batch ID (dsbb_), only for disbursements created by a batch in the merchant portal. Example: `null`
`created_at`	string(date-time)	Required	The time the request was accepted. Example: `2026-10-29T08:00:00Z`
`updated_at`	string(date-time)	Required	The time of the latest change. Example: `2026-10-29T08:00:00Z`
`has_more`	boolean	Required	Whether there is a next page. Example: `false`
`next_cursor`	stringNullable	Required	The cursor for the next page; null when there is no next page. Example: `null`
`request_id`	string	Required	Unique identifier of this request. Example: `req_demo_105`

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
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

Filter by merchant_disbursement_no (exact match, case-sensitive), status, currency, batch_id, and created_gte (inclusive) / created_lt (exclusive). Results are sorted by created_at, newest first, then by id descending for the same time.
Disbursements made in the merchant portal, one by one or in batches, are included (see source). Only the last 4 digits of the payee account are returned.
processing with resolution_status needs_query or manual_review means the outcome is unknown. It isn't a failure, so don't create another disbursement.
Queries only read the platform's current status, so querying more often won't get you a result sooner. For the query schedule, see Disbursements: status and outcomes.

Was this page helpful?