# Create a seller

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

- Sandbox: `POST https://sandbox.payme.io/api/create-seller`
- Production: `POST https://live.payme.io/api/create-seller`

## Credentials

- Request body field `payme_client_key` (required): Your partner key. Partners only.

Creates a seller under your partner account and returns its `seller_payme_id` (MPL), its public key, and a link where the seller finishes onboarding. Partners only: send your `payme_client_key`. A seller's MPL can't be used to create sellers. For the whole onboarding flow, see [Create sellers](/marketplaces-and-platforms/seller-onboarding/create-seller).

PayMe sets which fields are required for your account. A missing required field returns error `19`, with the field name in `status_additional_info`. The **Required** column below shows the usual setup. `seller_email` is always required and must be unique among your sellers (error `150`). `seller_id`, if you send it, must also be unique among your sellers (error `108`). Other fields can be enabled for your account by PayMe.

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, you get HTTP 429 with error `998`. Wait and retry.

### Testing in the sandbox

Field | Test value
---|---
`seller_social_id` | `9999999999`. PayMe replaces it with a random valid ID.
`seller_email` | `random@paymeservice.com`. PayMe replaces it with a unique address and sends no emails.
`seller_bank_code` | `54`
`seller_bank_branch` | Any 3 digits, for example `123`
`seller_bank_account_number` | Any 6 digits, for example `123456`

### Callback

