Retrieve a disbursement

API contract v1.0.0

On this page

getDisbursement

GET/v1/disbursements/{disbursement_id}

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.

Retrieves a single disbursement. Don't treat processing as a failure, and don't create another one; failed and reversed are terminal states, and the amount and fee are back in settleable. After a reversal, succeeded_at, paid_amount and payee.utr are kept. A disbursement ID that doesn't belong to the current merchant and environment returns 404, without revealing whether it exists.

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.

Request example

curl

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

Placeholders to replace

<DISBURSEMENT_ID>: Replace with your actual value
<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 details.

Example

JSON

{
  "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",
  "request_id": "req_demo_104"
}

Response fields

Returns an object. See the object section for field descriptions.

Name	Type	Required	Description
`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.
`account_last4`	string	Required	Last 4 digits of the payee account. Example: `4567`
`name`	string	Required	Payee name, as sent in the request. Example: `Test Payee`
`bank_code`	DisbursementBankCodeNullable	Required	Bank code; null when the receiving method isn't bank. `HBL` `UBL` `MCB` `MCB_ARIF_HABIB` `NBP` `ALFALAH` `ALLIED` `ASKARI` `FAYSAL` `MEEZAN` `AL_HABIB` `HABIB_METRO` `BANK_ISLAMI` `DUBAI_ISLAMIC` `PUNJAB_BANK` `SINDH_BANK` `SONERI` `SUMMIT` `SILK` `SAMBA` `JS` `NIB` `APNA` `CITI` `NRSP` `CDNS` More values may be added in the future. Don't treat a status you don't recognize as success.
`bank_name`	stringNullable	Required	Name of the payee's bank, as returned by the disbursement channel; may be null. Example: `null`
`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: `null`
`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.
`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: `payee_account_invalid`
`message`	string	Required	Sanitized description. Example: `Invalid payee account or name mismatch.`
`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`
`request_id`	string	Required	Unique identifier of this request, used for troubleshooting and support. Example: `req_demo_001`

Possible error codes

HTTP	Error code	When it occurs	How to handle
404	not_found	An incorrect ID; using a test key to look up a live object; looking up a platform exception refund (not returned by the open API)	Check the ID and the environment of the key you used; the platform doesn't reveal whether another merchant's object exists
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

Only the last 4 digits of the payee account are returned (payee.account_last4). The full account never appears in any response or event.
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.
reversed means the payee's wallet or bank returned the money after success, so the payee didn't receive it. succeeded_at, paid_amount and payee.utr are kept.
Queries only read the platform's current status. A disbursement that doesn't belong to the current merchant or environment returns 404, without revealing whether it exists.
For failure.code values and what to do, see disbursement failure codes.

Was this page helpful?