# Withdraw a seller's balance Building with an AI agent? Start at https://docs.payme.io/agents.md - Sandbox: `POST https://sandbox.payme.io/api/withdraw-balance` - Production: `POST https://live.payme.io/api/withdraw-balance` ## Credentials - Request body field `payme_client_key` (optional): Your partner key. A seller calling for itself doesn't send it. - Request body field `seller_payme_id` (required): The seller's MPL. Requests a payout of a seller's released balance in one currency to the seller's bank account. By default it withdraws the whole released balance. To withdraw a set amount, send `withdrawal_amount`. To withdraw specific transactions, send `transaction_ids`. A partner sends `payme_client_key` and the seller's `seller_payme_id`. A seller sends its own `seller_payme_id`. The seller must be on the manual withdrawal plan (`seller_withdrawal_plan` `1` on [List sellers](/payments/query-apis/post-get-sellers)), approved by PayMe (`seller_approved`), and have bank details on file. Approval needs the seller's documents: see [File types](/marketplaces-and-platforms/seller-reference/file-types). The amount must be at least the minimum: 100.00 per currency (`10000` in minor units), unless PayMe set another value for your account. PayMe records the withdrawal, sends a `withdrawal-complete` callback, and transfers the money later. If the response has no `items`, no withdrawal was created. If the call times out, check [List withdrawals](/payments/query-apis/post-get-withdrawals) before you retry. For plans, timing and reconciliation, see [Withdrawals](/marketplaces-and-platforms/fees-and-payouts/withdrawals). ### Errors Every error returns `status_code` `1` with the code in `status_error_code`. Code | Meaning ---|--- `1` | `withdrawal_currency` is missing. `2` | A previous withdrawal is stuck on a funds mismatch. Contact PayMe support. `17` | `withdrawal_currency` holds more than one currency. Send one currency per request. `42` | `withdrawal_amount` isn't an integer. `109` | The seller isn't approved yet. `165` | The seller's bank details are missing. `171` | No released balance to withdraw, or `withdrawal_amount` is above it. `252` | Unknown `withdrawal_currency`. `907` | The seller is on an automatic (daily or monthly) withdrawal plan. `908` | The seller, or a listed transaction, is paid directly by the card companies. `913` | The amount is below the minimum, or `withdrawal_amount` isn't a positive integer. `998` | HTTP 429: another withdrawal for this seller is running. Wait and retry. `507` / `523` / `525` / `526` | A listed transaction is in another currency / not released yet / already withdrawn / not found for this seller. The full list is on [Errors](/payments/getting-started/errors). ### Callback When the withdrawal is recorded, before the bank transfer, PayMe sends a `withdrawal-complete` callback (`POST`, `x-www-form-urlencoded`) to your default callback URL. See [Callbacks](/payments/getting-started/callbacks). Field | Description ---|--- `notify_type` | `withdrawal-complete` `payme_status` | `success` `status_code` | `0` `status_error_code` | `0` `seller_payme_id` | The seller's MPL, for example `MPLDEMO-MPLDEMO-MPLDEMO-1234567`. `seller_id` | Your own ID for the seller. Omitted when the seller has none. `sale_payme_code` | Always `0`. `tran_payme_code` | The withdrawal's ID: `withdrawal_id` in this response, `withdrawal_payme_code` on List withdrawals. `tran_created` | When the withdrawal was created, `yyyy-mm-dd hh:mm:ss`. `tran_type` | `40` (bank withdrawal). `tran_currency` | Currency, for example `ILS`. `tran_total` | Amount, in minor units (`10000` = 100.00). `tran_description` | A Hebrew label. Don't parse it. ## Parameters This endpoint takes no path, query or header parameters. ## Request body Content type: `application/json` | Field | Type | Required | Description | | --- | --- | --- | --- | | `payme_client_key` | string | no | Your partner key. A seller calling for itself doesn't send it. | | `seller_payme_id` | string | yes | The seller's MPL. | | `withdrawal_currency` | string | yes | Currency to withdraw, a 3-letter [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) code such as `ILS`. One currency per request. | | `withdrawal_amount` | integer | no | Withdraw this amount of the released balance instead of all of it, in minor units (`50000` = 500.00). It must be at least the minimum and no more than the released balance. Ignored when you send `transaction_ids`. | | `transaction_ids` | array | no | Withdraw only these transactions: `payme_transaction_id` values from [List transactions](/payments/query-apis/post-get-transactions), for example `TRAN1499-869602B9-7QIUNKHI-F0SL1AOV`. Each must belong to the seller, be in `withdrawal_currency`, be released and not withdrawn already. PayMe also includes the other released transactions of the same sales, such as refunds, and lists them all in the response's `transaction_ids`. | | `language` | string | no | Language of error messages: `he` (default) or `en`. | ### Request example ```json { "payme_client_key": "XXXXXXXX", "seller_payme_id": "MPLDEMO-MPLDEMO-MPLDEMO-1234567", "withdrawal_currency": "ILS", "language": "en" } ``` ## Code samples ### curl ```bash curl -X POST 'https://sandbox.payme.io/api/withdraw-balance' \ -H 'Content-Type: application/json' \ --data-raw '{ "payme_client_key": "XXXXXXXX", "seller_payme_id": "MPLDEMO-MPLDEMO-MPLDEMO-1234567", "withdrawal_currency": "ILS", "language": "en" }' ``` ### Node.js ```javascript const response = await fetch("https://sandbox.payme.io/api/withdraw-balance", { method: "POST", headers: { "Content-Type": "application/json", }, body: JSON.stringify({ "payme_client_key": "XXXXXXXX", "seller_payme_id": "MPLDEMO-MPLDEMO-MPLDEMO-1234567", "withdrawal_currency": "ILS", "language": "en" }), }); console.log(await response.text()); ``` ### Python ```python import requests response = requests.post( "https://sandbox.payme.io/api/withdraw-balance", json={ "payme_client_key": "XXXXXXXX", "seller_payme_id": "MPLDEMO-MPLDEMO-MPLDEMO-1234567", "withdrawal_currency": "ILS", "language": "en", }, ) print(response.text) ``` ### PHP ```php 'POST', CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => [ 'Content-Type: application/json', ], CURLOPT_POSTFIELDS => $body, ]); $response = curl_exec($ch); curl_close($ch); echo $response; ``` ## Responses ### 200 — OK (success) | Field | Type | Description | | --- | --- | --- | | `status_code` | integer | `0` on success. | | `session` | string | PayMe session ID. | | `page` | integer | Always `1`. | | `items_per_page` | integer | Number of withdrawals in `items`. | | `items_total` | integer | Number of withdrawals in `items`. | | `items` | array | The withdrawals created. Missing when no withdrawal was created. | | `items[].withdrawal_id` | integer | The withdrawal's ID. The same number is `withdrawal_payme_code` on List withdrawals and `tran_payme_code` in the callback. | | `items[].withdrawal_currency` | string | Withdrawal currency. | | `items[].withdrawal_total` | integer | Withdrawal amount, in minor units. | | `transaction_ids` | array | Partial withdrawals only: every transaction included, which can be more than you sent. | ```json { "status_code": 0, "session": "a1B2c3D4", "page": 1, "items_per_page": 1, "items_total": 1, "items": [ { "withdrawal_id": 10001, "withdrawal_currency": "ILS", "withdrawal_total": 600000 } ] } ``` ### 500 — Error, for example error `171`: no released balance to withdraw (error) | Field | Type | Description | | --- | --- | --- | | `status_code` | integer | `1` on failure. | | `status_error_code` | integer | PayMe error code. See [Errors](/payments/getting-started/errors). | | `status_error_details` | string | Error message, in the request's `language`. | | `status_additional_info` | string | Extra detail, such as the name of the missing or invalid field. Can be `null`. | | `session` | string | PayMe session ID. Quote it when you contact support. | ```json { "status_code": 1, "status_error_details": "No available funds for withdrawal", "status_additional_info": null, "status_error_code": 171, "session": "a1B2c3D4" } ```