# List future withdrawals

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

- Sandbox: `POST https://sandbox.payme.io/api/get-future-withdrawals`
- Production: `POST https://live.payme.io/api/get-future-withdrawals`

## Credentials

- Header `PayMe-Partner-Key` (optional): Partner key, instead of `payme_client_key` in the body. Partners only.
- Header `PayMe-Merchant-Key` (optional): A seller's own MPL, instead of `seller_payme_id` in the body.
- Request body field `seller_payme_id` (optional): The seller's MPL. Required unless a partner sends `seller_id`. Can also be sent in the `PayMe-Merchant-Key` header.
- Request body field `payme_client_key` (optional): Partner key. Required with `seller_id`. Can also be sent in the `PayMe-Partner-Key` header.

Projects a seller's upcoming withdrawals in one currency, from the funds waiting for release and the seller's withdrawal plan. Use it to show the next payout dates and amounts.

A seller sends its own `seller_payme_id` (in the body or the `PayMe-Merchant-Key` header). A partner sends `payme_client_key` with the seller's `seller_payme_id` or your own `seller_id`. Send `currency` too. One seller and one currency per call.

You get `limit` items: `limit − 1` scheduled payouts, then one summary item with `end_time` `-1` that holds everything due later. Amounts are in minor units. When card companies pay the seller directly, the items are split by release date, `source` and `card_brand`, with `withdrawable` `0`.

The call doesn't page. It is rate limited per seller: on HTTP 429 (error `998`), wait for the `Retry-After` time and retry. A missing `currency` returns error `1`, and an unknown one returns error `24`.

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `PayMe-Partner-Key` | header | string | no | Partner key, instead of `payme_client_key` in the body. Partners only. |
| `PayMe-Merchant-Key` | header | string | no | A seller's own MPL, instead of `seller_payme_id` in the body. |

## Request body

Content type: `application/json`

Send `currency` and identify one seller.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `seller_payme_id` | string | no | The seller's MPL. Required unless a partner sends `seller_id`. Can also be sent in the `PayMe-Merchant-Key` header. |
| `payme_client_key` | string | no | Partner key. Required with `seller_id`. Can also be sent in the `PayMe-Partner-Key` header. |
| `seller_id` | string | no | Your own ID for the seller, as sent to create-seller. Partners only, with `payme_client_key`. |
| `currency` | string | yes | Wallet currency, 3-letter [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) code, for example `ILS`. |
| `limit` | integer | no | Number of items to return, including the final summary item. Default `7`. |
| `language` | string | no | Language of `source_text` and `card_brand_text`: `he` (default) or `en`. |

### Request example

```json
{
  "seller_payme_id": "MPLDEMO-MPLDEMO-MPLDEMO-1234567",
  "currency": "ILS",
  "limit": 3,
  "language": "en"
}
```

## Code samples

### curl

```bash
curl -X POST 'https://sandbox.payme.io/api/get-future-withdrawals' \
  -H 'Content-Type: application/json' \
  -H 'PayMe-Partner-Key: <PayMe-Partner-Key>' \
  -H 'PayMe-Merchant-Key: <PayMe-Merchant-Key>' \
  --data-raw '{
  "seller_payme_id": "MPLDEMO-MPLDEMO-MPLDEMO-1234567",
  "currency": "ILS",
  "limit": 3,
  "language": "en"
}'
```

### Node.js

```javascript
const response = await fetch("https://sandbox.payme.io/api/get-future-withdrawals", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "PayMe-Partner-Key": "<PayMe-Partner-Key>",
    "PayMe-Merchant-Key": "<PayMe-Merchant-Key>",
  },
  body: JSON.stringify({
    "seller_payme_id": "MPLDEMO-MPLDEMO-MPLDEMO-1234567",
    "currency": "ILS",
    "limit": 3,
    "language": "en"
  }),
});

console.log(await response.text());
```

### Python

