# 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`, or header `PayMe-Merchant-Key` | **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"). 

Partner-only endpoints documented with `payme_client_key` include `create-seller`, `update-seller`, `upload-seller-files`, `withdraw-balance`, `get-vas-seller`, `vas-enable`, `vas-disable`, POS `authenticate` and `pair`, and the query APIs `get-sellers`, `get-subscriptions`, `get-withdrawals` and `funds-transfer`. 

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`, B2B `payment-contracts` |
| `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), `POST /get-transaction-data` |
| `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. 

> ⚠ TO CONFIRM: Where in the merchant dashboard does a merchant find its public key? [Q9]

## Getting credentials

- **Payments API:** not yet documented — see below.
- **Keep API:** you receive a `Client ID` and `Client Secret` from your Account Manager. 

> ⚠ TO CONFIRM: How does a developer get sandbox credentials (seller_payme_id/MPL, payme_client_key, public key) — self-service sign-up, an account manager, or an email to support? [Q5]

> ⚠ TO CONFIRM: Sandbox and production credentials are most likely fully separate — each environment generates its own keys, so a sandbox key should be rejected by `live.payme.io` and vice versa. Please confirm the environments share no credentials. [Q10]

## Keep API: OAuth 2.0 client credentials

1. `POST /oauth2/token` with `application/x-www-form-urlencoded` body: `grant_type=client_credentials`, `client_id`, `client_secret`, optional `scope` (`partner-api` or `seller-api`).
2. The response has `access_token`, `refresh_token`, `expires_in`, `refresh_expires_in`, `token_type`, `scope`.
3. Send `Authorization: Bearer <access_token>` on every request.
4. Refresh with `grant_type=refresh_token` and the `refresh_token`.

Access tokens are short-lived ("typically 1 hour"); refresh tokens last "typically 30 days". All requests must use HTTPS; plain HTTP and unauthenticated calls fail. 

## Products & Customers API: JWT

1. `POST /auth/token` with `{"mpl": "<seller MPL>", "key": "<client key>"}` returns `access_token` and `refresh_token`.
2. Send `Authorization: Bearer <ACCESS_TOKEN>` on product and customer calls.
3. `POST /auth/refresh` with `refresh_token` in the body and headers `PayMe-Partner-Key` and `PayMe-Merchant-Key` returns a new `access_token` and `expires_in` (seconds).



> ⚠ TO CONFIRM: In Products & Customers `POST /auth/token`, is `key` the same value as `payme_client_key`? How long is the access token valid? [Q12]

## Keeping credentials secret

- Keep `seller_payme_id`, `payme_client_key`, the client password 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, encrypted, and rotate credentials periodically. 

### If a key leaks

Contact PayMe support. PayMe can rotate a partner key or a seller ID without downtime — the old and new values both work until the switch — and can block a partner or deactivate a public key. There is no self-service endpoint for this.