When the seller is created or updated, PayMe sends a seller callback (`POST`, `x-www-form-urlencoded`) to your default callback URL. The fields are listed on [Callbacks → Sellers](/payments/getting-started/callbacks#sellers-partners).

### Errors

Every error returns `status_code` `1` with the code in `status_error_code`. The common ones:

Code | Meaning
---|---
`1` | A required parameter is missing, for example `payme_client_key`.
`5` | `seller_description` is longer than 255 characters.
`13` | `seller_email` is missing or invalid.
`19` | A field your account requires is missing. `status_additional_info` names it.
`25` | Invalid phone number.
`57` | `seller_merchant_name_en` or `seller_dba_en` isn't in Latin characters.
`101` | Invalid national ID number.
`106` | Unknown `seller_bank_code`.
`108` | `seller_id` is already used by another of your sellers.
`110` | Unknown or inactive business field in `seller_person_business_type`.
`114` | Unknown incorporation type, a type from another country than `seller_address_country`, or a `seller_inc_code` that doesn't fit the type.
`116` / `117` / `118` | Invalid birth date / registration date / ID issue date.
`119` | Invalid `seller_retail_type`.
`120` | Invalid characters in `seller_merchant_name`.
`121` | `seller_inc_code` isn't a number.
`131` | Invalid `seller_gender`.
`150` | `seller_email` is already used by another of your sellers.
`160` | An item in `seller_additional_details` has no `type`, or one of its files isn't an individual file type.
`165` | Invalid bank branch or account number.
`304` | `market_fee` is outside 0–60.
`912` | Unknown `seller_address_country`.
`998` | HTTP 429: over the rate limit, or a call for the same `seller_email` is still running.

The full list is on [Errors](/payments/getting-started/errors).

## Parameters

This endpoint takes no path, query or header parameters.

## Request body

Content type: `application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `payme_client_key` | string | yes | Your partner key. Partners only. |
| `seller_id` | string | no | Your own ID for the seller. Must be unique among your sellers (error `108`). |
| `seller_first_name` | string | yes | First name of the seller's owner (the seller's primary individual). |
| `seller_last_name` | string | yes | Last name of the seller's owner. |
| `seller_social_id` | string | yes | National ID number of the seller's owner. An invalid number returns error `101`. In the sandbox, `9999999999` is replaced with a random valid ID. |
| `seller_birthdate` | string | yes | Seller's personal birth date. Required by default; PayMe can change this per partner. Format `dd/mm/yyyy` with leading zeros only: `06/05/1989` is accepted, `6/5/1989` and `06-05-1989` are rejected. The person must be at least 16. Responses return `yyyy-mm-dd`. |
| `seller_social_id_issued` | string | yes | Seller's personal social ID issuing day. Required by default; PayMe can change this per partner. Format `dd/mm/yyyy` with leading zeros only. Responses return `yyyy-mm-dd`. |
| `seller_gender` | integer | yes | `0` – male, `1` – female, `2` – other. Another value returns error `131`. |
| `seller_email` | string | yes | The seller's email address. Always required. It must be unique among your sellers (error `150`), and an invalid address returns error `13`. In the sandbox, `random@paymeservice.com` is replaced with a unique address. |
| `seller_phone` | string | yes | Seller phone number, supplied as a string. Mobile and landline formats are supported; international format with country code is recommended. Local numbers are interpreted using the seller's country, Israel by default. Phone validation or normalization failures return error `25`. |
| `seller_contact_email` | string | no | Seller's contact email, shown to buyers. If not sent, it is copied from `seller_email`. |
| `seller_contact_phone` | string | no | Phone number shown to buyers. If you don't send it, it is copied from `seller_phone`. |
| `seller_bank_code` | integer | yes | Bank code. See [Banks in Israel](/payments/codes-statuses/banks-in-israel). An unknown code returns error `106`. |
| `seller_bank_branch` | integer | yes | Bank branch number, up to 3 digits. An invalid branch returns error `165`. |
| `seller_bank_account_number` | string | yes | Bank account number, digits only. An invalid number returns error `165`. |
| `seller_description` | string | no | Seller’s description, including offered product line and services. Limited to 255 characters (error `5`). |
| `seller_site_url` | string | yes | The seller's website URL. |
| `seller_person_business_type` | integer | yes | Business field code (the seller's line of business). See [Business field codes](/marketplaces-and-platforms/seller-reference/mcc-list), or get the live list from [List business fields](/payments/merchants-management/get-business-fields). An unknown or inactive code returns error `110`. |
| `seller_inc` | integer | yes | Incorporation type, see [Seller incorporation types](/marketplaces-and-platforms/seller-reference/seller-incorporation-types-il). Required by default; PayMe can change this per partner. The type must belong to the seller's country (`seller_address_country`, default Israel), otherwise error `114`. If you send `seller_inc` without `seller_person_business_type`, the business field defaults to `205`. |
| `seller_inc_code` | string | no | Seller's business ID (ח.פ, ע.מ). May be required for your account (PayMe configures this per partner). When sent, it must be a number, 0 or above, otherwise the request fails with error `121`. For Israeli sellers, Individual, Sole Proprietorship and Exempt Sole Proprietorship must use the owner's national ID; other types must not equal the national ID and must start with that type's 2-digit company-registry prefix. Otherwise the request fails with error `114`. |
| `seller_registration_date` | string | no | Seller's business registration date. May be required for your account (PayMe configures this per partner). Format `dd/mm/yyyy` with leading zeros only: `01/02/2020` is accepted, `1/2/2020` and `01-02-2020` are rejected. Responses return `yyyy-mm-dd`. |
| `seller_retail_type` | integer | no | `1` – card not present (online), `2` – card present, `4` – MOTO (phone or mail order). Another value returns error `119`. |
| `seller_merchant_name` | string | no | The business's name. Invalid characters return error `120`. May be required for your account (PayMe configures this per partner). |
| `seller_merchant_name_en` | string | no | The business's name in English. Latin characters only (error `57`). |
| `seller_dba` | string | no | The seller's legal (registered) name in Hebrew. |
| `seller_dba_en` | string | no | The seller's legal (registered) name in English. Latin characters only (error `57`). |
| `seller_address_city` | string | yes | Business address: city. |
| `seller_address_street` | string | yes | Business address: street. |
| `seller_address_street_number` | string | yes | Business address: street number. |
| `seller_address_country` | string | no | Business address: country, as an ISO 3166-1 alpha-2 code such as `IL`. Default Israel. An unknown code returns error `912`. |
| `seller_first_name_en` | string | no | The seller's first name in English. |
| `seller_last_name_en` | string | no | The seller's last name in English. |
| `seller_address_state` | string | no | State or region of the business address, for sellers outside Israel. |
| `seller_address_zip` | string | no | Postal code of the business address. |
| `seller_file_social_id` | string | no | Public URL of the owner's ID card (file type `1`). PayMe downloads it in the background. To upload other documents, use [Upload seller files](/payments/merchants-management/post-upload-seller-files). |
| `seller_file_cheque` | string | no | Public URL of a bank account confirmation or a cancelled cheque (file type `2`). PayMe downloads it in the background. |
| `seller_file_corporate` | string | no | Public URL of the incorporation certificate (file type `3`). PayMe downloads it in the background. |
| `market_fee` | number | no | The seller's default platform fee: the percent of the sale price collected for you, from `0` to `60` (for example `2.5`). It includes VAT and is added on top of PayMe's fees. Default `0`. Out of range returns error `304`. A sale can override it with its own `market_fee`. It can't be changed later with Update a seller; see [Platform fees](/marketplaces-and-platforms/fees-and-payouts/platform-fees). |
| `seller_plan` | string | no | A predefined set of settings for the seller. If required, this value will be provided by your Account Manager. Required unless your account has a default plan. |
| `seller_additional_details` | array | no | More people in the business, such as owners, signatories and directors. One object per person. |
| `seller_additional_details[].first_name` | string | no | First name. |
| `seller_additional_details[].last_name` | string | no | Last name. |
| `seller_additional_details[].national_id` | string | no | National ID number. |
| `seller_additional_details[].social_id_issued` | string | no | ID issue date, `dd/mm/yyyy`. |
| `seller_additional_details[].date_of_birth` | string | no | Date of birth, `dd/mm/yyyy`. |
| `seller_additional_details[].email` | string | no | Email address. |
| `seller_additional_details[].phone` | string | no | Phone number. |
| `seller_additional_details[].type` | array | yes | The person's roles, as an array of [individual role](/marketplaces-and-platforms/seller-reference/individual-seller-types) codes, for example `[1, 2]` for an owner who is also a signatory. Missing returns error `160`. |
| `seller_additional_details[].business_title` | string | no | Job title in the business. |
| `seller_additional_details[].ownership_percent` | number | no | Ownership share, percent. |
| `seller_additional_details[].address_country` | string | no | Address: country. |
| `seller_additional_details[].address_state` | string | no | Address: state or region. |
| `seller_additional_details[].address_city` | string | no | Address: city. |
| `seller_additional_details[].address_street` | string | no | Address: street. |
| `seller_additional_details[].address_building_number` | string | no | Address: building number. |
| `seller_additional_details[].address_zip` | string | no | Address: postal code. |
| `seller_additional_details[].files` | array | no | The person's documents. Only individual file types `90`–`97` are accepted (see [File types](/marketplaces-and-platforms/seller-reference/file-types)); another type returns error `160`. |
| `seller_additional_details[].files[].type` | integer | yes | File type code, `90`–`97`. See [File types](/marketplaces-and-platforms/seller-reference/file-types). |
| `seller_additional_details[].files[].url` | string | no | Public URL of the file. Send `url` or `base64`. |
| `seller_additional_details[].files[].base64` | string | no | The file content, base64-encoded. Send `url` or `base64`. |
| `seller_additional_details[].files[].name` | string | no | File name with extension, for example `id-front.jpg`. |
| `seller_additional_details[].files[].mime_type` | string | no | MIME type of the file, for example `image/jpeg` or `application/pdf`. |
| `language` | string | no | Language of error messages: `he` (default) or `en`. |

### Request example

```json
{
  "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_description": "Handmade ceramics",
  "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"
}
```

## Code samples

### curl

```bash
curl -X POST 'https://sandbox.payme.io/api/create-seller' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "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_description": "Handmade ceramics",
  "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"
}'
```

### Node.js

```javascript
const response = await fetch("https://sandbox.payme.io/api/create-seller", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "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_description": "Handmade ceramics",
    "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"
  }),
});

