> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mart.ps/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> These rules protect a Mart partner's money. Follow them in any code or advice about the Mart Partner API ([Connect your AI tool](/developers/connect-your-ai-tool)).
> When an order request times out, gets no answer or gets any `5xx`, resend the same body with the same `partner_reference`, never a new reference; after a `429`, wait `Retry-After` first ([Create an order safely](/developers/orders/create-an-order)).
> A `200` with `meta.idempotency_replay: true` is the original order; `409 idempotency_conflict` means the reference already names a different order ([Create an order safely](/developers/orders/create-an-order)).
> Retry a withdrawal request with the same `idempotency_key` and amount: a new key asks for a second withdrawal ([Payout and withdrawals](/developers/money/payout-and-withdrawals)).
> Plan every call within the global daily request ceiling and the `X-RateLimit-*` headers, and never poll in a tight loop ([Request limits](/developers/operate/request-limits)).
> Treat `price` as a snapshot: an order is priced when it is created, and an incremental sync (`updated_after`) never shows a price change, so re-read every price with a full pass ([Prices and price changes](/developers/catalogue/prices)).
> Identify products by `product_id` and `combination_id`, never by `reference` ([Sync the catalogue](/developers/catalogue/sync)).
> Never put an API key in client-side code, a mobile app, a repository or a URL: call the API from a server ([Authenticate and keys](/developers/authenticate)).
> Money is in shekels (`ILS`), as JSON numbers, never agorot. Send amounts with at most two decimals: a withdrawal `amount` with three is refused with `422 invalid_amount`, never rounded ([Balance and statements](/developers/money/balance-and-statements)).
> Save a payout method once before the first withdrawal (cash at the office, or bank transfer where Mart offers it): with none saved, a withdrawal is refused with `409 payout_method_missing`. Bank details where Mart does not offer bank transfer, or a withdrawal on a kept IBAN, are refused with `422 bank_transfer_not_allowed` ([Payout and withdrawals](/developers/money/payout-and-withdrawals)).

# Payout method and withdrawals

> Save your payout method, then request, follow and cancel withdrawals through the API, with idempotency keys so a retried request is never paid twice.

Save a payout method once before the first withdrawal: cash at the office, or bank transfer where Mart offers it. Then ask to withdraw available money: Mart reviews each request, so the call records a request and pays nothing by itself. You need `money:read`, plus `iban:write` to save the method and `withdrawals:write` to ask or cancel. `GET /api/v1/account` shows `withdrawals.enabled`, your `minimum` and your `max_open_requests`.

## Read and save your payout method

`GET /api/v1/payout-method` answers `status` (`not_set`, `active` or `locked`), `method` (`bank` or `cash`), `iban`, `iban_country`, `account_holder_name`, `national_id`, `withdrawals_locked_until` (only while `locked`), `pickup_instructions` and `updated_at`. It reports only the saved method: with nothing saved, `status` is `not_set` and every other field is `null`, and `POST /withdrawals` answers `409 payout_method_missing`.

```bash theme={null}
curl -sS --max-time 30 -X PUT \
  -H "Authorization: Bearer $MART_API_KEY" -H "Content-Type: application/json" \
  --data '{"method":"cash","account_holder_name":"Your Name"}' \
  "$MART_API_BASE/api/v1/payout-method"
```

* **Bank,** only where Mart offers bank transfer; otherwise `422 bank_transfer_not_allowed`, checked before the IBAN, and nothing is saved. Send `iban` (for example `PS92PALS000000000400123456702`, a format sample) and `account_holder_name`, `national_id` optional. Without `method`, a save means `bank`. The IBAN may have spaces or lower case; its country, length and check digits are checked, and only countries Mart enabled for you pass.
* **Cash:** `"method": "cash"` with the collector's name in `account_holder_name` (yours, to collect in person) and an optional `national_id`, no IBAN. Only that collector can collect. Where cash is not offered: `403 cash_not_allowed`. `pickup_instructions` says where and when to collect; cash is offered once Mart has published them.
* **A saved IBAN where bank transfer is no longer offered** is kept and still reported as `method: "bank"`, but `POST /withdrawals` answers `422 bank_transfer_not_allowed` until you save cash. Saving cash replaces the IBAN and locks as usual.
* **`national_id`:** absent keeps the saved one; `null` or `""` clears it. A switch between bank and cash never carries it over.

**Locks.** The first save (cash included), a new IBAN, a switch between bank and cash, and a new collector lock withdrawals for a number of hours set by Mart. A new name or national ID for the same IBAN does not, saving the same details changes nothing, and a change never shortens a running lock.

