Onboard a seller, from creation to first payout

Prerequisites

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

Related

• Create sellers
• Create a seller
• Upload seller files
• File types
• List sellers
• Update a seller
• Withdrawals
• Platform fees
• Start here: build a platform or marketplace on PayMe
• 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.

The lifecycle at a glance

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 (error 114), business field codes on List business fields (error 110), bank codes on 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.

2. Create the seller

Call create-seller from your server:

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:

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

3. Upload the documents

PayMe approves a seller only after it has checked the seller's documents. Use the codes on File types:

There are three ways to send them:

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

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

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.

• 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 with the seller's MPL:

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

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

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 and Accept 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 lists the services installed on the seller. Service types are on 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, and the fee rules on 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:

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:

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

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