# Withdrawals

Building with an AI agent? Start at https://docs.payme.io/agents.md

## Related

- [Reconcile sales and withdrawals](/accepting-payments/reporting/reconcile-sales-and-withdrawals)
- [Platform fees](/marketplaces-and-platforms/fees-and-payouts/platform-fees)

## How sellers get paid

A withdrawal moves a seller's released balance to its bank account. How it starts depends on `seller_withdrawal_plan` on [get-sellers](/payments/query-apis/post-get-sellers), and on whether the card companies pay the seller directly:

| Seller | How money arrives | Can request a withdrawal |
| --- | --- | --- |
| `seller_withdrawal_plan` `1` | Manual: you request each withdrawal | Yes |
| `seller_withdrawal_plan` `2` | Automatic, daily | No, error `907` |
| `seller_withdrawal_plan` `3` | Automatic, monthly on `seller_withdrawal_date` | No, error `907` |
| Paid directly by the card companies (`withdrawable` is `0` on get-future-withdrawals) | The card companies pay the seller directly | No, error `908` |

A new seller takes the partner's default plan, and no API field changes it. Every seller created on the sandbox test account came back on plan `2`, so PayMe has to set up a test seller before a withdrawal can succeed there.

## Before the first withdrawal

Funds can't be withdrawn until PayMe approves the seller. Until then, withdraw-balance returns error `109`. `seller_approved` on get-sellers shows the approval, and a partner receives the `seller-approve` [callback](/payments/getting-started/callbacks).

Approval needs the seller's documents. Upload them with [Upload seller files](/payments/merchants-management/post-upload-seller-files), using the codes on [File types](/marketplaces-and-platforms/seller-reference/file-types):

| Document | Code | Needed by |
| --- | --- | --- |
| Social ID | `1` | Every seller |
| Bank account ownership | `2` | Every seller |
| Corporate certificate | `3` | Every seller except a private individual, a house committee or a municipality |

Some business types need more documents. File types lists them. The seller must also be active and have bank details on file.

Approval holds back payouts, not payments: a new seller can start taking payments while it waits. Show sellers their approval state early, and send them the `seller_dashboard_signup_link` that [Create a seller](/payments/merchants-management/post-create-seller) returns so they can finish onboarding.

## Check the balance

There is no separate balance call. `seller_wallets` on get-sellers holds each currency's balance, in minor units. It isn't returned when you send `api_mode` `slim`.

| Field | Meaning |
| --- | --- |
| `wallet_total` | Everything PayMe holds for the seller |
| `wallet_releasable` | The part past its release date |
| The difference | Funds not released yet. `sale_release_date` on [get-sales](/payments/query-apis/post-get-sales) gives each sale's date |

Check `seller_approved` as well: a positive `wallet_releasable` doesn't mean the seller can withdraw.

## Request a withdrawal

Call [withdraw-balance](/payments/merchants-management/post-withdraw-balance) with one currency. A partner sends `payme_client_key` and `seller_payme_id`.

```json
{
  "payme_client_key": "XXXXXXXX",
  "seller_payme_id": "MPLDEMO-MPLDEMO-MPLDEMO-1234567",
  "withdrawal_currency": "ILS"
}
```

This withdraws the whole released balance in that currency. To withdraw a set amount instead, add `withdrawal_amount` in minor units. It must be at least the minimum and no more than the released balance.

The response identifies the withdrawal:

```json
{
  "status_code": 0,
  "page": 1,
  "items_per_page": 1,
  "items_total": 1,
  "items": [
    {
      "withdrawal_id": 10001,
      "withdrawal_currency": "ILS",
      "withdrawal_total": 600000
    }
  ]
}
```

If `items` is empty, no withdrawal was created. PayMe finishes a whole-balance withdrawal in the background, so the amount can change and a failed withdrawal is removed. Read the final amount from get-withdrawals.

If the call times out or the connection drops, PayMe may still have acted. Check [get-withdrawals](/payments/query-apis/post-get-withdrawals) before you retry: there is no idempotency key.

## Withdraw specific transactions

To withdraw only some transactions, add `transaction_ids` with `payme_transaction_id` values from [get-transactions](/payments/query-apis/post-get-transactions):

