Skip to main content
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.
  • 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:
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.
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: 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

The withdrawal call in six languages: Request a withdrawal.