console.log(await response.text());
```

### Python

```python
import requests

response = requests.post(
    "https://sandbox.payme.io/api/create-seller",
    json={
        "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_description": "Handmade ceramics",
        "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",
    },
)

print(response.text)
```

### PHP

```php
<?php

$body = <<<'BODY'
{
  "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_description": "Handmade ceramics",
  "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"
}
BODY;

$ch = curl_init('https://sandbox.payme.io/api/create-seller');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => $body,
]);

$response = curl_exec($ch);
curl_close($ch);

echo $response;
```

## Responses

### 200 — OK (success)

| Field | Type | Description |
| --- | --- | --- |
| `status_code` | integer | `0` on success. |
| `session` | string | PayMe session ID. |
| `seller_payme_id` | string | The new seller's MPL. Use it on every call for this seller and keep it on your server. |
| `seller_payme_secret` | string | Not a credential: a random value that PayMe does not store or check. Ignore it (see [Authentication](/payments/getting-started/authentication)). |
| `seller_public_key` | object | The seller's public key, for browser code such as Hosted Fields. |
| `seller_public_key.uuid` | string | The public key. |
| `seller_public_key.description` | string | Name of the key. |
| `seller_public_key.is_active` | boolean | `true` when the key is active. |
| `seller_id` | string | Your own ID for the seller, as you sent it. |
| `seller_dashboard_signup_link` | string | Link where the seller sets a password and finishes onboarding. Send it to the seller. Its host depends on your partner account and may differ from the API host, so use it as returned and don't build it yourself. |

```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>"
}
```

### 500 — Error, for example error `150`: the email address is already used by another of your sellers (error)

| Field | Type | Description |
| --- | --- | --- |
| `status_code` | integer | `1` on failure. |
| `status_error_code` | integer | PayMe error code. See [Errors](/payments/getting-started/errors). |
| `status_error_details` | string | Error message, in the request's `language`. |
| `status_additional_info` | string | Extra detail, such as the name of the missing or invalid field. Can be `null`. |
| `session` | string | PayMe session ID. Quote it when you contact support. |

```json
{
  "status_code": 1,
  "status_error_details": "Email is already in use",
  "status_additional_info": null,
  "status_error_code": 150,
  "session": "a1B2c3D4"
}
```

### 429 — Too many requests (error `998`) (error)

| Field | Type | Description |
| --- | --- | --- |
| `status_code` | integer | `1` on failure. |
| `status_error_code` | integer | PayMe error code. See [Errors](/payments/getting-started/errors). |
| `status_error_details` | string | Error message, in the request's `language`. |
| `status_additional_info` | string | Extra detail, such as the name of the missing or invalid field. Can be `null`. |
| `session` | string | PayMe session ID. Quote it when you contact support. |

```json
{
  "status_code": 1,
  "status_error_details": "Operation is not permitted",
  "status_additional_info": "Too Many Attempts.",
  "status_error_code": 998,
  "session": "a1B2c3D4"
}
```