# Onboard a seller, from creation to first payout

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

## Prerequisites

- Partner credentials (payme_client_key) from PayMe Partners
- A default callback URL on your partner account, to receive seller callbacks

## Related

- [Create sellers](/marketplaces-and-platforms/seller-onboarding/create-seller)
- [Create a seller](/payments/merchants-management/post-create-seller)
- [Upload seller files](/payments/merchants-management/post-upload-seller-files)
- [File types](/marketplaces-and-platforms/seller-reference/file-types)
- [List sellers](/payments/query-apis/post-get-sellers)
- [Update a seller](/payments/merchants-management/post-update-seller)
- [Withdrawals](/marketplaces-and-platforms/fees-and-payouts/withdrawals)
- [Platform fees](/marketplaces-and-platforms/fees-and-payouts/platform-fees)
- [Start here: build a platform or marketplace on PayMe](/marketplaces-and-platforms/start-here/how-platforms-work)
- [Callbacks](/payments/getting-started/callbacks)

This guide follows one seller through its whole life on your platform: you create it, upload its documents, PayMe approves it, it takes its first payment and gets its first payout. Only partners onboard sellers, with their `payme_client_key`. For the two ways to create a seller and the fields PayMe's onboarding pages ask for, see [Create sellers](/marketplaces-and-platforms/seller-onboarding/create-seller).

## The lifecycle at a glance

| Stage | What you do | How you know it's done |
|---|---|---|
| 1. Collect the details | Your onboarding form | Nothing to check yet |
| 2. Create the seller | [create-seller](/payments/merchants-management/post-create-seller) | `seller_payme_id` in the response, then the `seller-create` callback |
| 3. Upload the documents | [upload-seller-files](/payments/merchants-management/post-upload-seller-files), or the seller uploads them on PayMe's onboarding pages | `status_code` `0` |
| 4. Approval | Wait for PayMe's review | The `seller-approve` callback, and `seller_approved` `true` on [get-sellers](/payments/query-apis/post-get-sellers) |
| 5. Services | The seller installs payment methods, or you call `vas-enable` | [get-vas-seller](/payments/merchants-management/post-get-vas-seller) lists them |
| 6. First sale | [generate-sale](/payments/hosted-payment-page/post-generate-sale) with the seller's MPL | The `sale-complete` callback |
| 7. First payout | [withdraw-balance](/payments/merchants-management/post-withdraw-balance), or automatic | The `withdrawal-complete` callback, then [get-withdrawals](/payments/query-apis/post-get-withdrawals) |

A seller can take payments from stage 2. Only the payout waits for approval.

## 1. Collect the seller's details

- **Required fields:** PayMe sets which create-seller fields are required for your partner account. A missing one returns error `19`, and `status_additional_info` names it. `seller_email` is always required and must be unique among your sellers (error `150`).
- **Your own ID:** send `seller_id` to find the seller by your ID later. It must be unique among your sellers (error `108`).
- **Reference lists:** incorporation types per country on [Seller incorporation types](/marketplaces-and-platforms/seller-reference/seller-incorporation-types-il) (error `114`), business field codes on [List business fields](/payments/merchants-management/get-business-fields) (error `110`), bank codes on [Banks in Israel](/payments/codes-statuses/banks-in-israel) (error `106`).
- **Dates:** `dd/mm/yyyy` with leading zeros, for example `06/05/1989`.
- **Other people in the business:** owners, signatories and directors go in `seller_additional_details`, one object per person, with their roles from [Individual seller types](/marketplaces-and-platforms/seller-reference/individual-seller-types).

## 2. Create the seller

Call [create-seller](/payments/merchants-management/post-create-seller) from your server:

```bash
curl -X POST https://sandbox.payme.io/api/create-seller \
  -H 'Content-Type: application/json' \
  -d '{
    "payme_client_key": "XXXXXXXX",
    "seller_id": "store-1001",
    "seller_first_name": "Dana",
    "seller_last_name": "Levi",
    "seller_social_id": "9999999999",
    "seller_birthdate": "06/05/1989",
    "seller_social_id_issued": "01/02/2015",
    "seller_gender": 1,
    "seller_email": "random@paymeservice.com",
    "seller_phone": "+972501234567",
    "seller_bank_code": 54,
    "seller_bank_branch": 123,
    "seller_bank_account_number": "123456",
    "seller_site_url": "https://www.example.com",
    "seller_person_business_type": 205,
    "seller_inc": 1,
    "seller_merchant_name": "Dana Ceramics",
    "seller_address_city": "Tel Aviv",
    "seller_address_street": "Herzl",
    "seller_address_street_number": "10",
    "seller_address_country": "IL",
    "market_fee": 2.5,
    "language": "en"
  }'
```

