Start here: build a platform or marketplace on PayMe

Prerequisites

• Partner credentials (payme_client_key and client password) from PayMe Partners

Related

• Onboard a seller, from creation to first payout
• Create sellers
• Platform fees
• Withdrawals
• Reporting across your sellers
• Authentication
• Callbacks
• Get API access and go live: from sandbox to production

As a platform or marketplace, you are a PayMe partner. You onboard your sellers under your partner account, take payments for them, can collect a platform fee on each sale, and PayMe pays each seller out to its own bank account. This page maps the whole flow and links to the guide for each step.

How the model works

Partner (you): payme_client_key + client password
 ├─ Seller A: seller_payme_id (MPL), public key, balance, bank account
 ├─ Seller B: seller_payme_id (MPL), public key, balance, bank account
 └─ …

Buyer pays a sale of Seller A
 └─ PayMe ─┬─ Seller A's balance (after PayMe's fees and your market_fee) ─▶ withdrawal to A's bank account
           └─ your platform fee (market_fee) ─▶ transferred to you

Your credentials and your sellers'

The rules:

• When you send payme_client_key with a seller_payme_id, the seller must be one of yours. Otherwise the call fails with error 20.
• seller_id is your own ID for a seller, set on create-seller. It must be unique among your sellers (error 108), and it identifies the seller only together with payme_client_key.
• Keep payme_client_key, the client password and every MPL on your server. Only the public key goes into browser or mobile code.
• Ignore seller_payme_secret on create-seller: it isn't a credential.
• Verify payme_signature on sale callbacks with your payme_client_key and client password. Seller and withdrawal callbacks carry no signature: re-read them with get-sellers or get-withdrawals. See Callbacks.
• Saved cards: a token captured without "buyer_is_private": true belongs to your partner account, and any of your sellers can charge it. Reading it with get-buyer-key and a seller's MPL returns error 603: send payme_client_key instead. Capture with "buyer_is_private": true to keep a token with one seller.

More on each credential: Authentication.

The integration, step by step

1. Onboard your sellers. Create each seller, upload its documents and wait for PayMe's approval. See Onboard a seller, from creation to first payout and Create sellers.
2. Turn on payment methods. A seller installs Apple Pay, Google Pay or Bit from the dashboard app store (חנות אפליקציות), or you enable it with vas-enable: see Accept Apple Pay and Accept Google Pay. Check what a seller has with get-vas-seller. 3D Secure is enabled on the account by PayMe.
3. Take payments, with your fee. Create each sale with the seller's MPL, and send market_fee to override the seller's default fee. See Platform fees.
4. Handle callbacks. Sale callbacks go to the sale's sale_callback_url. Seller and withdrawal callbacks go to your partner account's default callback URL. See Callbacks.
5. Pay your sellers out. See Withdrawals.
6. Report and reconcile. See Reporting across your sellers and Reconcile sales and withdrawals.

A sale for one of your sellers, with a 2.5% platform fee:

curl -X POST https://sandbox.payme.io/api/generate-sale \
  -H 'Content-Type: application/json' \
  -d '{
    "payme_client_key": "XXXXXXXX",
    "seller_payme_id": "MPLDEMO-MPLDEMO-MPLDEMO-1234567",
    "sale_price": 10000,
    "currency": "ILS",
    "product_name": "Test order",
    "transaction_id": "order-1001",
    "sale_callback_url": "https://your-server.example.com/payme/callback",
    "sale_return_url": "https://your-site.example.com/payment/success",
    "market_fee": 2.5,
    "language": "en"
  }'

On this sale of 10000 (100.00), your fee is 250 (2.50).

Settings PayMe keeps for your partner account

These settings apply to every seller under your partner account. PayMe sets them; to set or change one, contact PayMe Partners (partners@payme.io).

A default URL is shared by all your sellers. To route one seller's callbacks elsewhere, send sale_callback_url on each of its sales: a seller has no dashboard setting for it.

Know these before you build

• Payments start before approval; payouts don't. A new seller can take payments at once. Withdrawals wait until PayMe approves the seller (error 109).
• A seller's default fee is set once. market_fee on create-seller sets the seller's default. Update-seller can't change it: contact PayMe Partners, and send market_fee on each sale until it changes.
• Sellers paid directly by the card companies ignore the market_fee sent on a sale (the seller's default applies), and can't request withdrawals (error 908).
• Create-seller is rate limited to 5 calls per minute per IP (error 998).

Test as a partner in the sandbox

• Create test sellers with the values on Creating test sellers.
• Sellers created on the sandbox test account start on an automatic withdrawal plan, so ask PayMe to set up a test seller before you test a withdrawal.
• Pay with the test cards.

When you are ready for production, follow Get API access and go live.