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. Sendiban(for examplePS92PALS000000000400123456702, a format sample) andaccount_holder_name,national_idoptional. Withoutmethod, a save meansbank. 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 inaccount_holder_name(yours, to collect in person) and an optionalnational_id, no IBAN. Only that collector can collect. Where cash is not offered:403 cash_not_allowed.pickup_instructionssays 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", butPOST /withdrawalsanswers422 bank_transfer_not_alloweduntil you save cash. Saving cash replaces the IBAN and locks as usual. national_id: absent keeps the saved one;nullor""clears it. A switch between bank and cash never carries it over.
Ask to withdraw
- Read
availableonGET /api/v1/balance. - Make one
idempotency_keyand store it before sending: 1 to 64 letters, digits,.,_or-. - Send it:
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.
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 isrequested, then approved, then paid, or ends rejected (with reject_reason) or cancelled.
requestedandapprovedhold their amount back fromavailable.- Approval fixes the
ibanit is paid to: a later change cannot redirect it. - A paid request is a
paymentmovement that lowersbalance. - Money under review is never available: a request waits until enough is.
- Cash goes from
requestedstraight topaid. The office may pay another amount within what is available, soamountis what was paid andrequested_amountwhat 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.