```python
import requests

response = requests.post(
    "https://sandbox.payme.io/api/get-future-withdrawals",
    headers={
        "PayMe-Partner-Key": "<PayMe-Partner-Key>",
        "PayMe-Merchant-Key": "<PayMe-Merchant-Key>",
    },
    json={
        "seller_payme_id": "MPLDEMO-MPLDEMO-MPLDEMO-1234567",
        "currency": "ILS",
        "limit": 3,
        "language": "en",
    },
)

print(response.text)
```

### PHP

```php
<?php

$body = <<<'BODY'
{
  "seller_payme_id": "MPLDEMO-MPLDEMO-MPLDEMO-1234567",
  "currency": "ILS",
  "limit": 3,
  "language": "en"
}
BODY;

$ch = curl_init('https://sandbox.payme.io/api/get-future-withdrawals');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json',
        'PayMe-Partner-Key: <PayMe-Partner-Key>',
        'PayMe-Merchant-Key: <PayMe-Merchant-Key>',
    ],
    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. |
| `withdrawal_plan` | integer | The seller's withdrawal plan: `1` manual, `2` daily, `3` monthly. |
| `currency` | string | The currency you asked for. |
| `items_count` | integer | Number of items. |
| `items` | array | Expected payouts, then one summary item. |
| `items[].start_time` | integer | Start of the period the payout covers, Unix epoch. |
| `items[].end_time` | integer | Expected payout time, Unix epoch. `-1` on the summary item. |
| `items[].created_at` | string | Expected payout date and time, `yyyy-mm-dd hh:mm:ss`. On the summary item, the current time. |
| `items[].withdrawable` | integer | `1` paid out by PayMe; `0` paid directly by a card company. |
| `items[].source` | integer | Who pays it out: `1` PayMe, other values a card company. |
| `items[].source_text` | string | Name of `source`, in the requested `language`. |
| `items[].card_brand` | integer | Card brand code. |
| `items[].card_brand_text` | string | Name of `card_brand`, in the requested `language`. |
| `items[].total` | string | Expected amount, in minor units. |
| `items[].withdrawal_payme_code` | string | Opaque token for this expected payout. It's not a withdrawal code from get-withdrawals. |

```json
{
  "status_code": 0,
  "withdrawal_plan": 2,
  "currency": "ILS",
  "items_count": 3,
  "items": [
    {
      "start_time": 1793836800,
      "end_time": 1793923200,
      "created_at": "2026-11-06 02:00:00",
      "withdrawable": 1,
      "source": 1,
      "source_text": "PayMe",
      "card_brand": 1,
      "card_brand_text": "Other",
      "total": "48250",
      "withdrawal_payme_code": "<opaque-token>"
    },
    {
      "start_time": 1793923200,
      "end_time": 1794009600,
      "created_at": "2026-11-07 02:00:00",
      "withdrawable": 1,
      "source": 1,
      "source_text": "PayMe",
      "card_brand": 1,
      "card_brand_text": "Other",
      "total": "0",
      "withdrawal_payme_code": "<opaque-token>"
    },
    {
      "start_time": 1794009600,
      "end_time": -1,
      "created_at": "2026-11-05 14:00:20",
      "withdrawable": 1,
      "source": 1,
      "source_text": "PayMe",
      "card_brand": 1,
      "card_brand_text": "Other",
      "total": "156390",
      "withdrawal_payme_code": "<opaque-token>"
    }
  ]
}
```

### 500 — Error. Most errors return HTTP 500; the rate limit (`998`) returns HTTP 429. The body is the same. See [Errors](/payments/getting-started/errors). (error)

| Field | Type | Description |
| --- | --- | --- |
| `status_code` | integer | `1` on failure. |
| `status_error_code` | integer | PayMe error code. |
| `status_error_details` | string | Error message. |
| `status_additional_info` | string | The field the error refers to, when there is one. |

```json
{
  "status_code": 1,
  "status_error_details": "Required parameter is missing",
  "status_additional_info": "currency",
  "status_error_code": 1
}
```