The values `9999999999`, `random@paymeservice.com` and bank `54` are sandbox test values. Use the seller's real details in production.

From the response:

```json
{
  "status_code": 0,
  "session": "a1B2c3D4",
  "seller_payme_id": "MPLDEMO-MPLDEMO-MPLDEMO-1234567",
  "seller_payme_secret": "Qw3rTy7uI9oP1aS5dF8gH2jK4lZ6xC",
  "seller_public_key": {
    "uuid": "12345678-1234-4abc-9def-123456789012",
    "description": "PayMe-Public-Key",
    "is_active": true
  },
  "seller_id": "store-1001",
  "seller_dashboard_signup_link": "https://<signup-host>/<link-from-payme>"
}
```

- Store `seller_payme_id` (the MPL) on your server. You send it on every call for this seller.
- Store `seller_public_key.uuid` for the seller's browser code.
- Send the seller `seller_dashboard_signup_link`, exactly as returned. There the seller sets a password and finishes onboarding.
- Ignore `seller_payme_secret`: it isn't a credential.

The call is limited to 5 requests per minute per IP. Over the limit, or while a call for the same `seller_email` is still running, it returns HTTP 429 with error `998`: wait and retry. A partner sets the seller's default platform fee here with `market_fee`; it can't be changed later with update-seller. See [Platform fees](/marketplaces-and-platforms/fees-and-payouts/platform-fees).

## 3. Upload the documents

PayMe approves a seller only after it has checked the seller's documents. Use the codes on [File types](/marketplaces-and-platforms/seller-reference/file-types):

| Seller | Files |
|---|---|
| Every seller | `1` social ID and `2` bank account ownership |
| Every seller except a private individual, a House Committee, and Municipalities and councils | Also `3` corporate certificate |
| A House Committee | Also `14` authorized signer protocol and `7` processing agreement |
| Municipalities and councils | Also `27` origin tax confirmation and `7` processing agreement |
| Some services and partner accounts | Also `7` or `29`. Your account manager will tell you. |

There are three ways to send them:

- **[upload-seller-files](/payments/merchants-management/post-upload-seller-files):** one or more files, each as a public `url` or as `base64` content.
- **On create-seller:** public URLs in `seller_file_social_id` (type `1`), `seller_file_cheque` (type `2`) and `seller_file_corporate` (type `3`). PayMe downloads them in the background.
- **The seller uploads them** on PayMe's onboarding pages, through `seller_dashboard_signup_link`.

```json
{
  "payme_client_key": "XXXXXXXX",
  "seller_payme_id": "MPLDEMO-MPLDEMO-MPLDEMO-1234567",
  "seller_files": [
    {
      "name": "social_id.pdf",
      "type": 1,
      "url": "https://www.example.com/files/social_id.pdf",
      "mime_type": "application/pdf"
    }
  ],
  "language": "en"
}
```

Personal documents (types `90`–`97`, such as the front and back of an ID) belong to a person:

- In `seller_additional_details[].files` on create-seller, they are attached to that person.
- With upload-seller-files, they are attached to the seller's primary individual. If the seller has more than one individual, the call fails with error `184`.

Allowed file types and the upload errors (`904`, `905`, `909`) are on [upload-seller-files](/payments/merchants-management/post-upload-seller-files).

## 4. Verification and approval

PayMe reviews the seller's details and documents. You learn the result from seller callbacks and from get-sellers.

### Seller callbacks

