Home/Withdraw

Create Withdraw Order

Last Updated: 2026-05-29

HTTP Request

POST/v1/withdraw/order

Auth: Signed API key required

Permissions: Withdrawal

Signed Location: JSON body

Content-Type: application/json

Create a fiat withdraw request and support the add/update beneficiary flow.

Headers

Parameter Name	Required	Type	Notes
X-MBX-APIKEY	true	string	Provisioned ACCESS_ID. `x-access-id` is also accepted by the backend, but `X-MBX-APIKEY` is recommended.

Request Body

Parameter Name	Required	Type	Notes
currency	true	string	DebitCurrency enum value.
amount	true	string	Decimal string. Single-currency order — no price/rate.
fee_amount	true	string	Decimal string.
payees	false	array<WithdrawOrderPayee>	Preferred multi-account input. Each row: `payee_type` (`Card`/`QrCode`/`PdfFile`), `sort_order`, and for `Card` the `bank_name`/`account_name`/`account_no` (plus `address`/`swift_code`/`mobile` where required); for `QrCode`/`PdfFile` an uploaded `file_id`. Optional `remark`.
bank_name	false	string	Legacy single-card field. Optional now — sent without `payees`, the server auto-creates one `Card` payee from `bank_name`/`account_name`/`account_no`.
account_name	false	string	Legacy single-card field. Account holder name.
account_no	false	string	Legacy single-card field. Account number or card number.
reference_id	false	string	Reference id.
remark	false	string	General remark.
file_ids	false	string	JSON array string.
account_remark	false	string	Beneficiary nickname.
bank_account_file_id	false	integer	File id of the related QR/log.
action	true	string	Beneficiary action.
timestamp	true	int64	Request timestamp in milliseconds. Microseconds are also accepted and normalized by the server.
recvWindow	false	integer	Optional receive window. Default `5000`, maximum `60000`.
signature	true	string	HMAC-SHA256 signature of the signed payload. `signature` itself is not part of the payload string being signed.

Notes

Prefer payees for the multi-account flow. Sending the legacy single-card fields without payees auto-creates one Card payee (back-compat).
If action is add-new, the endpoint may create or restore a beneficiary.
The maximum number of files is limited by MAX_DEBIT_FILE.

Request Example

curl -X POST 'https://<host>/v1/withdraw/order' \
  -H 'X-MBX-APIKEY: <ACCESS_ID>' \
  -H 'Content-Type: application/json' \
  -d '{
    "currency":"NGN",
    "amount":"1000",
    "fee_amount":"25",
    "payees":[
      {"payee_type":"Card","sort_order":0,"bank_name":"Bank A","account_name":"John Doe","account_no":"1234567890"}
    ],
    "action":"add-new",
    "timestamp":1717200000000,
    "recvWindow":5000,
    "signature":"<SIGNATURE>"
  }'

Parameter Name

Required

Type

Notes

X-MBX-APIKEY

true

string

Provisioned ACCESS_ID. x-access-id is also accepted by the backend, but X-MBX-APIKEY is recommended.

Request Body

Parameter Name	Required	Type	Notes
currency	true	string	DebitCurrency enum value.
amount	true	string	Decimal string. Single-currency order — no price/rate.
fee_amount	true	string	Decimal string.
payees	false	array<WithdrawOrderPayee>	Preferred multi-account input. Each row: `payee_type` (`Card`/`QrCode`/`PdfFile`), `sort_order`, and for `Card` the `bank_name`/`account_name`/`account_no` (plus `address`/`swift_code`/`mobile` where required); for `QrCode`/`PdfFile` an uploaded `file_id`. Optional `remark`.
bank_name	false	string	Legacy single-card field. Optional now — sent without `payees`, the server auto-creates one `Card` payee from `bank_name`/`account_name`/`account_no`.
account_name	false	string	Legacy single-card field. Account holder name.
account_no	false	string	Legacy single-card field. Account number or card number.
reference_id	false	string	Reference id.
remark	false	string	General remark.
file_ids	false	string	JSON array string.
account_remark	false	string	Beneficiary nickname.
bank_account_file_id	false	integer	File id of the related QR/log.
action	true	string	Beneficiary action.
timestamp	true	int64	Request timestamp in milliseconds. Microseconds are also accepted and normalized by the server.
recvWindow	false	integer	Optional receive window. Default `5000`, maximum `60000`.
signature	true	string	HMAC-SHA256 signature of the signed payload. `signature` itself is not part of the payload string being signed.

Request Example

curl -X POST 'https://<host>/v1/withdraw/order' \
  -H 'X-MBX-APIKEY: <ACCESS_ID>' \
  -H 'Content-Type: application/json' \
  -d '{
    "currency":"NGN",
    "amount":"1000",
    "fee_amount":"25",
    "payees":[
      {"payee_type":"Card","sort_order":0,"bank_name":"Bank A","account_name":"John Doe","account_no":"1234567890"}
    ],
    "action":"add-new",
    "timestamp":1717200000000,
    "recvWindow":5000,
    "signature":"<SIGNATURE>"
  }'