Withdrawals

Related

• Reconcile sales and withdrawals
• 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, and on whether the card companies pay the seller directly:

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.

Approval needs the seller's documents. Upload them with Upload seller files, using the codes on File types:

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 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.

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

Request a withdrawal

Call withdraw-balance with one currency. A partner sends payme_client_key and seller_payme_id.

{
  "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:

{
  "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 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:

{
  "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

• 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 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.

Common errors

Branch on status_error_code, as described on Errors.