PayMe sends these callbacks to your partner account's default callback URL as a form-encoded `POST`. Each carries the seller's details (`seller_payme_id`, `seller_id`, `seller_active`, `seller_approved` and more): see [Callbacks → Sellers](/payments/getting-started/callbacks#sellers-partners).

| `notify_type` | When PayMe sends it |
|---|---|
| `seller-create` | The seller was created. Also carries `seller_public_key`. |
| `seller-update` | The seller changed: after update-seller, when PayMe records the result of a check on the seller, and when the seller's approval changes. |
| `seller-approve` | PayMe approved the seller. Also carries `partner_name`. |

- When PayMe approves a seller, it sends both `seller-approve` and `seller-update`. They can arrive in any order.
- A `seller-update` during the review isn't an approval. Wait for `seller-approve`, or for `seller_approved` `1`.
- Seller callbacks carry no signature. Treat each one as a prompt: read the seller with get-sellers and act on what it returns.
- If your partner account has no default callback URL, PayMe sends no seller callbacks. Ask PayMe Partners to set one, or check get-sellers.

### Check the seller's state

Call [get-sellers](/payments/query-apis/post-get-sellers) with the seller's MPL:

```json
{
  "payme_client_key": "XXXXXXXX",
  "seller_payme_id": "MPLDEMO-MPLDEMO-MPLDEMO-1234567",
  "api_mode": "slim"
}
```

| Field | Meaning |
|---|---|
| `seller_approved` | `true` once PayMe has approved the seller. Withdrawals need it. |
| `seller_approved_date` | When PayMe approved the seller, or `null` |
| `seller_active` | `true` if the seller is active |

To list every seller that is still waiting, send `payme_client_key` with `"seller_approved": false`.

### If a document is declined

Upload a corrected file with the same type. If a required document is declined after the seller was approved, the seller loses its approval: you get a `seller-update` with `seller_approved` `0`, and withdrawals fail with error `109` until PayMe approves the seller again.

### Before and after approval

| | Before approval | After approval |
|---|---|---|
| Take payments | Yes | Yes |
| Request a withdrawal | No, error `109` | Yes, if the seller is active, has bank details and has released funds |

## 5. Turn on payment methods and services

- **Apple Pay, Google Pay, Bit:** the seller installs them from the dashboard app store (חנות אפליקציות), or you enable them with `vas-enable`. See [Accept Apple Pay](/accepting-payments/payment-methods/apple-pay) and [Accept Google Pay](/accepting-payments/payment-methods/google-pay). A sale with a method the seller doesn't have fails with error `720`.
- **3D Secure:** enabled on the seller's account by PayMe.
- **Check:** [get-vas-seller](/payments/merchants-management/post-get-vas-seller) lists the services installed on the seller. Service types are on [VAS types](/marketplaces-and-platforms/seller-reference/vas-types).

## 6. Take the first sale

Create the sale with the seller's MPL, from your server. Add `market_fee` to override the seller's default fee for this sale. The full example is on [Start here: build a platform or marketplace on PayMe](/marketplaces-and-platforms/start-here/how-platforms-work), and the fee rules on [Platform fees](/marketplaces-and-platforms/fees-and-payouts/platform-fees).

## 7. Get the first payout

How the seller is paid depends on `seller_withdrawal_plan` on get-sellers. A new seller starts on your partner account's default plan:

| Plan | How the seller is paid |
|---|---|
| `1` manual | You request each withdrawal with withdraw-balance |
| `2` automatic, daily | PayMe pays out by itself. withdraw-balance returns error `907`. |
| `3` automatic, monthly | PayMe pays out on `seller_withdrawal_date`. withdraw-balance returns error `907`. |

A seller paid directly by the card companies gets its money from them, and withdraw-balance returns error `908`.

Before the first withdrawal, check that:

- the seller is approved (otherwise error `109`) and has bank details on file (otherwise error `165`);
- `seller_wallets.<currency>.wallet_releasable` on get-sellers is above zero. It isn't returned with `api_mode` `slim`. Each sale's `sale_release_date` on get-sales tells you when its money is released;
- the released balance reaches the minimum, by default 100.00 in the currency (otherwise error `913`).

On plan `1`, request the withdrawal:

```json
{
  "payme_client_key": "XXXXXXXX",
  "seller_payme_id": "MPLDEMO-MPLDEMO-MPLDEMO-1234567",
  "withdrawal_currency": "ILS"
}
```

This withdraws the whole released balance in that currency. When the withdrawal is recorded, PayMe sends `withdrawal-complete` to your default callback URL, before the bank transfer arrives. Read the final amount from get-withdrawals. Partial withdrawals, specific transactions, the callback fields and every error are on [Withdrawals](/marketplaces-and-platforms/fees-and-payouts/withdrawals).

In the sandbox, sellers start on an automatic plan: ask PayMe to set up a test seller before you test a withdrawal.

## Change a seller later

Call [update-seller](/payments/merchants-management/post-update-seller) with `payme_client_key`, the seller's MPL (or your `seller_id`) and only the fields you want to change. PayMe then sends `seller-update`.

- PayMe sets which fields stay locked once they have a value. Changing one returns error `33`.
- `seller_additional_details` adds people. It doesn't change or remove the people already on file.
- The seller's default `market_fee` can't be changed with update-seller. Contact PayMe Partners (<partners@payme.io>).