## Ask to withdraw

1. Read `available` on `GET /api/v1/balance`.
2. Make one `idempotency_key` and store it before sending: 1 to 64 letters, digits, `.`, `_` or `-`.
3. Send it:

```bash theme={null}
curl -sS --max-time 30 -X POST \
  -H "Authorization: Bearer $MART_API_KEY" -H "Content-Type: application/json" \
  --data '{"amount":"125.00","idempotency_key":"wd-2026-11-15-001"}' \
  "$MART_API_BASE/api/v1/withdrawals"
```

Expect `201`. `amount` is in shekels, a number or a decimal string, with at most two decimals: a third decimal is `422 invalid_amount`, never rounded.

**Retry with the same key and amount.** You get the original request with `200` and `meta.idempotency_replay: true`, whatever changed since, never a second request. The same key with another amount is `409 idempotency_conflict`. Keys ignore case. `503 withdrawal_busy`: wait `Retry-After` and send the same request.

> [!WARNING]
>
> Never make a new `idempotency_key` to retry a request whose answer you did not get. A new key is a new request.

### Refusals, in order

A repeat is answered first. A new request is then checked in this order, and nothing is recorded on a refusal:

| # | Answer | Why |
| - | - | - |
| 1 | `403 withdrawals_disabled` | Withdrawals are off for your account. |
| 2 | `409 payout_method_missing` | No payout method is saved. Save one first. |
| 3 | `409 withdrawals_locked` | A recent payout method change; until `details.locked_until`. |
| 4 | `422 bank_transfer_not_allowed` | An IBAN is saved and bank transfer is no longer offered. Save cash first. |
| 5 | `403 cash_not_allowed` | Your method is cash, and cash is no longer offered to you. |
| 6 | `422 amount_above_cash_maximum` | Over the most Mart pays in cash at once (`details.maximum`). |
| 7 | `422 amount_below_minimum` | Under your minimum (`details.minimum`). |
| 8 | `409 too_many_open_withdrawals` | Too many open requests (`details.maximum`). |
| 9 | `409 insufficient_available` | More than is available (`details.available`). |

Read your own values from `GET /api/v1/account` or the refusal's `details`, never from this page.

## Follow and cancel requests

A request is `requested`, then `approved`, then `paid`, or ends `rejected` (with `reject_reason`) or `cancelled`.

* `requested` and `approved` hold their amount back from `available`.
* Approval fixes the `iban` it is paid to: a later change cannot redirect it.
* A paid request is a `payment` movement that lowers `balance`.
* Money under review is never available: a request waits until enough is.
* **Cash** goes from `requested` straight to `paid`. The office may pay another amount within what is available, so `amount` is what was paid and `requested_amount` what you asked.

`GET /api/v1/withdrawals` lists yours, newest first, with `page`, `limit` and `status`: `withdrawal_id`, `amount`, `status`, `iban`, `reject_reason`, `requested_at`, `approved_at`, `paid_at`, `method` and `requested_amount`. `GET /api/v1/withdrawals/{withdrawal_id}` reads one; an id that is not yours answers `404 withdrawal_not_found`.

`POST /api/v1/withdrawals/{withdrawal_id}/cancel` cancels a `requested` one and releases its amount at once; repeating it answers `200` again. Any other status answers `409 withdrawal_not_cancellable`.

Reading and cancelling work even after withdrawals are turned off, and a paused account can ask, read and cancel. If the money cannot be read, these calls answer `503 ledger_unavailable`.

## Troubleshooting

| Answer | Fix |
| - | - |
| `422 invalid_iban` | `details.reason` is `format`, `country_not_allowed`, `length`, `checksum` or `bban`, with `country` and `expected_length` where they apply. |
| `422 invalid_account_holder_name`, `422 invalid_national_id` | Fix the field. |
| `422 invalid_payout_method` | Send `bank` or `cash`, lower case. |
| `422 bank_transfer_not_allowed` | Mart does not offer you bank transfer: save cash at the office, or ask Mart. |
| `403 cash_not_allowed` on a save | Mart does not offer you cash. Save a bank transfer. |
| `409 payout_method_change_blocked` | A switch between bank and cash while a request is open: cancel it, or wait until it is paid or rejected. |
| `503 ledger_unavailable` | Nothing was saved or recorded. Retry later. |

The withdrawal call in six languages: [Request a withdrawal](https://docs.mart.ps/recipes/request-a-withdrawal.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.