Create Withdrawal Request API

This endpoint creates a withdrawal request record and returns a generated reference you can track.

Endpoint

Method: POST

URL: /disburse/v1/withdraw

Authentication And Headers

Your request must include these headers:

Header	Required	Description
`Authorization`	Yes	Bearer token used to authenticate your client. Format: `Bearer <token>`
`Content-Type`	Yes	Use `application/json`
`x-tenant-id`	Optional	Tenant ID override header. If omitted, tenant ID is read from authenticated token

If Authorization is missing or invalid, the API returns 401.

Request Body

Required fields

Field	Type	Notes	Example
`walletAccountNo`	`number`	Whole number	`200001`
`transactionCategory`	`string`	See allowed values below	`"USER_DISBURSEMENT"`
`requestMethod`	`string`	One of: `WEB`, `MOBILE`, `USSD`	`"MOBILE"`
`amount`	`number`	Send as number, not string	`50000`
`telephoneNumber`	`string`	Required when `payoutMethod = MOBILEMONEY`	`"256752002106"`
`telephoneNetwork`	`string`	Required when `payoutMethod = MOBILEMONEY`	`"AIRTEL"`
`remarks`	`string`	Short description	`"Weekly withdrawal"`

Transaction Category Values

Value	When to use
`USER_DISBURSEMENT`	Sending money to a member's account
`MERCHANT_SETTLEMENT`	Sending money to a merchant's account

Example Request Body

{
    "walletAccountNo": 200001,
    "transactionCategory": "USER_DISBURSEMENT",
    "requestMethod": "MOBILE",
    "amount": 50000,
    "telephoneNumber": "256752002106",
    "telephoneNetwork": "AIRTEL",
    "remarks": "Monday withdrawal"
}

Example cURL Request

Replace token and sample values with your real integration values:

Success Response

If the withdrawal request is created successfully, the API returns:

{
    "status": "success",
    "message": "Withdrawal request created successfully",
    "error": null,
    "data": {
        "id": "0a3e145f-f1cb-4b2a-9e3d-cbf9fe09debb",
        "referenceNo": "WDR-5DAGXJSK",
        "walletAccountNo": 200001,
        "transactionCategory": "USER_DISBURSEMENT",
        "requestMethod": "MOBILE",
        "currency": "UGX",
        "amount": "50000",
        "payoutMethod": "MOBILEMONEY",
        "telephoneNumber": "256752002106",
        "telephoneNetwork": "AIRTEL",
        "remarks": "Monday withdrawal",
        "transactionStatus": "PENDING",
        "createdAt": "2026-04-07T08:40:53.110Z"
    }
}

Important Notes

The endpoint creates a withdrawal request record; downstream payout completion is a separate process.

The API generates referenceNo for you. Do not send it in the request.

currency is stored as UGX.

Send numeric fields like walletAccountNo and amount as numbers, not quoted strings.

Create Withdrawal Request API

Endpoint#

Authentication And Headers#

Request Body#

Required fields#

Transaction Category Values#

Example Request Body#

Example cURL Request#

Success Response#

Important Notes#