# Start here: build a platform or marketplace on PayMe

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

## Prerequisites

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

## Related

- [Onboard a seller, from creation to first payout](/marketplaces-and-platforms/seller-onboarding/onboard-a-seller)
- [Create sellers](/marketplaces-and-platforms/seller-onboarding/create-seller)
- [Platform fees](/marketplaces-and-platforms/fees-and-payouts/platform-fees)
- [Withdrawals](/marketplaces-and-platforms/fees-and-payouts/withdrawals)
- [Reporting across your sellers](/marketplaces-and-platforms/reporting/reporting-across-your-sellers)
- [Authentication](/payments/getting-started/authentication)
- [Callbacks](/payments/getting-started/callbacks)
- [Get API access and go live: from sandbox to production](/payments/getting-started/go-live)

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

```text
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
```

| Term | What it is |
|---|---|
| Partner | You. You hold `payme_client_key` and its client password, issued by PayMe Partners (<partners@payme.io>). PayMe also keeps settings for your whole partner account. |
| Seller | Each business on your platform. It has its own `seller_payme_id` (MPL), public key, balance and bank account. |
| Sale | Always belongs to one seller. The buyer pays the seller. |
| Platform fee | `market_fee`: a percent of each sale that PayMe collects for you from the seller, on top of PayMe's own fees. By default it is transferred to you once a month. |
| Withdrawal | Moves a seller's released balance to its bank account, once PayMe has approved the seller. |

## Your credentials and your sellers'

| You want to | Send | Notes |
|---|---|---|
| Create a seller | `payme_client_key` | Partner-only: [create-seller](/payments/merchants-management/post-create-seller) returns the seller's MPL |
| Update a seller or upload its documents | `payme_client_key` and the seller's `seller_payme_id`, or your `seller_id` for it | Partner-only: [update-seller](/payments/merchants-management/post-update-seller), [upload-seller-files](/payments/merchants-management/post-upload-seller-files) |
| Read or enable a seller's services | `payme_client_key` and the seller's `seller_payme_id` | Partner-only: [get-vas-seller](/payments/merchants-management/post-get-vas-seller), `vas-enable` |
| Request a seller's withdrawal | `payme_client_key` and the seller's `seller_payme_id` | [withdraw-balance](/payments/merchants-management/post-withdraw-balance) |
| Create a sale for a seller | The seller's `seller_payme_id` in the JSON body. You can add `payme_client_key`. | Or send your `seller_id` for the seller together with `payme_client_key`. See [generate-sale](/payments/hosted-payment-page/post-generate-sale). |
| Refund a seller's sale | The seller's `seller_payme_id`. You can add `payme_client_key`. | See [refund-sale](/payments/post-sale-actions/post-refund-sale). |
| Report across your sellers | `payme_client_key` alone covers all your sellers. Add `seller_payme_id`, one MPL or an array of up to 100, to narrow it. | `get-sales`, `get-transactions`, `get-sellers`, `get-subscriptions`, `get-withdrawals`. See [Reporting across your sellers](/marketplaces-and-platforms/reporting/reporting-across-your-sellers). |
| Run Hosted Fields, Apple Pay or Google Pay in the browser | The seller's public key | From `seller_public_key` on create-seller or the `seller-create` callback, or from [List a seller's public keys](/payments/merchants-management/get-sellers-mpl-public-keys). |

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](/payments/getting-started/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](/payments/tokenization/post-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](/payments/getting-started/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](/marketplaces-and-platforms/seller-onboarding/onboard-a-seller) and [Create sellers](/marketplaces-and-platforms/seller-onboarding/create-seller).
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](/accepting-payments/payment-methods/apple-pay) and [Accept Google Pay](/accepting-payments/payment-methods/google-pay). Check what a seller has with [get-vas-seller](/payments/merchants-management/post-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](/marketplaces-and-platforms/fees-and-payouts/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](/payments/getting-started/callbacks).
5. **Pay your sellers out.** See [Withdrawals](/marketplaces-and-platforms/fees-and-payouts/withdrawals).
6. **Report and reconcile.** See [Reporting across your sellers](/marketplaces-and-platforms/reporting/reporting-across-your-sellers) and [Reconcile sales and withdrawals](/accepting-payments/reporting/reconcile-sales-and-withdrawals).

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

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

| Setting | What it does |
|---|---|
| Default sale callback URL | Receives the callbacks of a sale created without `sale_callback_url`. If your account has no dedicated sale callback URL, the default callback URL is used. |
| Default callback URL | Receives the seller callbacks (`seller-create`, `seller-update`, `seller-approve`) and `withdrawal-complete`, and the callbacks of a subscription created without `sub_callback_url`. Without it, PayMe sends no seller callbacks. |
| Default return URL | Where the buyer goes after paying a sale created without `sale_return_url`. |
| Required seller fields | Which create-seller fields are required for your sellers. A missing one returns error `19`. |
| Withdrawal plan | The plan each new seller starts on: manual or automatic. No API field changes it. |
| Sale price range | The default `sale_price` range is `500`–`4000000` minor units. A different range set for you applies to all your sellers. |
| Rate limit | Payment calls share a per-seller limit. A limit set for you applies to each of your sellers separately. See [Rate limits](/payments/getting-started/idempotency-and-retries#rate-limits). |

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](/payments/getting-started/test-cards-and-payment-methods#creating-test-sellers-partners).
- 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](/payments/getting-started/test-cards-and-payment-methods).

When you are ready for production, follow [Get API access and go live](/payments/getting-started/go-live).