Create a seller

Credentials

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.

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.

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.

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. 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, or get the live list from List business fields. An unknown or inactive code returns error 110.
seller_inc integer yes Incorporation type, see Seller incorporation types. 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.
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.
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 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); another type returns error 160.
seller_additional_details[].files[].type integer yes File type code, 90–97. See 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

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

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

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

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

$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).
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. 
{
  "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.
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. 
{
  "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.
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. 
{
  "status_code": 1,
  "status_error_details": "Operation is not permitted",
  "status_additional_info": "Too Many Attempts.",
  "status_error_code": 998,
  "session": "a1B2c3D4"
}