```json
{
  "payme_client_key": "XXXXXXXX",
  "seller_payme_id": "MPLDEMO-MPLDEMO-MPLDEMO-1234567",
  "withdrawal_currency": "ILS",
  "transaction_ids": ["TRANDEMO-XXXXXXXX-XXXXXXXX-XXXXXXXX"]
}
```

Every transaction must belong to the seller, be in the withdrawal currency, be released and not be withdrawn already. PayMe also takes in the released, unwithdrawn transactions on the same sales, such as a refund. `transaction_ids` in the response lists every transaction involved, so it can hold more IDs than you sent.

## Track withdrawals

| To see | Call | Fields |
| --- | --- | --- |
| Past withdrawals | [get-withdrawals](/payments/query-apis/post-get-withdrawals) | `withdrawal_payme_code`, `withdrawal_created`, `withdrawal_currency`, `withdrawal_total`, `withdrawal_source`, `withdrawal_card_brand` |
| Upcoming withdrawals | [get-future-withdrawals](/payments/query-apis/get-future-withdrawals) | `created_at`, `total`, `start_time`, `end_time`, `withdrawable` |

- **get-withdrawals:** a seller sees its own withdrawals. A partner sees all its sellers, or those named in `seller_payme_id`. The response has no status for the bank transfer.
- **get-future-withdrawals:** send `seller_payme_id` and `currency`, both required, for one seller per request. An item with `end_time` `-1` covers everything after the listed periods. `withdrawal_payme_code` on this call doesn't match the code on get-withdrawals.

## Callback

PayMe sends `withdrawal-complete` to the partner's default [callback](/payments/getting-started/callbacks) URL when the withdrawal is recorded, which is before the bank transfer arrives. Treat it as a prompt: read get-withdrawals and act on what that returns. De-duplicate on `tran_payme_code`.

| Field | Example | Meaning |
| --- | --- | --- |
| `notify_type` | `withdrawal-complete` | Type of callback |
| `payme_status` | `success` | Always `success` for this callback |
| `status_code` | `0` | `0` for success |
| `status_error_code` | `0` | `0` for success |
| `seller_payme_id` | `MPLDEMO-MPLDEMO-MPLDEMO-1234567` | The seller |
| `seller_id` | `store-1001` | Your own ID for the seller, if you set one |
| `sale_payme_code` | `0` | Always `0` |
| `tran_payme_code` | `10001` | The same number as `withdrawal_payme_code` |
| `tran_created` | `2026-11-03 15:15:15` | Withdrawal time, Asia/Jerusalem |
| `tran_type` | `40` | Bank withdrawal |
| `tran_currency` | `ILS` | Currency |
| `tran_total` | `600000` | Amount in minor units |
| `tran_description` | (Hebrew text) | A Hebrew label. Don't parse it |

## Common errors

Branch on `status_error_code`, as described on [Errors](/payments/getting-started/errors).

| Code | Meaning | What to do |
| --- | --- | --- |
| `2` | A previous withdrawal is stuck on a funds mismatch | Contact PayMe support |
| `17` | More than one currency was sent | Send one currency per request |
| `42` | `withdrawal_amount` isn't an integer | Send the amount in minor units, as an integer |
| `109` | The seller isn't approved yet | Complete document verification and approval |
| `165` | Bank details are missing | Update the seller's bank details |
| `171` | No funds available to withdraw, or `withdrawal_amount` is above them | Check `wallet_releasable` and try after funds are released |
| `252` | Unknown `withdrawal_currency` | Send a 3-letter currency code, such as `ILS` |
| `907` | The seller is on an automatic plan | Don't call withdraw-balance; track with the query APIs |
| `908` | The seller is paid directly | Money comes from the card companies |
| `913` | Amount is below the minimum | Wait until the released balance reaches the minimum, by default 100.00 in the currency |
| `998` | HTTP 429: a withdrawal for this seller is still running | Retry later, after checking get-withdrawals |
| `507` | A listed transaction is in another currency | Send one currency per request |
| `523` | A listed transaction isn't released yet | Retry after `transaction_release_date` |
| `525` | A listed transaction was already withdrawn | Remove it from `transaction_ids` |
| `526` | A listed transaction wasn't found | Check the IDs and the seller |