Authentication

The Payments API does not use an Authorization header. You identify yourself with keys inside the JSON request body (and, on some endpoints, in custom headers). Always send Content-Type: application/json.

The credentials at a glance

Credential	Who has it	What it does	Where it goes	Keep it
`seller_payme_id` (the MPL)	Every seller (merchant)	Identifies the seller and, on its own, authenticates most seller-level calls: creating sales, refunding, querying sales, updating the seller.	JSON body field `seller_payme_id` (required in the body on `generate-sale`), or header `PayMe-Merchant-Key` on the endpoints listed under Header-based endpoints	Secret — server-side only
`payme_client_key`	Partners (platforms and marketplaces) only	The partner key. Needed for partner-level calls such as creating sellers and querying across sellers.	JSON body field `payme_client_key`, or header `PayMe-Partner-Key`	Secret — server-side only
Public key	Every seller; one per seller per environment	Designed for browser code: tokenizing cards (Hosted Fields), Apple Pay and Google Pay flows, and reading a filtered list of the seller's transactions.	Header `PayMe-Public-Key`; first argument of `PayMe.create(apiKey, …)`	May be exposed in the browser — but note it can read transactions

Example MPL format: MPLDEMO-MPLDEMO-MPLDEMO-1234567.

seller_payme_secret is not a credential. create-seller returns it, but it is a random value that PayMe never stores or checks. Ignore it.

Merchants and partners

A merchant (a single seller) authenticates with seller_payme_id. It can call refund-sale with seller_payme_id alone — PayMe finds the partner from the seller.
A partner (a platform managing many sellers) also holds payme_client_key, sent in the body or the PayMe-Partner-Key header. If a partner sends both keys, the seller must belong to that partner; otherwise the request fails with error 20 ("Merchant-Seller inconsistency"). A partner can also identify the seller by the seller_id it set when creating the seller, together with payme_client_key.

Partner-only endpoints documented with payme_client_key include create-seller, update-seller, upload-seller-files, get-vas-seller, vas-enable, vas-disable, and POS authenticate and pair. withdraw-balance takes either a partner's payme_client_key with the seller's seller_payme_id, or the seller's own seller_payme_id.

The query APIs get-sales, get-subscriptions, get-sellers and get-withdrawals are not partner-only. A partner sends payme_client_key (or the PayMe-Partner-Key header). A seller without a partner key sends seller_payme_id in the JSON body; results are limited to that seller.

merchant_key and merchant_password do not exist on a seller account: they are partner-level credentials. A seller that puts its own MPL in payme_client_key gets HTTP 500 with code 200 "Merchant was not found": remove the field and send seller_payme_id alone.

Error codes you may see while setting up keys: 1 — no key sent at all; 200 — the payme_client_key matches no partner; 201 — the partner is inactive; 251 — the seller_payme_id matches no seller; 163 — the seller is inactive.

Header-based endpoints

Header	Carries	Used on (examples)
`PayMe-Merchant-Key`	The seller's MPL	`GET /buyers/{buyer_guid}`, `GET /documents`, 3D Secure hash resolution, `PATCH /subscriptions/{sub_payme_id}/resume`
`PayMe-Partner-Key`	The partner's client key	`GET /sellers/{seller_payme_id}/public-keys`, `GET /banks/{country_iso_code}`
`PayMe-Public-Key`	The seller's public key	`POST /sales/{payme_sale_id}/3ds` (called from the browser)
`PayMe-Signature`	A static value PayMe provides on request	`/sellers/{mpl_key}/individuals`, `/sellers/{mpl_key}/mids`

PayMe-Signature is not computed per request: it is a static secret value that PayMe gives you on request. Keep it secret and never paste it into code samples or tickets.

The public key

Each seller has its own public key, issued separately in each environment. A partner can look it up with GET /sellers/{seller_payme_id}/public-keys (header PayMe-Partner-Key), and create-seller returns it as seller_public_key.

The public key is meant for browser code, but it can read a filtered list of the seller's transactions. Use it only where you need it in the browser.

In the merchant dashboard, the public key, the MPL and the Hosted Fields JSAPI credentials are on Admin → API & Integration (API ואינטגרציה). The Hosted Fields public key is in the section Hosted Fields JSAPI Credentials on that page, and it differs between the sandbox and production. PayMe.create takes the public key only: never put the MPL (seller_payme_id) in browser code. GET /sellers/{seller_payme_id}/public-keys is partner-only.

Getting credentials

Payments API — sandbox: if you already have a PayMe account, open the test account from the dashboard: click your name at the top → Switch to test account → Create test account. A developer with no account registers at https://paid.co.il → "הרשמה" (Register), then opens the test account from the dashboard as above. The "התנסות" (Try it out) button opens a shared demo, not your own sandbox: it has no keys of your own. The sandbox is free and asks for no signatures.
Where the keys are: Admin → API & Integration shows the MPL (seller_payme_id, with a test/production toggle), the public key, both base URLs and the Hosted Fields JSAPI credentials. If the page is missing, install the API service from the dashboard app store (חנות אפליקציות) first; depending on your account it may carry a charge.
Payments API — production: the same page in production mode. Sandbox and production are separate accounts with separate credentials: a sandbox key is rejected by live.payme.io and vice versa.
Partner key (payme_client_key): issued to partners by PayMe Partners (partners@payme.io). It is never given to individual sellers, even for refunds — a seller refunds with seller_payme_id alone.
Questions about credentials: partners@payme.io.

Other APIs

B2B Payments uses the Payments API keys: Hosts and authentication.
Keep uses OAuth 2.0 client credentials: Authorization Flow.
Products & Customers uses a JWT: Hosts, Authentication and Errors.

Keeping credentials secret

Keep seller_payme_id, payme_client_key, the client password (called payme_merchant_secret in older PayMe documentation; see Callbacks) and PayMe-Signature on your server. Never put them in browser or mobile code, logs, or public repositories such as GitHub.
Only the public key belongs in browser code. The 3D Secure guide makes the same split: the browser call uses the public key, the hash-resolution call "should be called from your backend".
Store tokens securely and encrypted.

If a key leaks

There is no self-service key regeneration or rotation. If you believe a key has leaked, contact PayMe support immediately.