# Payments
## Getting Started
- [Start Here](https://docs-staging.payme.io/payments/getting-started/start-here): Reading order for developers and AI coding agents integrating the PayMe Payments API: 1) PayMe at a glance, 2) Authentication (seller_payme_id/MPL, payme_client_key, public key), 3) Environments (sandbox.payme.io vs live.payme.io), 4) Quickstart (generate-sale, pay, callback, refund-sale), 5) Callbacks (form-encoded POST, notify_type, payme_signature). Then Errors and Idempotency & Retries.
# Start Here
Read these five pages, in this order, before you write integration code.
| # | Page | What you learn |
|---|------|----------------|
| 1 | [PayMe at a glance](https://docs-staging.payme.io/payments/getting-started/payme-at-a-glance) | Products, payment methods, currencies, environments, compliance and support contact — in one page. |
| 2 | [Authentication](https://docs-staging.payme.io/payments/getting-started/authentication) | Which credential goes where: `seller_payme_id` (MPL), `payme_client_key`, the public key, and the OAuth/JWT tokens used by the Keep and Products & Customers APIs. |
| 3 | [Environments](https://docs-staging.payme.io/payments/getting-started/environments) | Sandbox vs production base URLs, test cards, and the hosts you will see in `sale_url`. |
| 4 | [Quickstart](https://docs-staging.payme.io/payments/getting-started/quickstart) | One complete sale in the sandbox with `curl`: create a sale, pay it, receive the callback, refund it. |
| 5 | [Callbacks](https://docs-staging.payme.io/payments/getting-started/callbacks) | How PayMe notifies your server, what the payload contains, and how to handle it. |
After those, read [Errors](https://docs-staging.payme.io/payments/getting-started/errors) and [Idempotency and retries](https://docs-staging.payme.io/payments/getting-started/idempotency-and-retries) before going live.
## Three facts that trip up most integrations
1. **Amounts are in minor units.** A price of 50.75 is sent as `5075`, and the minimum `sale_price` is `500`.
2. **Callbacks are not JSON.** PayMe sends a `POST` with `x-www-form-urlencoded` body to your callback URL, even though your requests to PayMe are JSON.
3. **Error messages default to Hebrew.** Send `"language": "en"` to get English error messages.
> ⚠ 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]
- [PayMe at a Glance](https://docs-staging.payme.io/payments/getting-started/payme-at-a-glance): PayMe is a payments provider whose Payments API lets platforms and merchants accept payments through a hosted payment page, hosted fields (JSAPI) or a direct API, with tokenization, subscriptions, refunds, authorization and capture, 3D Secure, invoices and point-of-sale. Other APIs: B2B Payments, Keep (accounting) and Products & Customers. Payment methods include cards, Bit, Apple Pay, Google Pay, PayPal, bank transfer, SEPA, BACS and Israeli direct debit. Sandbox: sandbox.payme.io/api; production: live.payme.io/api.
# PayMe at a Glance
This page lists only what the PayMe documentation states. Gaps are marked **TO CONFIRM**.
## What PayMe offers
PayMe's Payments API is "designed to allow platforms to offer a full payment solution as part of their product." With it you can:
- create and manage merchants on your platform;
- accept credit-card payments and other payment methods;
- create recurring payments (subscriptions);
- use hosted (secured) payment pages;
- tokenize cards for delayed and future payments;
- charge a platform (market) fee on each transaction;
- query sellers, transactions, subscriptions and withdrawals.
### APIs in this documentation
| API | What it covers |
|-----|----------------|
| [Payments](https://docs-staging.payme.io/payments/introduction/getting-started) | Sales (hosted payment page, hosted fields, direct API), Apple Pay, Google Pay, Israeli direct debit, tokenization, subscriptions, refunds / capture / void, 3D Secure (including a standalone 3D Secure service), invoices, point-of-sale devices, merchant management for partners, and query APIs. |
| [B2B Payments](https://docs-staging.payme.io/b2b-payments/contracts/post-user) | Payment contracts (send a payment or a payment request between businesses) and transfers between wallets. |
| [Keep](https://docs-staging.payme.io/keep/partner-authorization/prerequisites) | APIs for PayMe's accounting product: sellers, income documents (invoices, receipts), expenses, tax and VAT. |
| [Products and Customers](https://docs-staging.payme.io/products-and-customers/authentication/post-auth-token) | Create, list, update and delete products and customers. |
Mobile: an iOS SDK is available.
## Integration options
| Option | In one line |
|--------|-------------|
| Hosted Payment Page | The buyer pays on PayMe's secure page (`sale_url`, shown as an IFRAME or redirect); PayMe carries the PCI DSS burden. |
| Hosted Fields (JSAPI) | Payment fields embedded in your page with PayMe's JavaScript library. |
| Direct API | Your server sends card details to PayMe; you must meet PCI DSS level 1 yourself. |
## Payment methods
The `sale_payment_method` values documented are:
`credit-card`, `bank-transfer`, `paypal`, `alipay-qr`, `alipay-online`, `funds-transfer`, `cash`, `cheque`, `echeck`, `bit`, `bacs`, `sepa`, `apple-pay`, `il-direct-debit`, `verifone-prepaid`, `google-pay`. Use `multi` to let the buyer choose on one checkout page.
Card networks named in the docs: Visa, Mastercard, American Express, Diners, Discover, JCB and Isracard (test cards). Google Pay supports Visa, Mastercard, American Express, Discover and JCB.
Installments: 1–12 fixed, or let the buyer choose up to 3, 6, 9 or 12 (`103`, `106`, `109`, `112`).
## Currencies
Sale currency is a 3-letter ISO 4217 code. Supported currencies, subject to your account configuration:
ILS, USD, EUR, GBP, TRY, CHF, SEK, NOK, CAD, ZAR, JPY, AUD, AED, ARS, BHD, BRL, CNY, INR, KRW, KWD, KZT, MXN, NGN, PLN, RON, RUB, SAR, UAH, PHP, VND, HKD.
- Each account has its own allowed set; any other currency returns error `252`.
- ILS only: Israeli direct debit, Bit, and any sale with more than one installment.
- Sandbox test cards accept ILS, USD and EUR (the local Israeli test card accepts ILS only).
- Keep income documents: "currently only ILS supported".
## Countries
The documentation is Israel-centred: Israeli bank codes, Israeli business incorporation types, Israeli social ID fields, and Israeli direct debit. Test data also exists for SEPA and BACS accounts. The payment page collects a ZIP code for cards issued in the USA, Canada and the United Kingdom.
> ⚠ TO CONFIRM: In which countries can merchants be onboarded, and from which countries can buyers pay? [Q45]
## Amounts and limits
- Amounts are in minor units (50.75 → `5075`).
- Default `sale_price` range: `500`–`4000000` minor units, the same in every currency and payment method (so `500` is 5.00 ILS or USD but 500 JPY). PayMe can set different limits per account; out of range returns error `352`. Token sales use a fixed price of `100`.
- An authorization (J5) reserves funds for up to 168 hours; capture is allowed once.
- Rate limit: `generate-sale`, `pay-sale` and `capture-sale` share a per-seller limit, by default 100 requests per 10 seconds (may differ per account); over the limit returns HTTP 429. See [Idempotency and retries](https://docs-staging.payme.io/payments/getting-started/idempotency-and-retries).
> ⚠ TO CONFIRM: Is 100 requests per 10 seconds per seller also the default in **production**? [Q28]
## Environments
| Environment | Base URL |
|-------------|----------|
| Sandbox | `https://sandbox.payme.io/api/` |
| Production | `https://live.payme.io/api/` |
Details: [Environments](https://docs-staging.payme.io/payments/getting-started/environments).
## Compliance
- With the Hosted Payment Page, responsibility for PCI DSS lies with PayMe.
- With the Direct API, the merchant must meet PCI DSS level 1.
- Tokenization reduces the scope of PCI DSS requirements for recurring payments.
- 3D Secure is supported, including as a standalone service.
> ⚠ TO CONFIRM: What is PayMe's own PCI DSS certification level, and which licence or regulator applies to PayMe? [Q46]
## Contact
- General contact form:
- Support email (given for adding Google Pay card networks): `support@payme.io`
- Keep API keys come from your Account Manager.
> ⚠ TO CONFIRM: What is the official developer-support channel (email, form, hours), and is `support@payme.io` the right address for integration questions? [Q47]
## Machine-readable docs
Every page is available as Markdown by appending `.md` to its URL; each API project publishes an OpenAPI file at `//openapi.json`; the site index for AI agents is `/llms.txt`.
- [Authentication](https://docs-staging.payme.io/payments/getting-started/authentication): Payments API requests carry credentials in the JSON body, not an Authorization header. seller_payme_id (the MPL) identifies and authenticates the seller on its own, so keep it server-side. payme_client_key is the partner (platform) key held only by partners; merchants can call refund-sale without it. The per-seller public key (PayMe-Public-Key) is for browser code. Sandbox and production keys are separate. Keep uses OAuth2 client credentials; Products & Customers uses a JWT from POST /auth/token.
# 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 ` 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": "", "key": ""}` returns `access_token` and `refresh_token`.
2. Send `Authorization: Bearer ` 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.
- [Environments](https://docs-staging.payme.io/payments/getting-started/environments): PayMe has two environments: Sandbox at https://sandbox.payme.io/api/ and Production at https://live.payme.io/api/; each issues its own keys. The B2B Payments API uses the same hosts and /api prefix. sale_url is the environment's base URL plus /sale/generate/; use it exactly as returned. Test only in the sandbox with the documented test cards; decline cards return HTTP 200 with status_code 1 and codes such as 20004 or 21001-21008. Browser scripts load from cdn.paymeservice.com; Hosted Fields uses testMode: true.
# Environments
## Base URLs
| Environment | Base URL |
|-------------|----------|
| Sandbox | `https://sandbox.payme.io/api/` |
| Production | `https://live.payme.io/api/` |
Point every request at the right environment **with that environment's credentials**. Endpoint pages show both URLs.
A full endpoint URL is the base URL plus the path, for example `https://sandbox.payme.io/api/generate-sale` and `https://live.payme.io/api/refund-sale`.
> ⚠ 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]
### Other APIs
- **B2B Payments** uses the same hosts, the same `/api` prefix and the same `payme_client_key` / `seller_payme_id` authentication as the Payments API: payment contracts under `/api/payment-contracts`, wallet transfers under `/api/sales` and `/api/transfer`.
- **Keep:** endpoint pages show full URLs such as `https://sandbox.payme.io/api/partner/api/documents/income` and `https://live.payme.io/api/partner/api/documents/income`. Other Keep paths start with `/oauth2/token`, `/public/...` and `/seller/api/...`.
> ⚠ TO CONFIRM: What are the real sandbox and production base URLs for the Keep API, including the OAuth token endpoint (`/oauth2/token`) and the `/public/...` and `/seller/api/...` paths? [Q40]
> ⚠ TO CONFIRM: What are the real sandbox and production base URLs for the Products & Customers API (`/auth/token`, `/products`, `/customers`)? Is it really `https://sandbox.payme.io/api` / `https://live.payme.io/api`? [Q41]
## Hosts you will see besides the API
### The payment page (`sale_url`)
`generate-sale` returns a `sale_url` — the secured payment page to show the buyer. It is built as the environment's base URL followed by `/sale/generate/`, or `/sale/template/` for template sales.
**Use `sale_url` exactly as returned**; do not build it yourself or hard-code its host.
> ⚠ TO CONFIRM: The `sale_url` host is most likely `sandbox.payme.io` in the sandbox and `live.payme.io` in production; the `preprod.paymeservice.com` host in some documented examples (and in the 3D Secure `postMessage` origin check) appears to be a pre-production host. Please confirm the hosts per environment, so examples and iframe / Content-Security-Policy allow-lists can be corrected. [Q38]
### Browser scripts
PayMe's browser scripts are served from `cdn.paymeservice.com` (for example `//cdn.paymeservice.com/jsapi/v1/payme.min.js`). The Apple Pay and Google Pay guides load `hostedfields.js` from `cdn.paymeservice.com`; the Hosted Fields guide shows `cdn.payme.io/hf/v1/hostedfields.js`.
> ⚠ TO CONFIRM: `cdn.paymeservice.com` is the domain in use, so the Hosted Fields script is most likely `https://cdn.paymeservice.com/hf/v1/hostedfields.js` and `cdn.payme.io` is outdated. Please confirm the exact Hosted Fields path, and whether it is the same for sandbox and production. [Q39]
In browser code, sandbox vs production is chosen with `testMode` (default `false`): `PayMe.create(apiKey, { testMode: true })` for the sandbox. Setting it to `false` sends requests to production.
## Testing in the sandbox
Use test data **only in the sandbox**. Full list: [Test Cards and Payment Methods](https://docs-staging.payme.io/payments/introduction/test-cards-and-payment-methods).
Main test cards (all expire `12/30`, Social ID `008336174`):
| Card number | CVV | Behaviour |
|-------------|-----|-----------|
| `4557430402053431` | `200` | International non-Israeli card; one installment only; ILS, USD, EUR |
| `375516193000090` | `0957` | International Israeli card; multiple installments; ILS, USD, EUR |
| `5326105300985846` | `658` | Local Israeli card; multiple installments; ILS only |
### Cards that force a decline
Outside production these cards always fail. The response is **HTTP 200** with `status_code: 1` and:
| Card number | `status_error_code` | Message (with `language: "en"`) |
|-------------|--------------------|---------------------------------|
| `4000000000000002` | `20004` | Refusal by credit company. Please try a different card |
| `4000000000000051` | `21001` | The card is blocked |
| `4000000000000085` | `21002` | The card is stolen |
| `4000000000000069` | `21004` | The card is expired |
| `4242424242424241` | `21005` | Incorrect card number |
| `4000000000000135` | `21006` | The credit limit has been reached |
| `4000000000000101` | `21007` | CVV/ID is required but was not entered |
| `4000000000000127` | `21008` | Incorrect CVV or ID |
| `4000000000000036` | `20004` | Saving (tokenizing) the card succeeds; charging it later, including with its `buyer_key`, is refused |
### Other sandbox test data
- **Israeli direct debit:** bank `54`, branch `112`, account `2222111` is approved after 60 seconds; branch `113`, account `4444333` is declined after 60 seconds. In the sandbox you only receive bank-authorization statuses 1 or 2.
- **SEPA and BACS:** test account numbers drive the status from `initial` to `completed`, `failed` or `chargeback`.
- **Creating test sellers (partners):** `seller_social_id` `9999999999`, `seller_email` `random@paymeservice.com` (suppresses automatic emails), `seller_bank_code` `54`, any 3-digit branch, any 6-digit account.
### Merchant dashboard
`create-seller` returns a sign-up link to the merchant dashboard in `seller_dashboard_signup_link`.
> ⚠ TO CONFIRM: Each environment most likely has its own merchant dashboard (the partner's white-label dashboard if one is set, otherwise PayMe's default). What is the URL of PayMe's default sandbox dashboard, where a developer can see test sales? [Q43]
- [Quickstart](https://docs-staging.payme.io/payments/getting-started/quickstart): End-to-end sandbox walkthrough. 1) POST https://sandbox.payme.io/api/generate-sale with seller_payme_id, sale_price (minor units, min 500), currency, product_name, transaction_id, sale_callback_url, sale_return_url, language en; response has sale_url and payme_sale_id. 2) Open sale_url and pay with test card 5326105300985846 12/30 CVV 658. 3) PayMe POSTs a form-encoded callback with notify_type sale-complete; reply 200 within 5 s. 4) POST /refund-sale with seller_payme_id, payme_sale_id and optional sale_refund_amount.
# Quickstart
Your first sale in the sandbox: you will create a sale, pay it as a buyer, receive PayMe's callback, and refund it. Every field below comes from the endpoint pages linked in each step.
**You need:**
- a sandbox `seller_payme_id` (MPL) — see [Authentication](https://docs-staging.payme.io/payments/getting-started/authentication). Keep it on your server: on its own it authenticates seller-level calls;
- a public URL that accepts `POST` requests, for the callback. It may not be `localhost` or a private IP address; use HTTPS.
> ⚠ 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]
## Step 1 — Create the sale
Endpoint: [`POST /generate-sale`](https://docs-staging.payme.io/payments/hosted-payment-page/post-generate-sale). No payment happens yet.
```bash
curl -X POST https://sandbox.payme.io/api/generate-sale \
-H 'Content-Type: application/json' \
-d '{
"seller_payme_id": "MPLDEMO-MPLDEMO-MPLDEMO-1234567",
"sale_price": 1000,
"currency": "ILS",
"product_name": "Test order",
"transaction_id": "order-1001",
"installments": "1",
"sale_callback_url": "https://your-server.example.com/payme/callback",
"sale_return_url": "https://your-site.example.com/payment/success",
"language": "en"
}'
```
| Field | Meaning |
|-------|---------|
| `seller_payme_id` | Your MPL. Required. |
| `sale_price` | Price in minor units: `1000` = 10.00. Default allowed range `500`–`4000000`, in every currency (so `500` is 5.00 ILS but 500 JPY). Required. |
| `currency` | 3-letter ISO 4217 code, enabled on your account. Required. |
| `product_name` | Short product description, up to 500 characters. Required. |
| `transaction_id` | Your own order ID, for correlation with PayMe. Optional. |
| `installments` | `1`–`12` fixed, or `103`/`106`/`109`/`112` to let the buyer choose up to 3/6/9/12. |
| `sale_callback_url` | Where PayMe sends the server-to-server callback. Defaults to the merchant's settings. |
| `sale_return_url` | Where the buyer is redirected after paying. Defaults to the merchant's settings. |
| `language` | Payment page and error-message language. If omitted, messages are in Hebrew — always send `"en"` while integrating. |
`sale_price` and `installments` accept a number or a numeric string (`1000` or `"1000"`, `1` or `"1"`). A non-numeric `sale_price` returns error `352`; a non-numeric `installments` returns error `10`. A decimal `sale_price` is rounded to whole minor units.
Successful response (for the request above):
```json
{
"status_code": 0,
"sale_url": "https://preprod.paymeservice.com/sale/generate/XXXXXXXX-XXXXXXXX-XXXXXXXX-XXXXXXXX",
"payme_sale_id": "XXXXXXXX-XXXXXXXX-XXXXXXXX-XXXXXXXX",
"payme_sale_code": 12345678,
"price": 1000,
"transaction_id": "order-1001",
"currency": "ILS"
}
```
- `status_code` `0` means success, `1` means error.
- Save `payme_sale_id` (PayMe's sale ID) next to your `transaction_id`. You need it to refund.
- If `status_code` is `1`, read `status_error_code` and `status_error_details` — see [Errors](https://docs-staging.payme.io/payments/getting-started/errors). Errors usually come back with HTTP 500, so check `status_code`, not the HTTP status.
- PayMe does not de-duplicate `transaction_id`: sending this request twice creates two sales.
## Step 2 — Pay as the buyer
Open `sale_url` in a browser (or an IFRAME). Pay with a sandbox test card, for example:
| Card number | Expiry | CVV | Social ID |
|-------------|--------|-----|-----------|
| `5326105300985846` | `12/30` | `658` | `008336174` |
This is a local Israeli card that accepts ILS only. Other cards, including cards that force a decline, are on [Test Cards and Payment Methods](https://docs-staging.payme.io/payments/introduction/test-cards-and-payment-methods).
You can pre-fill buyer details by appending query parameters to `sale_url`, for example `?first_name=First&last_name=Last&email=test@example.com`. Card fields cannot be pre-filled.
Use `sale_url` exactly as returned.
> ⚠ TO CONFIRM: The `sale_url` host is most likely `sandbox.payme.io` in the sandbox and `live.payme.io` in production; the `preprod.paymeservice.com` host in the response example above appears to be a pre-production host. Please confirm, so the example can be corrected. [Q38]
To try a decline, pay with `4000000000000002`: the result is HTTP 200 with `status_code: 1` and error `20004`. Other decline cards are on [Environments](https://docs-staging.payme.io/payments/getting-started/environments).
After a successful payment the buyer is redirected (`GET`) to your `sale_return_url` with the sale details as query parameters:
```
https://your-site.example.com/payment/success?payme_status=success&payme_signature=75e99dbcb25cdfbe1c62f0b9376f4144&payme_sale_id=XXXXXXXX-XXXXXXXX-XXXXXXXX-XXXXXXXX&payme_transaction_id=XXXXXXXX-XXXXXXXX-XXXXXXXX-XXXXXXXX&price=1000¤cy=ILS&transaction_id=order-1001&is_token_sale=0
```
Use the redirect only to show the buyer a result page. Use the callback (step 3) to update your order.
## Step 3 — Receive the callback
When the sale is paid, PayMe sends a `POST` with an `x-www-form-urlencoded` body to `sale_callback_url`. Key fields:
| Field | Example | Meaning |
|-------|---------|---------|
| `notify_type` | `sale-complete` | What happened. See [Callbacks](https://docs-staging.payme.io/payments/getting-started/callbacks). |
| `status_code` | `0` | `0` success, `1` error |
| `payme_sale_id` | `XXXXXXXX-…` | PayMe's sale ID |
| `transaction_id` | `order-1001` | Your order ID |
| `sale_status` | `completed` | See [Sale Statuses](https://docs-staging.payme.io/marketplaces-and-platforms/lists-statuses/sale-statuses) |
| `price`, `currency` | `1000`, `ILS` | Amount in minor units and currency |
| `payme_signature` | `75e99dbcb25cdfbe1c62f0b9376f4144` | Signature |
To test your handler before you have a sandbox account, send yourself a callback with the documented shape:
```bash
curl -X POST https://your-server.example.com/payme/callback \
-H 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'status_code=0' \
--data-urlencode 'notify_type=sale-complete' \
--data-urlencode 'sale_created=2016-01-01 15:15:15' \
--data-urlencode 'transaction_id=order-1001' \
--data-urlencode 'payme_sale_id=XXXXXXXX-XXXXXXXX-XXXXXXXX-XXXXXXXX' \
--data-urlencode 'payme_sale_code=12345678' \
--data-urlencode 'payme_transaction_id=XXXXXXXX-XXXXXXXX-XXXXXXXX-XXXXXXXX' \
--data-urlencode 'price=1000' \
--data-urlencode 'currency=ILS' \
--data-urlencode 'sale_status=completed' \
--data-urlencode 'installments=1' \
--data-urlencode 'is_token_sale=0' \
--data-urlencode 'payme_signature=75e99dbcb25cdfbe1c62f0b9376f4144'
```
Your handler should:
1. **Reply `200` within 5 seconds.** Any status below 400 counts as delivered; anything else, or a timeout, makes PayMe retry — up to 3 attempts in total, then the callback is dropped.
2. **Ignore repeats** — de-duplicate on `notify_type` + `payme_sale_id` + `payme_transaction_id`.
3. **Verify `payme_signature`** — the recipe is on [Callbacks](https://docs-staging.payme.io/payments/getting-started/callbacks) (section "Verifying a callback").
4. **Confirm the sale before fulfilling** — treat the callback's status and amount as a notification, not proof of payment: call [`POST /get-sales`](https://docs-staging.payme.io/payments/query-apis/post-get-sales) with `sale_payme_id` and check `sale_status` and `sale_price`.
## Step 4 — Refund the sale
Endpoint: [`POST /refund-sale`](https://docs-staging.payme.io/payments/post-sale-actions/post-refund-sale). Omit `sale_refund_amount` for a full refund; send it for a partial refund (minimum `500`). You can refund several times as long as the total does not exceed the sale amount.
```bash
curl -X POST https://sandbox.payme.io/api/refund-sale \
-H 'Content-Type: application/json' \
-d '{
"seller_payme_id": "MPLDEMO-MPLDEMO-MPLDEMO-1234567",
"payme_sale_id": "SALEDEMO-XXXXXXXX-XXXXXXXX-XXXXXXXX",
"sale_refund_amount": 500,
"language": "en"
}'
```
`payme_client_key` is not needed here: a merchant can refund with `seller_payme_id` alone. Partners (platforms) may also send their `payme_client_key`, in which case the seller must belong to that partner.
Successful response (abridged):
```json
{
"status_code": 0,
"status_error_code": 0,
"payme_status": "success",
"sale_status": "partial-refund",
"sale_refund_buffer": 500,
"payme_transaction_total": 500,
"payme_transaction_id": "TRANDEMO-XXXXXXXX-XXXXXXXX-XXXXXXXX",
"payme_signature": "b71e**************ca5a"
}
```
PayMe also sends a callback with `notify_type` `refund` to the callback URL; its `payme_transaction_total` is the amount of this refund and `sale_refund_buffer` the amount still refundable.
**Do not blindly retry a refund that timed out**: a repeated partial refund runs again and refunds a second time. Read [Idempotency and retries](https://docs-staging.payme.io/payments/getting-started/idempotency-and-retries) first.
## Next steps
- [Callbacks](https://docs-staging.payme.io/payments/getting-started/callbacks) — every notification type and how to handle it.
- [Errors](https://docs-staging.payme.io/payments/getting-started/errors) — error codes and messages.
- To charge a saved card later, see [Create Payment With Buyer Key (Token)](https://docs-staging.payme.io/marketplaces-and-platforms/payments/create-payment-with-buyer-key-token); to authorize now and capture later, see [Capture sale](https://docs-staging.payme.io/marketplaces-and-platforms/payments/capture-sale).
- [Callbacks](https://docs-staging.payme.io/payments/getting-started/callbacks): PayMe callbacks are form-encoded POSTs to sale_callback_url (or the default callback URL). Any HTTP status below 400 counts as delivered; each attempt times out after 5 s; up to 3 attempts over about 2 minutes, then dropped. Duplicates happen and ordering is not guaranteed: de-duplicate on notify_type + payme_sale_id + payme_transaction_id. payme_signature = lowercase hex MD5 of payme_client_key + client password + payme_transaction_id + payme_sale_id. Before fulfilling an order, confirm the sale's status and amount with POST /get-sales.
# Callbacks
A callback (PayMe also calls it an "IPN") is a request PayMe's server sends to yours when something happens to a sale, a subscription or a seller.
**In short:** reply quickly with HTTP 200, expect repeats and out-of-order delivery, verify `payme_signature`, and confirm the sale's status and amount with [`POST /get-sales`](https://docs-staging.payme.io/payments/query-apis/post-get-sales) before you fulfil an order.
## Format
- Method and encoding: `POST` with an `x-www-form-urlencoded` body — not JSON.
- Destination: the `sale_callback_url` you sent in the request; if you did not send one, the merchant's default Callback URL. The same sale event can also go to the partner's callback URL.
- The `language` field of the request sets the language of the callback.
### Callback URL rules
- `http://` and `https://` are both accepted. Use HTTPS.
- Non-standard ports are allowed (for example `:8443`).
- Rejected: `localhost`, private and loopback IP addresses, and (in production) hosts without a valid top-level domain.
The callback is separate from the **return URL** redirect. The return URL is a browser `GET` that takes the buyer to your result page; the callback is server-to-server.
## Sale notification types (`notify_type`)
| `notify_type` | Meaning |
|---------------|---------|
| `sale-complete` | The sale was paid successfully |
| `sale-authorized` | The sale was authorized successfully |
| `refund` | The sale was refunded — full refund, partial refund, or void of an authorization |
| `sale-failure` | A payment attempt failed |
| `sale-chargeback` | The sale was charged back |
| `sale-chargeback-refund` | The chargeback was reverted |
- **`sale-failure` is sent once per failed attempt**, not once per sale. A buyer can retry on the payment page; each failure sends another `sale-failure` with a different `payme_transaction_id`. They stop once the sale completes.
- **Refund callbacks:** `payme_transaction_total` is the amount of this refund, `price` is the original sale price, `sale_refund_buffer` is the amount still refundable, and `payme_transaction_id` / `payme_signature` refer to the refund transaction.
> ⚠ TO CONFIRM: The exact `sale_status` string after a partial refund — the existing docs show `partial-refund`, while PayMe's API code suggests `partially-refunded`. Which is it (and the matching void strings)? [Q37]
## Sale callback payload
| Field | Example | Description |
|-------|---------|-------------|
| `status_code` | `0` | `0` success, `1` error |
| `status_error_code` | | In case of an error, PayMe's error code |
| `status_error_details` | | In case of an error, the error message |
| `notify_type` | `sale-complete` | Notification type (table above) |
| `sale_created` | `2016-01-01 15:15:15` | Sale creation time |
| `transaction_id` | `12345` | Your order ID |
| `payme_sale_id` | `XXXXXXXX-XXXXXXXX-XXXXXXXX-XXXXXXXX` | PayMe's sale ID |
| `payme_sale_code` | `12345678` | Sale code, for display only |
| `payme_transaction_id` | `XXXXXXXX-XXXXXXXX-XXXXXXXX-XXXXXXXX` | PayMe's ID for this transaction (payment, capture, refund or failed attempt) |
| `price` | `1000` | Amount in minor units (50.75 → `5075`) |
| `currency` | `USD` | ISO 4217 code |
| `sale_status` | `completed` | See [Sale Statuses](https://docs-staging.payme.io/marketplaces-and-platforms/lists-statuses/sale-statuses) |
| `payme_transaction_card_brand` | `Visa` | Card brand |
| `payme_transaction_auth_number` | `01A2B3C` | Authorization number from the card company |
| `buyer_card_mask` | `458045******4580` | Masked card number |
| `buyer_card_exp` | `0118` | Card expiry |
| `buyer_name`, `buyer_email`, `buyer_phone`, `buyer_social_id` | | Buyer details |
| `buyer_key` | `XXXXXXXX-…` | Token for future payments; only when `capture_buyer` was set |
| `installments` | `1` | Number of installments |
| `sale_paid_date` | `2016-01-01 15:16:15` | When the payment happened (not when the callback was sent) |
| `sale_release_date` | `2016-01-08 15:15:15` | Release date |
| `is_token_sale` | `0` | `0` false, `1` true |
| `payme_signature` | `75e99dbcb25cdfbe1c62f0b9376f4144` | Signature (see below) |
| `sale_invoice_url` | `https://www.example.com/XXXXXX.pdf` | Invoice URL, if the seller enabled invoices |
## Other callbacks
### Subscriptions
Sent to `sub_callback_url`, or to the partner's callback URL if none is set. **Subscription callbacks carry no `payme_signature`.**
| `notify_type` | When |
|---------------|------|
| `sub-create` | The subscription was created |
| `sub-active` | The subscription became active |
| `sub-iteration-success` | A billing iteration was paid (adds `payme_sale_id` and `payme_sale_code`) |
| `sub-iteration-skipped` | A billing iteration was skipped |
| `sub-failure` | The subscription failed |
| `sub-pause` | The subscription was paused |
| `sub-cancel` | The subscription was cancelled |
| `sub-complete` | The subscription completed |
The payload includes `sub_payme_id`, `sub_status`, `sub_price`, iteration counters and buyer fields. Each iteration also creates a sale, which sends its own `sale-complete` or `sale-failure`.
### Israeli direct debit
- `sale-paid` when the debit is submitted, with `buyer_key` and `buyer_status`.
- When the bank authorization status changes: `sale-complete` or `sale-failure`, then `sale-il-direct-debit-update` with `authorization_status` and `authorization_error_code`. The `authorization_status` values are listed on [Errors](https://docs-staging.payme.io/payments/getting-started/errors) (section "Israeli direct debit").
An Israeli direct-debit *payment* (not authorization) sends no callback on success and can take up to 8 days.
### Sellers (partners)
Sent to the partner's callback URL with all `seller_*` and `fee_*` fields: `seller-create` (adds `seller_public_key`), `seller-update`, `seller-approve`. Related partner notifications: `withdrawal-complete`, `charge-complete`, and `point-of-sale-action-*` (for example after a POS device is paired).
### Bank transfer
A bank transfer reaching `PAID` is reported with a callback.
> ⚠ TO CONFIRM: Bank transfers most likely use the normal `sale-complete` / `sale-failure` callbacks with no dedicated `notify_type`. Please confirm. [Q34]
### B2B payment contracts
A contract's `callback_url` receives a callback for every change in status.
## Verifying a callback (`payme_signature`)
### How it is computed
`payme_signature` is the **lowercase hexadecimal MD5** hash of four values joined with **no separator**, in this order:
1. `payme_client_key` (the partner key)
2. the client password issued together with the client key
3. `payme_transaction_id` (from the payload)
4. `payme_sale_id` (from the payload)
It is a plain MD5 hash, not an HMAC.
Worked example (fake values):
| Input | Value |
|-------|-------|
| `payme_client_key` | `demo_partner_KEY12345` |
| client password | `demoPassw0rd` |
| `payme_transaction_id` | `TRAN1700-000000AA-EXAMPLE1-TXN00001` |
| `payme_sale_id` | `SALE1700-000000AA-EXAMPLE1-SALE0001` |
Joined string: `demo_partner_KEY12345demoPassw0rdTRAN1700-000000AA-EXAMPLE1-TXN00001SALE1700-000000AA-EXAMPLE1-SALE0001`
`payme_signature` = `f8ffc5bb45fe6c3ad326c439f1a21c28`
```python
import hashlib, hmac
def payme_signature_ok(form, client_key, client_password):
expected = hashlib.md5(
(client_key + client_password
+ form["payme_transaction_id"] + form["payme_sale_id"]).encode()
).hexdigest()
return hmac.compare_digest(expected, form.get("payme_signature", ""))
```
> ⚠ TO CONFIRM: What is the "client password" called in PayMe's onboarding material, how does a partner receive it, and how can a merchant that has no `payme_client_key` verify `payme_signature`? [Q1]
### Where the same signature appears
The same formula is used in sale callbacks, the return-URL redirect (including when `payme_status=error`), and the `capture-sale` and `refund-sale` responses. In each case `payme_transaction_id` is the transaction in that payload — the payment, the capture or the refund.
Exceptions:
- Subscription callbacks have no signature. The subscription **return URL** is signed, with `sub_payme_id` in place of `payme_sale_id`.
- `verify_only` refunds return `payme_signature: null`.
- B2B payment contracts use a different formula.
### Confirm the sale before you fulfil
A valid signature tells you the callback refers to a real PayMe sale and transaction. Treat the status and amount in a callback as a notification, not as proof of payment.
**Safe practice:** before you fulfil an order, call [`POST /get-sales`](https://docs-staging.payme.io/payments/query-apis/post-get-sales) with `sale_payme_id` and check `sale_status` and `sale_price` against your order.
> ⚠ TO CONFIRM: Do callbacks come from a fixed set of IP addresses that merchants can allow-list? [Q3]
## Delivery, retries, duplicates and ordering
### What counts as delivered
- Any HTTP status **below 400** counts as delivered. The response body is ignored, and redirects are followed.
- Each attempt times out after **5 seconds**. Reply `200` immediately and do the slow work (emails, fulfilment) afterwards.
### Retries
- PayMe makes **up to 3 attempts**: the first, a retry about 30 seconds later, and a last retry about 60 seconds after that.
- A 4xx or 5xx response, a timeout, or a connection error triggers a retry.
- After the last attempt the callback is **dropped**. It cannot be replayed through the API.
- If your endpoint keeps failing, PayMe pauses delivery to it for a short time, and callbacks during that time are skipped.
**Do not rely on callbacks alone.** Reconcile with [`POST /get-sales`](https://docs-staging.payme.io/payments/query-apis/post-get-sales).
### Duplicates
The same callback can arrive more than once — typically when your endpoint processes it but replies after the 5-second timeout. There is no event ID. De-duplicate on **`notify_type` + `payme_sale_id` + `payme_transaction_id`**; each refund, capture and failed attempt has its own `payme_transaction_id`.
### Ordering
> ⚠ TO CONFIRM: Callbacks are most likely **not** delivered in order — they are sent by parallel workers with retry delays, so a `refund` can arrive before a `sale-complete` that is still being retried, and there is no sequence number or event timestamp. Please confirm, so the docs can state it as a rule. Until then: never let a later-arriving callback overwrite a final state you already recorded, and query the sale when in doubt. [Q33]
## Handling checklist
1. Parse the body as form data and reply `200` within 5 seconds.
2. Verify `payme_signature` (sale callbacks).
3. Ignore it if you already processed this `notify_type` + `payme_sale_id` + `payme_transaction_id`.
4. Before fulfilling, confirm `sale_status` and `sale_price` with `POST /get-sales`.
5. Run a periodic reconciliation with `get-sales`, because callbacks can be dropped after 3 attempts.
- [Errors](https://docs-staging.payme.io/payments/getting-started/errors): Payments API errors return status_code 1 with status_error_code, status_error_details (Hebrew unless language is en; he, en, es, ru, ar accepted) and status_additional_info (often the field name). Branch on status_code and status_error_code, never on HTTP status: card declines return HTTP 200, many request errors HTTP 500, some 400/403/422/429/503. Common codes: 1 missing parameter, 200 unknown client key, 251 seller not found, 252 currency not allowed, 305 wrong sale status, 352 invalid price, 998 too many or duplicate requests, 20xxx/21xxx card declines.
# Errors
## Error response shape (Payments API)
```json
{
"status_code": 1,
"status_error_details": "Seller was not found",
"status_additional_info": "seller_payme_id",
"status_error_code": 251
}
```
| Field | Meaning |
|-------|---------|
| `status_code` | `0` success, `1` error. |
| `status_error_code` | PayMe's numeric error code. `0` on success. |
| `status_error_details` | The error message, in the language you asked for. |
| `status_additional_info` | Extra detail — usually the name of the field at fault. Alternatives are joined with ` / `, for example `seller_payme_id / seller_id`. |
| `payme_status` | `success` or `error` (on some responses and on the return-URL redirect). |
Error bodies also include a `session` field.
## HTTP status vs `status_error_code`
The two numbers are separate: `status_error_code` is never used as the HTTP status.
| Situation | HTTP status |
|-----------|-------------|
| Card declined (codes `20xxx` / `21xxx`) | **200**, with `status_code: 1` |
| Most request errors — for example missing parameter (`1`), unknown client key (`200`), unknown seller (`251`), wrong sale status (`305`) | **500** |
| Some access and input errors | 400, 403 or 422 |
| Too many requests, or a duplicate call still running (`998`) | 429 |
| Service temporarily read-only | 503 |
**Decide what happened from `status_code` and `status_error_code`, not from the HTTP status.** A `200` can be a decline, and a `500` usually means your request needs fixing, not that PayMe is down.
## Getting messages in English
If you omit `language`, messages come back in **Hebrew**. Send `"language": "en"` on every call. Accepted values are `he`, `en`, `es`, `ru` and `ar`; any other value returns error `51`.
A few very early errors, such as a malformed key format, may still come back in Hebrew.
> ⚠ TO CONFIRM: `language` is honoured on the Payments, subscription, transaction and seller-management endpoints that were checked; please confirm it applies to every Payments endpoint. [Q16]
## Common error codes
The tables below cover the codes integrators meet most often.
> ⚠ TO CONFIRM: Is there an authoritative, complete list of `status_error_code` values with English meanings that can be published here? [Q14]
### Request and credential errors
| Code | Meaning | What to do |
|------|---------|------------|
| `1` | Required parameter is missing. `status_additional_info` names it. Also returned when no client key and no seller key are sent. | Add the named field. |
| `10` | `installments` is not numeric | Send a number such as `1` or `"1"`. |
| `19` | Please provide all required fields (some endpoints) | Check the endpoint's required fields. |
| `20` | Validation error. Also "Merchant-Seller inconsistency" (HTTP 400): the seller belongs to a different partner from the `payme_client_key` sent. | Fix the fields listed in `status_additional_info`. |
| `51` | Unsupported `language` value | Use `he`, `en`, `es`, `ru` or `ar`. |
| `163` | The seller exists but is inactive | Contact PayMe. |
| `200` | Merchant was not found: the `payme_client_key` (or `PayMe-Partner-Key`) matches no partner. `status_additional_info` is `payme_client_key`. | Check the key and the environment. |
| `201` | The partner is inactive | Contact PayMe. |
| `251` | Seller was not found: the `seller_payme_id` / `seller_id` matches no seller. Also returned for an unknown public key during card tokenization. | Check the MPL or public key and the environment. |
| `252` | Currency not allowed for this account | Use a currency enabled on the account. |
| `352` | `sale_price` is not numeric or is outside the allowed range | Send minor units within the allowed range. |
| `353` | `product_name` is missing | Add `product_name`. |
| `357` | Unknown `sale_type` value | Use a documented `sale_type`. |
### Sale-state, retry and rate-limit errors
| Code | Meaning | What to do |
|------|---------|------------|
| `305` | Cannot perform action due to an incorrect status. `status_additional_info` holds the sale's current status. Returned, for example, when a paid sale is paid again or a fully refunded sale is refunded again. | Check the sale with `get-sales`; do not retry. |
| `998` | HTTP 429. Either "Too Many Attempts." (rate limit) or "Duplicated action detected, please retry later" (the same action on the same sale is still running). Tell them apart by `status_additional_info` / the message. | Wait (`Retry-After` header) and check the sale before retrying. |
### Card declines
Declines return HTTP 200 with `status_code: 1`. Codes `21xxx` are card problems; `20xxx` are refusals from the card company or gateway.
| Code | Message |
|------|---------|
| `20004` | Refusal by credit company. Please try a different card |
| `21001` | The card is blocked |
| `21002` | The card is stolen |
| `21004` | The card is expired |
| `21005` | Incorrect card number |
| `21006` | The credit limit has been reached |
| `21007` | CVV/ID is required but was not entered |
| `21008` | Incorrect CVV or ID |
The sandbox test cards that produce each one are on [Environments](https://docs-staging.payme.io/payments/getting-started/environments).
### Other codes
Other codes shown on endpoint pages: `356` invalid credit-card expiry (3D Secure initialize, capture-buyer-token); `600` buyer not found (get-buyer-key); `720` the service was not activated on the account, with the service name in `status_additional_info` (Apple Pay, Google Pay, B2B transfer); `901` invalid JSON (get-transactions); `906` withdrawal not found (credit-match).
### Products & Customers API
Errors carry `status_code` `1`, a `message`, and a `status_error_code` equal to the HTTP status: `400` "Bad Request", `401` "Unauthorized request", `500` "Internal Server Error".
### Keep API
- OAuth token errors (HTTP 401) return `error` and `error_description`.
- Some partner endpoints return `{"statusCode": 1, "payload": {"message": "..."}}`, for example HTTP 429 "Rate limit exceeded" and "Update conflict".
- The document-failure webhook example uses `errorCode` `TAX_AUTHORITY_REJECTED` ("Document rejected by tax authority - invalid VAT number").
### B2B payment contracts (`error_code` on a contract)
| `error_code` | `error_text` |
|--------------|--------------|
| `11000` | Recipient Rejected |
| `11001` | Initiator Canceled |
| `11002` | Recipient Confirmation Timeout |
| `11003` | Initiator Confirmation Timeout |
| `11004` | Payment Processing Failure |
This is the complete list. For `11004`, `error_note` is free text and may contain a regular PayMe error message.
### Israeli direct debit
When a bank authorization changes, the `sale-il-direct-debit-update` callback carries `authorization_status` and `authorization_error_code`.
| `authorization_status` | Meaning | Effect |
|------------------------|---------|--------|
| `1` | Success | Authorization active |
| `2` | Failed | Failed |
| `3` | Canceled | Canceled |
| `4` | Unknown | Failed |
| `5` | Moved from previous account | Failed |
| `6` | Account changed | Failed |
| `13` | Frozen authorization reactivated | Authorization active |
| `14` | Sent to the bank | Pending |
| `15` | Sent to the bank again | Pending |
| `16` | Details missing | Failed |
| `17` | Details incorrect | Failed |
| `18` | Already processed (success) | Authorization active |
`authorization_error_code` is passed through unchanged from the bank side.
> ⚠ TO CONFIRM: What values can `authorization_error_code` take (for example `"11"`) and what does each mean? [Q51]
## Related status lists
Not errors, but often needed when handling them: [Sale Statuses](https://docs-staging.payme.io/marketplaces-and-platforms/lists-statuses/sale-statuses), [Transaction Statuses](https://docs-staging.payme.io/marketplaces-and-platforms/lists-statuses/transaction-statuses), [Subscription Statuses](https://docs-staging.payme.io/marketplaces-and-platforms/lists-statuses/subscription-statuses).
- [Idempotency and Retries](https://docs-staging.payme.io/payments/getting-started/idempotency-and-retries): PayMe has no idempotency key and does not de-duplicate transaction_id: two generate-sale calls create two sales. A second pay-sale, refund-sale or capture-sale for the same sale while the first is running gets HTTP 429 code 998; once it finished, a retry runs again (a repeated partial refund is a second refund; a paid sale paid again gets 305). After a timeout, check sale_status via POST /get-sales (filter by sale_payme_id or transaction_id) before retrying. generate-sale, pay-sale and capture-sale share a per-seller rate limit, 100 requests per 10 s by default.
# Idempotency and Retries
"Idempotent" means that sending the same request twice has the same effect as sending it once. **PayMe has no idempotency key**, so you must make retries safe yourself.
## What happens when a request runs twice
| Request | Second call while the first is **still running** | Second call **after** the first finished |
|---------|-----------------------------------------------|------------------------------------------|
| `generate-sale` | A second, separate sale | A second, separate sale — `transaction_id` is **not** checked for uniqueness |
| `generate-sale` with `buyer_key` / token (creates **and charges**) | A second charge is possible | A second charge is possible |
| `pay-sale` | Rejected: HTTP 429, code `998` "Duplicated action detected, please retry later" | If the first succeeded: rejected with HTTP 500, code `305`, current status in `status_additional_info`. If the first failed: accepted as a **new charge attempt**. |
| `refund-sale` — partial | Rejected: HTTP 429, code `998` | **Runs again** — a second refund, as long as refundable balance remains |
| `refund-sale` — full | Rejected: HTTP 429, code `998` | Rejected with code `305` |
| `capture-sale` | Rejected: HTTP 429, code `998` | An authorization can be captured only once. |
Notes:
- **`transaction_id` is your own reference.** PayMe stores and returns it but does not reject duplicates: each `generate-sale` creates a new sale with its own `payme_sale_id`.
- **Template sales:** each `pay-sale` on a template creates a new sale, so the protections above do not apply to template sales.
- PayMe does not promise that a retried payment can never charge twice. Check before you retry.
- An authorization lasts up to 168 hours; a capture after that fails. A void must be for the full authorized amount.
## Before retrying, check the sale
If a request timed out and you do not know whether it ran, look the sale up instead of resending it.
[`POST /get-sales`](https://docs-staging.payme.io/payments/query-apis/post-get-sales) accepts these filters:
- `sale_payme_id` — PayMe's sale ID (one sale);
- `transaction_id` — your order ID. Because `transaction_id` is not unique, this can return several sales.
**By default `get-sales` leaves out unpaid sales** (status `initial`). To find an unpaid sale, pass `sale_status` including `initial`.
`get-sales` works with `seller_payme_id` alone; partners can also use `payme_client_key`.
> ⚠ TO CONFIRM: Reading `sale_status` from `get-sales` is most likely the right way to tell whether a timed-out operation ran — capture → `completed` (not `authorized`/`failed`), full refund → `refunded`, void → a voided status. Please confirm this is the recommended check, and the exact status strings for partial refunds and voids (the docs show `partial-refund`; PayMe's API code suggests `partially-refunded`). Note that `sale_status` alone cannot show whether a **retried partial refund** already ran: compare `sale_refund_buffer` (the amount still refundable, returned by `refund-sale` and sent in each `refund` callback — `get-sales` does not return it) or count the `refund` callbacks, each of which has its own `payme_transaction_id`. [Q25]
## Retrying safely
1. Retry only on network errors, timeouts, or HTTP 429 code `998`. Never retry a response with `status_code` `1` that names a problem with your input.
2. On `998`, wait (honour the `Retry-After` header), then **check the sale** before retrying.
3. Before retrying anything that moves money (`pay-sale`, `refund-sale`, `capture-sale`, `generate-sale` with `buyer_key`), check the sale's current state as above.
4. Store PayMe's `payme_sale_id` as soon as `generate-sale` returns, so every later step refers to one sale.
5. Treat callbacks as confirmation, and process each one once — see [Callbacks](https://docs-staging.payme.io/payments/getting-started/callbacks).
> ⚠ TO CONFIRM: What client-side timeout should integrators use for Payments API calls (typical and maximum response time)? [Q29]
## PayMe's own retries
- **Callbacks:** up to 3 attempts over about 2 minutes, then dropped. Details on [Callbacks](https://docs-staging.payme.io/payments/getting-started/callbacks).
- **Subscriptions:** a subscription in status `76` is "Failed - Pending automatic retry", so PayMe retries failed subscription charges itself.
## Rate limits
- `generate-sale`, `pay-sale` and `capture-sale` (and tokenization and 3D Secure calls) share one **per-seller** limit — by default **100 requests per 10 seconds**. PayMe can set a different limit per account; partners can read theirs from `GET /partners` (`technical.rate_limit_max_attempts`, `technical.rate_limit_decay_seconds`).
- Over the limit: **HTTP 429**, `status_error_code` `998`, `status_additional_info` `"Too Many Attempts."`, and the headers `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `Retry-After` and `X-RateLimit-Reset`.
- `refund-sale` and `get-sales` have no per-seller limit.
> ⚠ TO CONFIRM: Is 100 requests per 10 seconds per seller also the default in **production**? [Q28]
- **Keep:** a partner endpoint documents HTTP `429` with message "Rate limit exceeded".
## Introduction
- [Payments overview](https://docs-staging.payme.io/payments/introduction/getting-started): Our API is designed to allow platforms to offer a full payment solution as part of their product.
# Getting Started
Our API is designed to allow platforms to offer a full payment solution as part of their product.
Using the API you can:
- Create and manage Merchant on your platform
- Allow merchants to accept credit card paymentsCreate standard transactions
- Create recurring payments
- Use our secured payment pages
- Use Tokenization for delayed & future payments
- Charge a platform fee from every transactionQuery data regarding sellers, transactions, subscriptions, withdrawals and more
PCI compliant and want to use the direct credit card API? [Let us know!](https://payme.io/contact-us/)
By using the API you will be able to handle all transactions on your website without dealing with sensitive credit card details, processing difficulties or PCI compliancy. The basics are simple. You POST required information to our target URL's using JSON format and get replies structured in JSON format. You are free to use whatever programming language you prefer.
##### Note:
Do not forget to add the header Content-Type: application/json to your requests! Callbacks - We have an option to send out a server to server notifications, also known as "IPN".
For example: a customer successfully paying using the IFRAME; a successful subscription iteration. The format and details are described throughout this document. The callback is a POST request of type x-www-form-urlencoded to your provided target URL.
- [Sandbox and Production URLs](https://docs-staging.payme.io/payments/introduction/sandbox-and-production-urls): In order to work with the API, you should use the service URLs according to the required environments, Sandbox or Production.When interacting with the API, make sure you point to the correct environment, with the correct credentials. Both URLs will be stated next to each function.
# Sandbox and Production URLs
In order to work with the API, you should use the service URLs according to the required environments, Sandbox or Production. When interacting with the API, make sure you point to the correct environment, with the correct credentials. Both URLs will be stated next to each function.
ENVIRONMENT | URL
---------|----------
Sandbox | https://sandbox.payme.io/api/
Production | https://live.payme.io/api/
- [Test Cards and Payment Methods](https://docs-staging.payme.io/payments/introduction/test-cards-and-payment-methods): Please use the following credit card when integrating only in the **Sandbox** environment.
# Test Cards and Payment Methods
Please use the following credit card when integrating only in the **Sandbox** environment.
## Main credit card numbers for testing
EMV supported credit cards:
Credit Card |Details
---|---
**Card Number:** `4557430402053431` **Expiration:** `12/30` **CVV:**`200` **Social ID:**`008336174`|**Limitations**: Acts as an international non-Israeli card. Accepts sales with only one installment. Accepts sales in ILS, USD, EUR.
**Card Number:** `375516193000090` **Expiration:** `12/30` **CVV:** `0957` **Social ID:**`008336174`| **Limitations**: Acts as an international Israeli card. Accepts sales with multiple installments. Accepts sales in ILS, USD, EUR.
**Card Number:** `5326105300985846` **Expiration:** `12/30` **CVV:** `658` **Social ID:**`008336174`| **Limitations**: Acts as a local Israeli card. Accepts sales with multiple installments. Accepts sales in ILS only.
## Secondary credit card numbers for testing
Credit Card Type |Credit Card Number
---|---
Visa| `4111111111111111` `4200000000000000`
Mastercard| `5555555555554444` `5454545454545454`
AmericanExpress| `378282246310005` `377777777777770`
Diners |`38520000023237`
Discover| `6011000990139424`
JCB |`3530111333300000`
Isracard|` 12312312`
## Credit card numbers for testing specific responses and errors
Card Number |Description
---|---
`4000000000000002`| Payment is declined with a card declined error
`4000000000000051`| Payment is declined with a card blocked error
`4000000000000085`| Payment is declined with a card stolen error
`4000000000000069`| Payment is declined with a card expired error
`4000000000000101`| Payment is declined with a required CVV error
`4000000000000127`| Payment is declined with an incorrect CVV
`4000000000000135`| Payment is declined with a credit limit reached error
`4242424242424241`| Payment is declined with an incorrect card number error
`4000000000000036`| Token capture succeeds, but payment is declined with a card declined error
## Apple Pay Testing Information
Card Brand | Card Number | Card Expiry Date | Card CVV
---|---|---|---
Visa | 4051 0693 0220 0121 | 12/27 | 340
Mastercard | 5204 2452 5052 2095 | 12/30 | 111
American Express | 37272 79248 51007 | 12/28 | 1111
Discvoer | FPAN: 6011 0009 9475 4889 | 12/30 | 111
## Israeli Direct Debit Testing Information
Bank Account Infromation (Bank, Branch, Account Number) |Description
---|---
`54, 112, 2222111` |Bank Authorization is approved after 60 seconds
`54, 113, 4444333`|Bank Authorization is declined after 60 seconds
## SEPA Payment Method Testing Information
Account Number |Description
---|---
`DE89370400440532013000 `| The Payment status transitions from `initial` to `completed` immidiately.
`DE08370400440532013003`|The Payment status transitions from `initial` to `completed` after 3 minutes.
`DE62370400440532013001` |The Payment status transitions from `initial` to `failed` immidiately.
`DE78370400440532013004`|The Payment status transitions from `initial` to `failed` after 3 minutes.
`DE35370400440532013002`|The Payment status transitions from `initial` to `completed` and then immidiately to `chargeback`.
## BACS Payment Method Testing Information
SORT CODE |Account Number| Description
---|---|---
`108800 `| `00012345`| The Payment status transitions from `initial` to `completed` immidiately.
`108800 `| `90012345`| The Payment status transitions from `initial` to `completed` after 3 minutes.
`108800 `| `33333335`| The Payment status transitions from `initial` to `completed` and than immidiately changed to `Failed`.
- [Value Added Services](https://docs-staging.payme.io/payments/introduction/value-added-services): At PayMe, We go beyond traditional financial solutions to offer a comprehensive suite of value-added services. These services are designed to enhance our clients' financial experiences and empower them with the tools they need for success. From the creation of invoices and security services to seamless integration with third-party platforms, our value-added services cater to the diverse needs of your business.
# Value Added Services
At PayMe, We go beyond traditional financial solutions to offer a comprehensive suite of value-added services. These services are designed to enhance our clients' financial experiences and empower them with the tools they need for success. From the creation of invoices and security services to seamless integration with third-party platforms, our value-added services cater to the diverse needs of your business.
- [Payment Options](https://docs-staging.payme.io/payments/introduction/payment-options): We have three integration options: - [Hosted Payment Page](https://docs-staging.payme.io/payments/hosted-payment-page/post-generate-sale) - [Hosted Fields - JSAPI](https://docs-staging.payme.io/marketplaces-and-platforms/integrations/hosted-fields-jsapi-guide) - [Direct API](https://docs-staging.payme.io/marketplaces-and-platforms/integrations/direct-api-how-to-create-and-pay-sale)
# Integration Options
We have three integration options:
- [Hosted Payment Page](https://docs-staging.payme.io/payments/hosted-payment-page/post-generate-sale)
- [Hosted Fields - JSAPI](https://docs-staging.payme.io/marketplaces-and-platforms/integrations/hosted-fields-jsapi-guide)
- [Direct API](https://docs-staging.payme.io/marketplaces-and-platforms/integrations/direct-api-how-to-create-and-pay-sale)
Integration | Description | Advantages ✔️ | Disadvantages ❌
---------|----------|---------|---------
[Hosted Payment Page](https://docs-staging.payme.io/payments/hosted-payment-page/post-generate-sale) | With this approach, the payment process is redirected to our secure payment gateway's website, where customers enter their payment details. We handle the transaction and send the result back to the merchant's website. | **Security**: Since the payment process occurs on our payment gateway's secure server, the merchant's website doesn't handle sensitive payment information directly, reducing the risk of data breaches.
**Simplicity**: Implementing a hosted payment page is relatively straightforward, as PayMe handles most of the complex payment processing tasks for you.
**Compliance**: The responsibility for meeting payment industry security standards, such as PCI DSS (Payment Card Industry Data Security Standard), lies with PayMe, relieving the merchant of some compliance burdens. | **Customization limitations**: Our hosted payment pages can't be customed designed, which may not seamlessly integrate with the merchant's website design.
**Limited control**: As the payment process is handled by PayMe, the merchant has less control over the overall checkout experience and may be restricted in customizing certain features or functionalities.
[Hosted Fields - JSAPI](https://docs-staging.payme.io/marketplaces-and-platforms/integrations/hosted-fields-jsapi-guide) | JSAPI (JavaScript API) payment integration allows you to embed payment forms directly into your website using JavaScript. This method enables a seamless payment experience for customers, without the need for redirection to an external page. | **Seamless user experience**: Customers can complete the entire payment process without leaving the merchant's website, enhancing convenience and reducing the risk of customer drop-off during checkout.
**Design flexibility**: By integrating payment forms using JavaScript, merchants have more control over the appearance and customization of the payment interface, enabling a consistent brand experience.
**Real-time response**: With JSAPI, payment responses can be processed in real-time, allowing for immediate feedback on the payment status and reducing the risk of potential payment errors or delays. | **Security considerations**: Handling sensitive data on the merchant's servers requires robust security measures.
**Development complexity**: Requires advanced programming skills and maintenance of the payment system.
[Direct API](https://docs-staging.payme.io/marketplaces-and-platforms/integrations/direct-api-how-to-create-and-pay-sale)| PayMe's API is integrated directly into your website or application. | **Customization and control**: Allows full control and customization of the payment process.
**Enhanced security**: You can implement robust encryption and security measures according to your requirements.
**Scalability and efficiency**: Facilitates real-time transaction updates and integrations with other systems. | **Development complexity**: Requires advanced programming skills and understanding of PayMe's API.
**Compliance responsibility**: Merchant must meet security standards and ensure ongoing maintenance and updates (PCI-DSS level 1).
## Hosted Payment Page
- [Generate Payment](https://docs-staging.payme.io/payments/hosted-payment-page/post-generate-sale): POST /generate-sale — Generate Payment
# Generate Payment
- Sandbox: `POST https://sandbox.payme.io/api/generate-sale`
- Production: `POST https://live.payme.io/api/generate-sale`
## Credentials
- Request body field `seller_payme_id` (required): MPL. Your private key in PayMe system.
## Overview
This endpoint can be used for the following actions:
Action | Description
----|----
Basic Sale (J4) | Allows you to create a sale.
Authorization (J5)| The requested amount gets reserved (blocked) on the credit card of the buyer for up to 168 hours.
You can find more information in our [Capture Sale Guide](/marketplaces-and-platforms/payments/capture-sale).
Template Payment Page | Enables many payments on a single sale link, by different buyers.
You can find more information in our [Template Payment Page Guide](/marketplaces-and-platforms/payments/multi-payment-page).
Create Payment With Buyer Key (Token)| Enables to capture token once the buyer pays (enter the payment details).
You can find more information in our [Create Payment With Buyer Key (Token) Guide](/marketplaces-and-platforms/payments/create-payment-with-buyer-key-token).
**See the request example below.**
* For all the sale types see [Sale Types](/marketplaces-and-platforms/lists-statuses/sale-types).
* For all the payment methods see [Available Payment Methods](/payments/direct-api/available-payment-methods).
#### Callbacks
Once the sale is paid successfully, we will notify the marketplace with the sale details with a POST of `type` `x-www-form-urlencoded` request to the marketplace Callback URL.
You can find the sale callback attributes [Sale Callbacks](/marketplaces-and-platforms/lists-statuses/sale-callbacks).
#### Issuing an Invoice for a Business
In the case where you are connected to our invoices services, you can send the following parameters as a part of your `generate-sale` API request to us when paying using a Token (saved card) in our platform.
Please add the following parameters to your request:
Parameter Name|Parameter Type|Example & Limitations
--|--|--
`buyer_business_name`| `string` | The name of the business the invoice should be issued for.
`buyer_business_code` | `integer` | The business code (VAT identifier) of the company the invoice is issued for.
#### Multi Payment Methods Checkout Page
To allow the buyer to select the payment method by himself, use `sale_payment_method="multi"`.
It will show your available payment methods (based on the added services in your account) in one payment page: Credit card, bit, ApplePay and GooglePay.
## Parameters
This endpoint takes no path, query or header parameters.
## Request body
Content type: `application/json`
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `seller_payme_id` | string | yes | MPL. Your private key in PayMe system. |
| `sale_price` | number | yes | Sale final price. For example, if the price is 50.75 (max 2 decimal points) the value that needs to be sent is 5075. Note that the minimum value is 500. |
| `currency` | string | yes | Sale currency. [3-letter ISO 4217 name](https://en.wikipedia.org/wiki/ISO_4217). |
| `product_name` | string | yes | Short name and description of the product/service. This text will be shown in the invoice as well, if the seller has enabled the invoices module in his account panel. Limited to 500 characters |
| `transaction_id` | string | no | Merchant's unique sale ID for correlation with us |
| `installments` | string | no | Amount of installments for the sale. We allow you to manually set the number of installments or to specify a top limit of installments for the buyer to choose from while paying. Setting a fixed number of installments is simply entering a number between 1 and 12. The sale will be initiated with this number of installments and the buyer will not be able to change it. To set a range for the buyer to choose from, enter the following: `103` - allow up to 3 installments `106` - allow up to 6 installments `109` - allow up to 9 installments `112` - allow up to 12 installments |
| `market_fee` | number | no | A decimal representing the percent of the sale price that is collected for the marketplace (includes VAT). This fee is added on top of our fees and transferred to the marketplace once a month. Default value is the market fee of the Seller, as set upon Seller creation. |
| `sale_send_notification` | boolean | no | Flag to send email and/or SMS notifications |
| `sale_callback_url` | string | no | Callback response to your page regarding call to our API. Default value is taken from the Merchant's settings. Note that you may not send a "localhost" URL as value |
| `sale_email` | string | no | In case sale send notification is true provide the address to send email notification |
| `sale_return_url` | string | no | We will redirect the IFRAME and the buyer to this URL upon payment success. Default value is taken from the Merchant's settings |
| `sale_mobile` | string | no | In case sale send notification is true, provide the phone number to send SMS notification, if the seller has enabled the SMS module in his account panel |
| `sale_name` | string | no | The name that will be displayed when sending a notification |
| `capture_buyer` | string | no | Flag for requesting the buyer's token for this payment (0 - do not capture token, 1 - capture token). For additional information see Tokens explanation below |
| `buyer_perform_validation` | string | no | Flag for performing an online validation of the card with the Issuer. |
| `sale_type` | string | no | You can find all the sale types [Sale Types](/marketplaces-and-platforms/lists-statuses/sale-types). |
| `sale_payment_method` | string | no | the Payment method used to pay the sale. For all the payment methods see [Available Payment Methods](/payments/direct-api/available-payment-methods). To display multi payment methods use `multi`. |
| `layout` | string | no | IFRAME payment page layout. Optional attribute which may be used with "bit" sale_payment_method. Avai lable layouts are:dynamic, qr-sms or dynamic-loose dynamic loose removes the validation for the social ID and CVV. |
| `language` | string | no | Changes the language of the payment IFRAME to English, as well as the error messages. Default value is Hebrew (he) |
| `order_number` | string | no | Purchase Order Number. Mandatory for level 2 / 3 card data. Maximum length: 15 digits |
| `items` | array | no | This is an object that should include multiple arrays. An array for each product (item) that is a part of this sale. All parameters that are numeric or integer must be equal or more than 0. |
| `items[].name` | string | no | Name of the Item Minimum length: 1 Character Maximum length: 50 Characters |
| `items[].quantity` | integer | no | Number of items, Minimum length: 0 digits, Maximum length: 6 digits |
| `items[].unit_price` | integer | no | Price of single unit in pennies, No length limitations |
| `items[].unit_measurement` | string | no | Unit of measurment, Minimum length: 0 characters (nullable), Maximum length: 12 characters |
| `items[].total` | integer | no | Total Price After Discount, Minimum length: 0 digits, Maximum length: 10 digits |
| `items[].discount_total` | number | no | In negative pennies amount, Minimum length: 0 digits (nullable), Maximum length: 12 digits |
| `items[].description` | string | no | The item description, Minimum length: 0 characters (nullable, Maximum length: 150 characters |
| `items[].product_code` | string | no | The item catalog code. Minimum length: 0 characters (nullable), Maximum length: 100 characters |
| `items[].commodity_code` | number | no | The item's commodity code, Minimum length: 0 digits (nullable), Maximum length: unlimited |
| `fees` | object | no | Amount of tax in pennies No length |
| `fees.tax` | number | no | The tax collected as a part of the payment - In pennies, Minimum length: 0, Maximum Length: 12 Digits |
| `fees.duty` | number | no | The international fees collected as a part of the payment - In pennies, Minimum lenth: 0, Maximum Length: 12 Digits |
| `fees.discount` | number | no | The total discount given for the payment - In pennies, Minimum length: 0, Maximum Length: 12 Digits |
| `fees.shipping` | number | no | The shipping cost charged as a part of the payment - In pennies, Minimum lenth: 0, Maximum Length: 12 Digits |
| `shipping_details` | object | no | |
| `shipping_details.name` | string | no | Individual's full name/Company's name, Maximum Length: 50 Characters |
| `shipping_details.email` | string | no | Email address of the addressee, Maximum Length: 100 Characters |
| `shipping_details.phone` | string | no | Phone number of the addressee, Maximum Length: 50 Characters |
| `shipping_details.address` | object | no | Address Object |
| `shipping_details.address.line1` | string | no | Line 1 of the shipping address, No Limits. |
| `shipping_details.address.line2` | string | no | Line 1 of the shipping address, No Limits. |
| `shipping_details.address.postal_code` | string | no | Postal code of the shipping address, No Limits. |
| `shipping_details.address.city` | string | no | City of the shipping address, No Limits. |
| `shipping_details.address.state` | string | no | State of the shipping address, No Limits. |
| `shipping_details.address.country` | string | no | Country of the shipping address, No Limits. |
| `billing_details` | object | no | |
| `billing_details.name` | string | no | Individual's full name/Company's name, No Limits. |
| `billing_details.email` | string | no | Email address of the payer, No Limits. |
| `billing_details.phone` | string | no | Phone number of the payer, No Limits. |
| `billing_details.address` | object | no | |
| `billing_details.address.line1` | string | no | Line 1 of the billing address, No Limits. |
| `billing_details.address.line2` | string | no | Line 2 of the billing address, No Limits. |
| `billing_details.address.postal_code` | string | no | Postal code of the billing address No Limits. |
| `billing_details.address.city` | string | no | City of the billing address, No Limits. |
| `billing_details.address.state` | string | no | State of the shipping address, No Limits. |
| `billing_details.address.country` | string | no | Country of the billing address, No Limits. |
| `buyer_name` | string | no | Buyer's name |
| `buyer_email` | string | no | Buyer's email |
| `buyer_phone` | string | no | Buyer's phone |
### Request example
```json
{
"seller_payme_id": "MPLDEMO-MPLDEMO-MPLDEMO-1234567",
"sale_price": 1000,
"currency": "ILS",
"product_name": "Smartphone",
"transaction_id": "12345",
"installments": "1",
"market_fee": 0.5,
"sale_send_notification": true,
"sale_callback_url": "https://www.payme.io",
"sale_email": "test@payme.io",
"sale_return_url": "https://www.payme.io",
"sale_mobile": "+9725254448888",
"sale_name": "Test User",
"capture_buyer": "0",
"buyer_perform_validation": false,
"sale_type": "sale",
"sale_payment_method": "credit-card",
"language": "he"
}
```
## Code samples
### curl
```bash
curl -X POST 'https://sandbox.payme.io/api/generate-sale' \
-H 'Content-Type: application/json' \
--data-raw '{
"seller_payme_id": "MPLDEMO-MPLDEMO-MPLDEMO-1234567",
"sale_price": 1000,
"currency": "ILS",
"product_name": "Smartphone",
"transaction_id": "12345",
"installments": "1",
"market_fee": 0.5,
"sale_send_notification": true,
"sale_callback_url": "https://www.payme.io",
"sale_email": "test@payme.io",
"sale_return_url": "https://www.payme.io",
"sale_mobile": "+9725254448888",
"sale_name": "Test User",
"capture_buyer": "0",
"buyer_perform_validation": false,
"sale_type": "sale",
"sale_payment_method": "credit-card",
"language": "he"
}'
```
### Node.js
```javascript
const response = await fetch("https://sandbox.payme.io/api/generate-sale", {
method: "POST",
headers: {
"Content-Type": "application/json",
},
body: JSON.stringify({
"seller_payme_id": "MPLDEMO-MPLDEMO-MPLDEMO-1234567",
"sale_price": 1000,
"currency": "ILS",
"product_name": "Smartphone",
"transaction_id": "12345",
"installments": "1",
"market_fee": 0.5,
"sale_send_notification": true,
"sale_callback_url": "https://www.payme.io",
"sale_email": "test@payme.io",
"sale_return_url": "https://www.payme.io",
"sale_mobile": "+9725254448888",
"sale_name": "Test User",
"capture_buyer": "0",
"buyer_perform_validation": false,
"sale_type": "sale",
"sale_payment_method": "credit-card",
"language": "he"
}),
});
console.log(await response.text());
```
### Python
```python
import requests
response = requests.post(
"https://sandbox.payme.io/api/generate-sale",
json={
"seller_payme_id": "MPLDEMO-MPLDEMO-MPLDEMO-1234567",
"sale_price": 1000,
"currency": "ILS",
"product_name": "Smartphone",
"transaction_id": "12345",
"installments": "1",
"market_fee": 0.5,
"sale_send_notification": True,
"sale_callback_url": "https://www.payme.io",
"sale_email": "test@payme.io",
"sale_return_url": "https://www.payme.io",
"sale_mobile": "+9725254448888",
"sale_name": "Test User",
"capture_buyer": "0",
"buyer_perform_validation": False,
"sale_type": "sale",
"sale_payment_method": "credit-card",
"language": "he",
},
)
print(response.text)
```
### PHP
```php
'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;
```
## Responses
### 200 — Sale Created Successfully (success)
| Field | Type | Description |
| --- | --- | --- |
| `status_code` | number | Status of the request (0 - success, 1 - error) |
| `sale_url` | string | The URL of the IFRAME secured payment form to display to the buyer |
| `payme_sale_id` | string | Our unique sale ID |
| `payme_sale_code` | number | Our unique sale code (for display purposes only) |
| `price` | number | Sale final price. For example, if the price is 50.75 (max 2 decimal points) the value that needs to be sent is 5075 |
| `transaction_id` | string | Merchant's unique sale ID for correlation with us |
| `currency` | string | Sale currency. [3-letter ISO 4217 name](https://en.wikipedia.org/wiki/ISO_4217). |
```json
{
"status_code": 0,
"sale_url": "https://preprod.paymeservice.com/sale/generate/XXXXXXXX-XXXXXXXX-XXXXXXXX-XXXXXXXX",
"payme_sale_id": "XXXXXXXX-XXXXXXXX-XXXXXXXX-XXXXXXXX",
"payme_sale_code": 12345678,
"price": 10000,
"transaction_id": "12345",
"currency": "USD"
}
```
### 500 — Missing Required Information (error)
| Field | Type | Description |
| --- | --- | --- |
| `status_code` | number | |
| `status_error_details` | string | |
| `status_additional_info` | string | |
| `status_error_code` | number | |
```json
{
"status_code": 1,
"status_error_details": "קישור משתמש לא נמצא",
"status_additional_info": null,
"status_error_code": 251
}
```
- [Generate Multi Checkout Payment](https://docs-staging.payme.io/payments/hosted-payment-page/post-generate-sale-2): How to call POST /generate-sale for Hosted Payment Page.
# Generate Multi Checkout Payment
This is a variant of [POST /generate-sale — Generate Payment](https://docs-staging.payme.io/payments/hosted-payment-page/post-generate-sale); the request and responses below are the ones documented for Hosted Payment Page.
- Sandbox: `POST https://sandbox.payme.io/api/generate-sale`
- Production: `POST https://live.payme.io/api/generate-sale`
## Credentials
- Request body field `seller_payme_id` (required): MPL. Your private key in PayMe system.
## Overview
This endpoint allows the buyer to select the payment method prefered by him.
It will show your available payment methods, based on the added services in your account, in one payment page: Credit card, bit, ApplePay and GooglePay.
This endpoint can be used for the following actions:
Action | Description
----|----
Basic Sale (J4) | Allows you to create a sale.
Authorization (J5)| The requested amount gets reserved (blocked) on the credit card of the buyer for up to 168 hours.
You can find more information in our [Capture Sale Guide](https://docs-staging.payme.io/marketplaces-and-platforms/payments/capture-sale).
Template Payment Page | Enables many payments on a single sale link, by different buyers.
You can find more information in our [Template Payment Page Guide](https://docs-staging.payme.io/marketplaces-and-platforms/payments/multi-payment-page).
**See the request example below.**
#### Callbacks
Once the sale is paid successfully, we will notify the marketplace with the sale details with a POST of `type` `x-www-form-urlencoded` request to the marketplace Callback URL.
You can find the sale callback attributes [Sale Callbacks](https://docs-staging.payme.io/marketplaces-and-platforms/lists-statuses/sale-callbacks).
#### Issuing an Invoice for a Business
In the case where you are connected to our invoices services, you can send the following parameters as a part of your `generate-sale` API request to us when paying using a Token (saved card) in our platform.
Please add the following parameters to your request:
Parameter Name|Parameter Type|Example & Limitations
--|--|--
`buyer_business_name`| `string` | The name of the business the invoice should be issued for.
`buyer_business_code` | `integer` | The business code (VAT identifier) of the company the invoice is issued for.
## Parameters
This endpoint takes no path, query or header parameters.
## Request body
Content type: `application/json`
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `seller_payme_id` | string | yes | MPL. Your private key in PayMe system. |
| `sale_price` | number | yes | Sale final price. For example, if the price is 50.75 (max 2 decimal points) the value that needs to be sent is 5075. Note that the minimum value is 500. |
| `currency` | string | yes | Sale currency. [3-letter ISO 4217 name](https://en.wikipedia.org/wiki/ISO_4217). |
| `product_name` | string | yes | Short name and description of the product/service. This text will be shown in the invoice as well, if the seller has enabled the invoices module in his account panel. Limited to 500 characters |
| `transaction_id` | string | no | Merchant's unique sale ID for correlation with us |
| `installments` | string | no | Amount of installments for the sale. We allow you to manually set the number of installments or to specify a top limit of installments for the buyer to choose from while paying. Setting a fixed number of installments is simply entering a number between 1 and 12. The sale will be initiated with this number of installments and the buyer will not be able to change it. To set a range for the buyer to choose from, enter the following: `103` - allow up to 3 installments `106` - allow up to 6 installments `109` - allow up to 9 installments `112` - allow up to 12 installments |
| `market_fee` | number | no | A decimal representing the percent of the sale price that is collected for the marketplace (includes VAT). This fee is added on top of our fees and transferred to the marketplace once a month. Default value is the market fee of the Seller, as set upon Seller creation. |
| `sale_send_notification` | boolean | no | Flag to send email and/or SMS notifications |
| `sale_callback_url` | string | no | Callback response to your page regarding call to our API. Default value is taken from the Merchant's settings. Note that you may not send a "localhost" URL as value |
| `sale_email` | string | no | In case sale send notification is true provide the address to send email notification |
| `sale_return_url` | string | no | We will redirect the IFRAME and the buyer to this URL upon payment success. Default value is taken from the Merchant's settings |
| `sale_mobile` | string | no | In case sale send notification is true, provide the phone number to send SMS notification, if the seller has enabled the SMS module in his account panel |
| `sale_name` | string | no | The name that will be displayed when sending a notification |
| `buyer_perform_validation` | string | no | Flag for performing an online validation of the card with the Issuer. |
| `sale_type` | string | no | You can find all the sale types [Sale Types](https://docs-staging.payme.io/marketplaces-and-platforms/lists-statuses/sale-types). |
| `sale_payment_method` | string | no | The buyer will be able to select his payment method. |
| `layout` | string | no | IFRAME payment page layout. Optional attribute which may be used with "bit" sale_payment_method. Avai lable layouts are:dynamic, qr-sms or dynamic-loose dynamic loose removes the validation for the social ID and CVV. |
| `language` | string | no | Changes the language of the payment IFRAME to English, as well as the error messages. Default value is Hebrew (he) |
| `order_number` | string | no | Purchase Order Number. Mandatory for level 2 / 3 card data. Maximum length: 15 digits |
| `items` | array | no | This is an object that should include multiple arrays. An array for each product (item) that is a part of this sale. All parameters that are numeric or integer must be equal or more than 0. |
| `items[].name` | string | no | Name of the Item Minimum length: 1 Character Maximum length: 50 Characters |
| `items[].quantity` | integer | no | Number of items, Minimum length: 0 digits, Maximum length: 6 digits |
| `items[].unit_price` | integer | no | Price of single unit in pennies, No length limitations |
| `items[].unit_measurement` | string | no | Unit of measurment, Minimum length: 0 characters (nullable), Maximum length: 12 characters |
| `items[].total` | integer | no | Total Price After Discount, Minimum length: 0 digits, Maximum length: 10 digits |
| `items[].discount_total` | number | no | In negative pennies amount, Minimum length: 0 digits (nullable), Maximum length: 12 digits |
| `items[].description` | string | no | The item description, Minimum length: 0 characters (nullable, Maximum length: 150 characters |
| `items[].product_code` | string | no | The item catalog code. Minimum length: 0 characters (nullable), Maximum length: 100 characters |
| `items[].commodity_code` | number | no | The item's commodity code, Minimum length: 0 digits (nullable), Maximum length: unlimited |
| `fees` | object | no | Amount of tax in pennies No length |
| `fees.tax` | number | no | The tax collected as a part of the payment - In pennies, Minimum length: 0, Maximum Length: 12 Digits |
| `fees.duty` | number | no | The international fees collected as a part of the payment - In pennies, Minimum lenth: 0, Maximum Length: 12 Digits |
| `fees.discount` | number | no | The total discount given for the payment - In pennies, Minimum length: 0, Maximum Length: 12 Digits |
| `fees.shipping` | number | no | The shipping cost charged as a part of the payment - In pennies, Minimum lenth: 0, Maximum Length: 12 Digits |
| `shipping_details` | object | no | |
| `shipping_details.name` | string | no | Individual's full name/Company's name, Maximum Length: 50 Characters |
| `shipping_details.email` | string | no | Email address of the addressee, Maximum Length: 100 Characters |
| `shipping_details.phone` | string | no | Phone number of the addressee, Maximum Length: 50 Characters |
| `shipping_details.address` | object | no | Address Object |
| `shipping_details.address.line1` | string | no | Line 1 of the shipping address, No Limits. |
| `shipping_details.address.line2` | string | no | Line 1 of the shipping address, No Limits. |
| `shipping_details.address.postal_code` | string | no | Postal code of the shipping address, No Limits. |
| `shipping_details.address.city` | string | no | City of the shipping address, No Limits. |
| `shipping_details.address.state` | string | no | State of the shipping address, No Limits. |
| `shipping_details.address.country` | string | no | Country of the shipping address, No Limits. |
| `billing_details` | object | no | |
| `billing_details.name` | string | no | Individual's full name/Company's name, No Limits. |
| `billing_details.email` | string | no | Email address of the payer, No Limits. |
| `billing_details.phone` | string | no | Phone number of the payer, No Limits. |
| `billing_details.address` | object | no | |
| `billing_details.address.line1` | string | no | Line 1 of the billing address, No Limits. |
| `billing_details.address.line2` | string | no | Line 2 of the billing address, No Limits. |
| `billing_details.address.postal_code` | string | no | Postal code of the billing address No Limits. |
| `billing_details.address.city` | string | no | City of the billing address, No Limits. |
| `billing_details.address.state` | string | no | State of the shipping address, No Limits. |
| `billing_details.address.country` | string | no | Country of the billing address, No Limits. |
| `buyer_name` | string | no | Buyer's name |
| `buyer_email` | string | no | Buyer's email |
| `buyer_phone` | string | no | Buyer's phone |
### Request example
```json
{
"seller_payme_id": "MPLDEMO-MPLDEMO-MPLDEMO-1234567",
"sale_price": 1000,
"currency": "ILS",
"product_name": "Smartphone",
"transaction_id": "12345",
"installments": "1",
"market_fee": 0.5,
"sale_send_notification": true,
"sale_callback_url": "https://www.payme.io",
"sale_email": "test@payme.io",
"sale_return_url": "https://www.payme.io",
"sale_mobile": "+9725254448888",
"sale_name": "Test User",
"buyer_perform_validation": false,
"sale_type": "sale",
"sale_payment_method": "multi",
"language": "he"
}
```
## Code samples
### curl
```bash
curl -X POST 'https://sandbox.payme.io/api/generate-sale' \
-H 'Content-Type: application/json' \
--data-raw '{
"seller_payme_id": "MPLDEMO-MPLDEMO-MPLDEMO-1234567",
"sale_price": 1000,
"currency": "ILS",
"product_name": "Smartphone",
"transaction_id": "12345",
"installments": "1",
"market_fee": 0.5,
"sale_send_notification": true,
"sale_callback_url": "https://www.payme.io",
"sale_email": "test@payme.io",
"sale_return_url": "https://www.payme.io",
"sale_mobile": "+9725254448888",
"sale_name": "Test User",
"buyer_perform_validation": false,
"sale_type": "sale",
"sale_payment_method": "multi",
"language": "he"
}'
```
### Node.js
```javascript
const response = await fetch("https://sandbox.payme.io/api/generate-sale", {
method: "POST",
headers: {
"Content-Type": "application/json",
},
body: JSON.stringify({
"seller_payme_id": "MPLDEMO-MPLDEMO-MPLDEMO-1234567",
"sale_price": 1000,
"currency": "ILS",
"product_name": "Smartphone",
"transaction_id": "12345",
"installments": "1",
"market_fee": 0.5,
"sale_send_notification": true,
"sale_callback_url": "https://www.payme.io",
"sale_email": "test@payme.io",
"sale_return_url": "https://www.payme.io",
"sale_mobile": "+9725254448888",
"sale_name": "Test User",
"buyer_perform_validation": false,
"sale_type": "sale",
"sale_payment_method": "multi",
"language": "he"
}),
});
console.log(await response.text());
```
### Python
```python
import requests
response = requests.post(
"https://sandbox.payme.io/api/generate-sale",
json={
"seller_payme_id": "MPLDEMO-MPLDEMO-MPLDEMO-1234567",
"sale_price": 1000,
"currency": "ILS",
"product_name": "Smartphone",
"transaction_id": "12345",
"installments": "1",
"market_fee": 0.5,
"sale_send_notification": True,
"sale_callback_url": "https://www.payme.io",
"sale_email": "test@payme.io",
"sale_return_url": "https://www.payme.io",
"sale_mobile": "+9725254448888",
"sale_name": "Test User",
"buyer_perform_validation": False,
"sale_type": "sale",
"sale_payment_method": "multi",
"language": "he",
},
)
print(response.text)
```
### PHP
```php
'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;
```
## Responses
### 200 — Sale Created Successfully (success)
| Field | Type | Description |
| --- | --- | --- |
| `status_code` | number | Status of the request (0 - success, 1 - error) |
| `sale_url` | string | The URL of the IFRAME secured payment form to display to the buyer |
| `payme_sale_id` | string | Our unique sale ID |
| `payme_sale_code` | number | Our unique sale code (for display purposes only) |
| `price` | number | Sale final price. For example, if the price is 50.75 (max 2 decimal points) the value that needs to be sent is 5075 |
| `transaction_id` | string | Merchant's unique sale ID for correlation with us |
| `currency` | string | Sale currency. [3-letter ISO 4217 name](https://en.wikipedia.org/wiki/ISO_4217). |
```json
{
"status_code": 0,
"sale_url": "https://preprod.paymeservice.com/sale/generate/XXXXXXXX-XXXXXXXX-XXXXXXXX-XXXXXXXX",
"payme_sale_id": "XXXXXXXX-XXXXXXXX-XXXXXXXX-XXXXXXXX",
"payme_sale_code": 12345678,
"price": 10000,
"transaction_id": "12345",
"currency": "USD"
}
```
### 500 — Missing Required Information (error)
| Field | Type | Description |
| --- | --- | --- |
| `status_code` | number | |
| `status_error_details` | string | |
| `status_additional_info` | string | |
| `status_error_code` | number | |
```json
{
"status_code": 1,
"status_error_details": "קישור משתמש לא נמצא",
"status_additional_info": null,
"status_error_code": 251
}
```
## Hosted Fields - JSAPI
- [Generate Payment with Token](https://docs-staging.payme.io/payments/hosted-fields-jsapi/post-generate-sale-hosted-fields-jsapi): How to call POST /generate-sale for Hosted Fields - JSAPI.
# Generate Payment with Token
This is a variant of [POST /generate-sale — Generate Payment](https://docs-staging.payme.io/payments/hosted-payment-page/post-generate-sale); the request and responses below are the ones documented for Hosted Fields - JSAPI.
- Sandbox: `POST https://sandbox.payme.io/api/generate-sale`
- Production: `POST https://live.payme.io/api/generate-sale`
## Credentials
- Request body field `seller_payme_id` (required): MPL. Your private key in PayMe system.
## Overview
This endpoint can be used for the following actions:
Action | Description
----|----
Basic Sale (J4) | Allows you to create a sale.
Authorization (J5)| The requested amount gets reserved (blocked) on the credit card of the buyer for up to 168 hours.
You can find more information in our [Capture Sale Guide](https://docs-staging.payme.io/marketplaces-and-platforms/payments/capture-sale).
Please note that you have to create a payment with token (Buyer Key). That enables to capture token once the buyer pays (enter the payment details).
You can find more information in our [Create Payment With Buyer Key (Token) Guide](https://docs-staging.payme.io/marketplaces-and-platforms/payments/create-payment-with-buyer-key-token).
**See the request example below.**
* For all the sale types see [Sale Types](https://docs-staging.payme.io/marketplaces-and-platforms/lists-statuses/sale-types).
#### Callbacks
Once the sale is paid successfully, we will notify the marketplace with the sale details with a POST of `type` `x-www-form-urlencoded` request to the marketplace Callback URL.
You can find the sale callback attributes [Sale Callbacks](https://docs-staging.payme.io/marketplaces-and-platforms/lists-statuses/sale-callbacks).
#### Issuing an Invoice for a Business
In the case where you are connected to our invoices services, you can send the following parameters as a part of your `generate-sale` API request to us when paying using a Token (saved card) in our platform.
Please add the following parameters to your request:
Parameter Name|Parameter Type|Example & Limitations
--|--|--
`buyer_business_name`| `string` | The name of the business the invoice should be issued for.
`buyer_business_code` | `integer` | The business code (VAT identifier) of the company the invoice is issued for.
## Parameters
This endpoint takes no path, query or header parameters.
## Request body
Content type: `application/json`
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `seller_payme_id` | string | yes | MPL. Your private key in PayMe system. |
| `sale_price` | number | yes | Sale final price. For example, if the price is 50.75 (max 2 decimal points) the value that needs to be sent is 5075. Note that the minimum value is 500. |
| `currency` | string | yes | Sale currency. [3-letter ISO 4217 name](https://en.wikipedia.org/wiki/ISO_4217). |
| `product_name` | string | yes | Short name and description of the product/service. This text will be shown in the invoice as well, if the seller has enabled the invoices module in his account panel. Limited to 500 characters |
| `transaction_id` | string | no | Merchant's unique sale ID for correlation with us |
| `installments` | string | no | Amount of installments for the sale. We allow you to manually set the number of installments or to specify a top limit of installments for the buyer to choose from while paying. Setting a fixed number of installments is simply entering a number between 1 and 12. The sale will be initiated with this number of installments and the buyer will not be able to change it. To set a range for the buyer to choose from, enter the following: `103` - allow up to 3 installments `106` - allow up to 6 installments `109` - allow up to 9 installments `112` - allow up to 12 installments |
| `market_fee` | number | no | A decimal representing the percent of the sale price that is collected for the marketplace (includes VAT). This fee is added on top of our fees and transferred to the marketplace once a month. Default value is the market fee of the Seller, as set upon Seller creation. |
| `sale_send_notification` | boolean | no | Flag to send email and/or SMS notifications |
| `sale_callback_url` | string | no | Callback response to your page regarding call to our API. Default value is taken from the Merchant's settings. Note that you may not send a "localhost" URL as value |
| `sale_email` | string | no | In case sale send notification is true provide the address to send email notification |
| `sale_return_url` | string | no | We will redirect the IFRAME and the buyer to this URL upon payment success. Default value is taken from the Merchant's settings |
| `sale_mobile` | string | no | In case sale send notification is true, provide the phone number to send SMS notification, if the seller has enabled the SMS module in his account panel |
| `sale_name` | string | no | The name that will be displayed when sending a notification |
| `capture_buyer` | string | no | Flag for requesting the buyer's token for this payment (0 - do not capture token, 1 - capture token). For additional information see Tokens explanation below |
| `buyer_perform_validation` | boolean | no | Flag for performing an online validation of the card with the Issuer. |
| `sale_type` | string | no | You can find all the sale types [Sale Types](https://docs-staging.payme.io/marketplaces-and-platforms/lists-statuses/sale-types). |
| `sale_payment_method` | string | no | the Payment method used to pay the sale. For all the payment methods see [Available Payment Methods](https://docs-staging.payme.io/payments/direct-api/available-payment-methods). |
| `layout` | string | no | IFRAME payment page layout. Optional attribute which may be used with "bit" sale_payment_method. Avai lable layouts are:dynamic, qr-sms or dynamic-loose dynamic loose removes the validation for the social ID and CVV. |
| `language` | string | no | Changes the language of the payment IFRAME to English, as well as the error messages. Default value is Hebrew (he) |
| `order_number` | string | no | Purchase Order Number |
| `items` | array | no | This is an object that should include multiple arrays. An array for each product (item) that is a part of this sale. |
| `items[].name` | string | no | Name of the Item Minimum length: 1 Character Maximum length: 50 Characters |
| `items[].quantity` | integer | no | Number of items, Minimum length: 0 digits, Maximum length: 6 digits |
| `items[].unit_price` | integer | no | Price of single unit in pennies, No length limitations |
| `items[].unit_measurement` | string | no | Unit of measurment, Minimum length: 0 characters (nullable), Maximum length: 12 characters |
| `items[].total` | integer | no | Total Price After Discount, Minimum length: 0 digits, Maximum length: 10 digits |
| `items[].discount_total` | number | no | In negative pennies amount, Minimum length: 0 digits (nullable), Maximum length: 12 digits |
| `items[].description` | string | no | The item description, Minimum length: 0 characters (nullable, Maximum length: 150 characters |
| `items[].product_code` | string | no | The item catalog code. Minimum length: 0 characters (nullable), Maximum length: 100 characters |
| `items[].commodity_code` | number | no | The item's commodity code, Minimum length: 0 digits (nullable), Maximum length: unlimited |
| `fees` | object | no | Amount of tax in pennies |
| `fees.tax` | number | no | The tax collected as a part of the payment - In pennies, Minimum length: 0, Maximum Length: 12 Digits |
| `fees.duty` | number | no | The international fees collected as a part of the payment - In pennies, Minimum lenth: 0, Maximum Length: 12 Digits |
| `fees.discount` | number | no | The total discount given for the payment - In pennies, Minimum length: 0, Maximum Length: 12 Digits |
| `fees.shipping` | number | no | The shipping cost charged as a part of the payment - In pennies, Minimum lenth: 0, Maximum Length: 12 Digits |
| `shipping_details` | object | no | |
| `shipping_details.name` | string | no | Individual's full name/Company's name, Maximum Length: 50 Characters |
| `shipping_details.email` | string | no | Email address of the addressee, Maximum Length: 100 Characters |
| `shipping_details.phone` | string | no | Phone number of the addressee, Maximum Length: 50 Characters |
| `shipping_details.address` | object | no | Address Object |
| `shipping_details.address.line1` | string | no | Line 1 of the shipping address, No Limits. |
| `shipping_details.address.line2` | string | no | Line 1 of the shipping address, No Limits. |
| `shipping_details.address.postal_code` | string | no | Postal code of the shipping address, No Limits. |
| `shipping_details.address.city` | string | no | City of the shipping address, No Limits. |
| `shipping_details.address.state` | string | no | State of the shipping address, No Limits. |
| `shipping_details.address.country` | string | no | Country of the shipping address, No Limits. |
| `billing_details` | object | no | |
| `billing_details.name` | string | no | Individual's full name/Company's name, No Limits. |
| `billing_details.email` | string | no | Email address of the payer, No Limits. |
| `billing_details.phone` | string | no | Phone number of the payer, No Limits. |
| `billing_details.address` | object | no | |
| `billing_details.address.line1` | string | no | Line 1 of the billing address, No Limits. |
| `billing_details.address.line2` | string | no | Line 2 of the billing address, No Limits. |
| `billing_details.address.postal_code` | string | no | Postal code of the billing address No Limits. |
| `billing_details.address.city` | string | no | City of the billing address, No Limits. |
| `billing_details.address.state` | string | no | State of the shipping address, No Limits. |
| `billing_details.address.country` | string | no | Country of the billing address, No Limits. |
### Request example
```json
{
"seller_payme_id": "MPLDEMO-MPLDEMO-MPLDEMO-1234567",
"sale_price": 1000,
"currency": "ILS",
"product_name": "Smartphone",
"transaction_id": "12345",
"installments": "1",
"market_fee": 0.5,
"sale_send_notification": true,
"sale_callback_url": "https://www.payme.io",
"sale_email": "test@payme.io",
"sale_return_url": "https://www.payme.io",
"sale_mobile": "+9725254448888",
"sale_name": "Test User",
"capture_buyer": false,
"buyer_perform_validation": false,
"sale_type": "sale",
"sale_payment_method": "credit-card",
"layout": "string",
"language": "he"
}
```
## Code samples
### curl
```bash
curl -X POST 'https://sandbox.payme.io/api/generate-sale' \
-H 'Content-Type: application/json' \
--data-raw '{
"seller_payme_id": "MPLDEMO-MPLDEMO-MPLDEMO-1234567",
"sale_price": 1000,
"currency": "ILS",
"product_name": "Smartphone",
"transaction_id": "12345",
"installments": "1",
"market_fee": 0.5,
"sale_send_notification": true,
"sale_callback_url": "https://www.payme.io",
"sale_email": "test@payme.io",
"sale_return_url": "https://www.payme.io",
"sale_mobile": "+9725254448888",
"sale_name": "Test User",
"capture_buyer": false,
"buyer_perform_validation": false,
"sale_type": "sale",
"sale_payment_method": "credit-card",
"layout": "string",
"language": "he"
}'
```
### Node.js
```javascript
const response = await fetch("https://sandbox.payme.io/api/generate-sale", {
method: "POST",
headers: {
"Content-Type": "application/json",
},
body: JSON.stringify({
"seller_payme_id": "MPLDEMO-MPLDEMO-MPLDEMO-1234567",
"sale_price": 1000,
"currency": "ILS",
"product_name": "Smartphone",
"transaction_id": "12345",
"installments": "1",
"market_fee": 0.5,
"sale_send_notification": true,
"sale_callback_url": "https://www.payme.io",
"sale_email": "test@payme.io",
"sale_return_url": "https://www.payme.io",
"sale_mobile": "+9725254448888",
"sale_name": "Test User",
"capture_buyer": false,
"buyer_perform_validation": false,
"sale_type": "sale",
"sale_payment_method": "credit-card",
"layout": "string",
"language": "he"
}),
});
console.log(await response.text());
```
### Python
```python
import requests
response = requests.post(
"https://sandbox.payme.io/api/generate-sale",
json={
"seller_payme_id": "MPLDEMO-MPLDEMO-MPLDEMO-1234567",
"sale_price": 1000,
"currency": "ILS",
"product_name": "Smartphone",
"transaction_id": "12345",
"installments": "1",
"market_fee": 0.5,
"sale_send_notification": True,
"sale_callback_url": "https://www.payme.io",
"sale_email": "test@payme.io",
"sale_return_url": "https://www.payme.io",
"sale_mobile": "+9725254448888",
"sale_name": "Test User",
"capture_buyer": False,
"buyer_perform_validation": False,
"sale_type": "sale",
"sale_payment_method": "credit-card",
"layout": "string",
"language": "he",
},
)
print(response.text)
```
### PHP
```php
'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;
```
## Responses
### 200 — Sale Created Successfully (success)
| Field | Type | Description |
| --- | --- | --- |
| `status_code` | number | Status of the request (0 - success, 1 - error) |
| `sale_url` | string | The URL of the IFRAME secured payment form to display to the buyer |
| `payme_sale_id` | string | Our unique sale ID |
| `payme_sale_code` | number | Our unique sale code (for display purposes only) |
| `price` | number | Sale final price. For example, if the price is 50.75 (max 2 decimal points) the value that needs to be sent is 5075 |
| `transaction_id` | string | Merchant's unique sale ID for correlation with us |
| `currency` | string | Sale currency. 3-letter ISO 4217 name |
```json
{
"status_code": 0,
"sale_url": "https://preprod.paymeservice.com/sale/generate/XXXXXXXX-XXXXXXXX-XXXXXXXX-XXXXXXXX",
"payme_sale_id": "XXXXXXXX-XXXXXXXX-XXXXXXXX-XXXXXXXX",
"payme_sale_code": 12345678,
"price": 10000,
"transaction_id": "12345",
"currency": "USD"
}
```
### 500 — Missing Required Information (error)
| Field | Type | Description |
| --- | --- | --- |
| `status_code` | number | |
| `status_error_details` | string | |
| `status_additional_info` | string | |
| `status_error_code` | number | |
```json
{
"status_code": 1,
"status_error_details": "קישור משתמש לא נמצא",
"status_additional_info": null,
"status_error_code": 251
}
```
## Direct API
- [Available Payment Methods](https://docs-staging.payme.io/payments/direct-api/available-payment-methods): As PayMe offers different payment methods, you can use the `sale_payment_method` parameter in [`generate-sale`](https://docs-staging.payme.io/payments) to set your desired payment method.
# Payment Methods
As PayMe offers different payment methods, you can use the `sale_payment_method` parameter in [`generate-sale`](https://docs-staging.payme.io/payments) to set your desired payment method.
Payment Method | Payment Method Type | PayMe `payment_method` code | API Value
---|---|---|---
Credit Card | Card Payment | 1 | credit-card
Bank Transfer| Bank Transfer Payment | 2 | bank-transfer
PayPal| Card/Wallet Payment | 3 | paypal
Alipay QR| Wallet Payment | 4 | alipay-qr
Alipay Online| Wallet Payment | 5 | alipay-online
Funds Transfer| Bank Transfer Payment | 6 | funds-transfer
Cash | Cash Payment | 7 | cash
Cheque | Cheque Payment | 8 |cheque
eCheck | Online Bank Transfer | 9 | echeck
Bit| Wallet | 10 | bit
BACS| Online Bank Transfer | 11 | bacs
SEPA |Online Bank Transfer | 12 | sepa
ApplePay| Wallet| 14 | apple-pay
IL Direct Debit| Online Bank Transfer | 15 | il-direct-debit
Verifone Prepaid| Prepaid card | 16 | verifone-prepaid
GooglePay | Wallet | 18 | google-pay
- [Pay Sale](https://docs-staging.payme.io/payments/direct-api/post-pay-sale): POST /pay-sale — Pay Sale
# Pay Sale
- Sandbox: `POST https://sandbox.payme.io/api/pay-sale`
- Production: `POST https://live.payme.io/api/pay-sale`
## Credentials
- Request body field `seller_payme_id` (required): Our unique seller ID
## Overview
**This endpoint can be used only if you are using our Direct Integration method.**
This endpoint allows you to pay on a sale you created.
By sending this request, a few actions occur: the sale is processed, the buyer is charged, and you receive an asynchronous response with the sale data.
You can find more information in the following guide - [Direct API - How to create and pay sale](/marketplaces-and-platforms/integrations/direct-api-how-to-create-and-pay-sale).
## Parameters
This endpoint takes no path, query or header parameters.
## Request body
Content type: `application/json`
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `seller_payme_id` | string | yes | Our unique seller ID |
| `sale_price` | string | yes | Sale final price. For example, if the price is 50.75 (max 2 decimal points) the value that needs to be sent is 5075. Note that the minimum value is 500. |
| `currency` | string | yes | Sale currency. [3-letter ISO 4217 name](https://en.wikipedia.org/wiki/ISO_4217). |
| `installments` | string | yes | Amount of installments for the sale. |
| `language` | string | no | The language of the response and callback. |
| `sale_callback_url` | string | no | Callback response to your page regarding call to our API. Default value is taken from the Merchant's settings. Note that you may not send a "localhost" URL as value |
| `sale_return_url` | string | yes | Once the payment was completed successfully, the user will be redirected to this URL |
| `capture_buyer` | number | no | Flag for requesting the buyer's token for this payment (0 - do not capture token, 1 - capture token). For additional information see Tokens explanation below |
| `buyer_key` | string | yes | Buyer key for an instant-payment with the token. This key is received through the use of capture_buyer. Note that this attribute cannot co-exist with the capture_buyer parameter in the same request |
| `payme_sale_id` | string | yes | Our unique sale ID |
| `credit_card_number` | number | yes | The card the transaction will be paid with. |
| `credit_card_exp` | string | yes | The expiration date of the card used to pay for the transaction (MM/YY) |
| `credit_card_cvv` | string | yes | The CVV of the card used to pay for the transaction. (3/4 digit code) |
### Request example
```json
{
"seller_payme_id": "string",
"sale_price": "string",
"currency": "string",
"installments": "string",
"sale_return_url": "string",
"capture_buyer": 0,
"buyer_key": "string",
"payme_sale_id": "string",
"credit_card_number": 0,
"credit_card_exp": "string",
"credit_card_cvv": 0
}
```
## Code samples
### curl
```bash
curl -X POST 'https://sandbox.payme.io/api/pay-sale' \
-H 'Content-Type: application/json' \
--data-raw '{
"seller_payme_id": "string",
"sale_price": "string",
"currency": "string",
"installments": "string",
"sale_return_url": "string",
"capture_buyer": 0,
"buyer_key": "string",
"payme_sale_id": "string",
"credit_card_number": 0,
"credit_card_exp": "string",
"credit_card_cvv": 0
}'
```
### Node.js
```javascript
const response = await fetch("https://sandbox.payme.io/api/pay-sale", {
method: "POST",
headers: {
"Content-Type": "application/json",
},
body: JSON.stringify({
"seller_payme_id": "string",
"sale_price": "string",
"currency": "string",
"installments": "string",
"sale_return_url": "string",
"capture_buyer": 0,
"buyer_key": "string",
"payme_sale_id": "string",
"credit_card_number": 0,
"credit_card_exp": "string",
"credit_card_cvv": 0
}),
});
console.log(await response.text());
```
### Python
```python
import requests
response = requests.post(
"https://sandbox.payme.io/api/pay-sale",
json={
"seller_payme_id": "string",
"sale_price": "string",
"currency": "string",
"installments": "string",
"sale_return_url": "string",
"capture_buyer": 0,
"buyer_key": "string",
"payme_sale_id": "string",
"credit_card_number": 0,
"credit_card_exp": "string",
"credit_card_cvv": 0,
},
)
print(response.text)
```
### PHP
```php
'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;
```
## Responses
### 200 — OK (success)
| Field | Type | Description |
| --- | --- | --- |
| `status_code` | number | Status of the capture request (0 - success, 1 - error) |
| `payme_status` | string | PayMe's payment status (success/failure) |
| `payme_sale_id` | string | PayMe's unique Sale ID |
| `payme_sale_code` | number | PayMe's unique Sale code |
| `sale_created` | string | The date the sale was created (timestamp) |
| `payme_sale_status` | string | PayMe's sale status |
| `sale_status` | string | Sale status |
| `currency` | string | Sale currency. 3-letter ISO 4217 name |
| `transaction_id` | string | Transaction ID |
| `is_token_sale` | boolean | Was the card tokenized or not |
| `price` | number | Payment price |
| `payme_signature` | string | PayMe's signature for the payment |
| `payme_transaction_id` | string | PayMe transaction ID |
| `payme_transaction_total` | string | Transaction total amount |
| `payme_transaction_card_brand` | string | The card brand |
| `payme_transaction_auth_number` | string | Transaction authorization number |
| `payme_transaction_voucher` | string | PayMe's transaction voucher |
| `buyer_name` | string | Buyer's full name |
| `buyer_email` | string | Buyer's email address |
| `buyer_phone` | string | Buyer's phone number |
| `buyer_card_mask` | string | Card mask |
| `buyer_card_exp` | string | Buyer's card expiration date |
| `buyer_card_is_foreign` | boolean | Is the card foreign or domestic? (For IL Sellers only) |
| `buyer_social_id` | string | Buyer's social ID number |
| `installments` | number | Number of installments used for the payment |
| `sale_paid_date` | string | Sale paid date |
```json
{
"status_code": 0,
"redirect_url": null,
"payme_status": "string",
"status_error_code": 0,
"payme_sale_id": "string",
"payme_sale_code": 0,
"sale_created": "string",
"payme_sale_status": "string",
"sale_status": "string",
"currency": "string",
"transaction_id": "string",
"is_token_sale": true,
"price": 0,
"payme_signature": "string",
"payme_transaction_id": "string",
"payme_transaction_total": "string",
"payme_transaction_card_brand": "string",
"payme_transaction_auth_number": "string",
"payme_transaction_voucher": "string",
"buyer_name": "string",
"buyer_email": "string",
"buyer_phone": null,
"buyer_card_mask": "string",
"buyer_card_exp": "string",
"buyer_card_is_foreign": true,
"buyer_social_id": null,
"installments": 0,
"sale_paid_date": "string",
"sale_release_date": null
}
```
### 500 — Internal Server Error (error)
| Field | Type | Description |
| --- | --- | --- |
| `status_code` | number | |
| `status_error_details` | string | |
| `status_additional_info` | string | |
| `status_error_code` | number | |
```json
{
"status_code": 0,
"status_error_details": "string",
"status_additional_info": "string",
"status_error_code": 0
}
```
## Point of Sale (POS)
- [Order New POS Device](https://docs-staging.payme.io/payments/point-of-sale-pos/post-vas-enable): POST /vas-enable — Order New POS Device
# Order New POS Device
- Sandbox: `POST https://sandbox.payme.io/api/vas-enable`
- Production: `POST https://live.payme.io/api/vas-enable`
## Credentials
- Request body field `payme_client_key` (required): The PayMe Secret Client Key
- Request body field `seller_payme_id` (required): The unique seller identifier (MPL).
## Overview
In order to be initiate the process of receiving a physical Point Of Sale (POS) device, you will first need to generate a new request to `https://.payme.io/api/vas-enable` using your personal VAS identifier.
Once the VAS is activated, the process will be initiated and the following operations will take place:
1. New terminal request (takes up to 5 business days)
2. Physical device internal preparation (Immediate once terminal is ready)
The API request for activating the service will look as follows:
### 1st step
Add the payment method via `vas-enable`
```
{
"payme_client_key": "payme_client_key",
"seller_payme_id": "seller_payme_id",
"vas_payme_id": "vas_payme_id"
}
```
### 2nd step
Add the device type via `vas-enable`
```
{
"payme_client_key": "payme",
"seller_payme_id":"MPL15991-MPL15991-MPL15991-MPL15991",
"vas_payme_id": "VASL1545-8192915E-8192915E-8192915E",
"extend_items": true,
"vas_data": {
"number_of_devices": 3,
"items":[
{
"pos_id": "123",
"shipping_address": "address of shipping",
"name": "name of the device"
},
{
"pos_id": "123",
"shipping_address": "address of shipping",
"name": "name of the device"
}
]
}
}
```
Once the VAS is activated, the process will be synchronous and there's no further action required to be completed by the partner or seller until receiving the device and starting to process immidiately.
## Parameters
This endpoint takes no path, query or header parameters.
## Request body
Content type: `application/json`
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `payme_client_key` | string | yes | The PayMe Secret Client Key |
| `seller_payme_id` | string | yes | The unique seller identifier (MPL). |
| `vas_payme_id` | string | yes | The unique activation key. |
| `vas_data` | object | yes | The predefined data object that allows you to request specific device amount and a per device information. |
| `vas_data.number_of_devices` | integer | yes | The number of requested devices. |
| `vas_data.items` | array | yes | The devices array. The items count must be equal to `number_of_devices` value. |
| `vas_data.items[].pos_id` | string | yes | The unique POS ID. This ID will be used in order to send payment request to the specific device. |
| `vas_data.items[].shipping_address` | string | yes | The shipping address for the physical device. |
| `vas_data.items[].name` | string | yes | The name of the device. Will be used internally for the setup process. |
| `extend_items` | boolean | yes | |
### Request example
```json
{
"payme_client_key": "icount",
"seller_payme_id": "MPL90009-90009EXM-EXAMPLE0-EXAMPLE9",
"vas_payme_id": "VASL1545-8192915E-5NTSEUM1-03YNFWNU",
"vas_data": {
"number_of_devices": 3,
"items": [
{
"pos_id": "123",
"shipping_address": "address of shipping",
"name": "name of the device"
},
{
"pos_id": "123",
"shipping_address": "address of shipping",
"name": "name of the device"
}
]
}
}
```
## Code samples
### curl
```bash
curl -X POST 'https://sandbox.payme.io/api/vas-enable' \
-H 'Content-Type: application/json' \
--data-raw '{
"payme_client_key": "icount",
"seller_payme_id": "MPL90009-90009EXM-EXAMPLE0-EXAMPLE9",
"vas_payme_id": "VASL1545-8192915E-5NTSEUM1-03YNFWNU",
"vas_data": {
"number_of_devices": 3,
"items": [
{
"pos_id": "123",
"shipping_address": "address of shipping",
"name": "name of the device"
},
{
"pos_id": "123",
"shipping_address": "address of shipping",
"name": "name of the device"
}
]
}
}'
```
### Node.js
```javascript
const response = await fetch("https://sandbox.payme.io/api/vas-enable", {
method: "POST",
headers: {
"Content-Type": "application/json",
},
body: JSON.stringify({
"payme_client_key": "icount",
"seller_payme_id": "MPL90009-90009EXM-EXAMPLE0-EXAMPLE9",
"vas_payme_id": "VASL1545-8192915E-5NTSEUM1-03YNFWNU",
"vas_data": {
"number_of_devices": 3,
"items": [
{
"pos_id": "123",
"shipping_address": "address of shipping",
"name": "name of the device"
},
{
"pos_id": "123",
"shipping_address": "address of shipping",
"name": "name of the device"
}
]
}
}),
});
console.log(await response.text());
```
### Python
```python
import requests
response = requests.post(
"https://sandbox.payme.io/api/vas-enable",
json={
"payme_client_key": "icount",
"seller_payme_id": "MPL90009-90009EXM-EXAMPLE0-EXAMPLE9",
"vas_payme_id": "VASL1545-8192915E-5NTSEUM1-03YNFWNU",
"vas_data": {
"number_of_devices": 3,
"items": [
{
"pos_id": "123",
"shipping_address": "address of shipping",
"name": "name of the device",
},
{
"pos_id": "123",
"shipping_address": "address of shipping",
"name": "name of the device",
},
],
},
},
)
print(response.text)
```
### PHP
```php
'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;
```
## Responses
### 200 — OK (success)
| Field | Type | Description |
| --- | --- | --- |
| `status_code` | string | The status code. |
| `seller_payme_id` | string | The unique seller ID. |
| `message` | string | The message for either success of failure. |
```json
{
"status_code": 2,
"seller_payme_id": "MPL00010-00010EXM-EXAMPLE0-EXAMPLE0",
"message": "Zendesk ticket created"
}
```
- [Pair New Device](https://docs-staging.payme.io/payments/point-of-sale-pos/post-pair): POST /vas/pos/pair — Pair New Device
# Pair New Device
- Sandbox: `POST https://sandbox.payme.io/api/vas/pos/pair`
- Production: `POST https://live.payme.io/api/vas/pos/pair`
## Credentials
- Request body field `payme_client_key` (required): Your private API Key
- Request body field `seller_payme_id` (required): Your Merchant's unique ID in our system
## Overview
This method is used to pair a stand-alone terminal to a POS/ECR. Each stand-alone terminal has a unique ID that is used in the paring process, this method is called first and then the pairing process is finalized by calling the authenticate method. Target URLs
As a part of the pairing process, the devices will be numbered automatically - The first device - 001 and onwards.
When initiating a payment request, you will need to use this identifier and mention it as a part of the API endpoint `sales` request.
## Parameters
This endpoint takes no path, query or header parameters.
## Request body
Content type: `application/json`
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `payme_client_key` | string | yes | Your private API Key |
| `seller_payme_id` | string | yes | Your Merchant's unique ID in our system |
| `pos_id` | string | yes | The ID you must choose for your POS. Must be a string of digits, between "001" and "999" |
| `terminal_id` | string | yes | A unique payment terminal identifier, this ID is displayed on the POS in the pairing process |
| `name` | string | no | The name of the POS, this will be displayed on the devices screen. Usually this is the Merchant's name |
### Request example
```json
{
"payme_client_key": "partner_key",
"seller_payme_id": "MPLXXXXX-XXXXXXXX-XXXXXXXX-XXXXXXXX",
"pos_id": "001",
"terminal_id": "9000015000",
"name": "John Doe"
}
```
## Code samples
### curl
```bash
curl -X POST 'https://sandbox.payme.io/api/vas/pos/pair' \
-H 'Content-Type: application/json' \
--data-raw '{
"payme_client_key": "partner_key",
"seller_payme_id": "MPLXXXXX-XXXXXXXX-XXXXXXXX-XXXXXXXX",
"pos_id": "001",
"terminal_id": "9000015000",
"name": "John Doe"
}'
```
### Node.js
```javascript
const response = await fetch("https://sandbox.payme.io/api/vas/pos/pair", {
method: "POST",
headers: {
"Content-Type": "application/json",
},
body: JSON.stringify({
"payme_client_key": "partner_key",
"seller_payme_id": "MPLXXXXX-XXXXXXXX-XXXXXXXX-XXXXXXXX",
"pos_id": "001",
"terminal_id": "9000015000",
"name": "John Doe"
}),
});
console.log(await response.text());
```
### Python
```python
import requests
response = requests.post(
"https://sandbox.payme.io/api/vas/pos/pair",
json={
"payme_client_key": "partner_key",
"seller_payme_id": "MPLXXXXX-XXXXXXXX-XXXXXXXX-XXXXXXXX",
"pos_id": "001",
"terminal_id": "9000015000",
"name": "John Doe",
},
)
print(response.text)
```
### PHP
```php
'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;
```
## Responses
### 200 — OK (success)
| Field | Type | Description |
| --- | --- | --- |
| `status_code` | number | Status of the request (0: success, otherwise error) |
```json
{
"status_code": 0
}
```
### 500 — Internal Server Error (error)
| Field | Type | Description |
| --- | --- | --- |
| `status_code` | number | Status of the request (0: success, otherwise error) |
| `status_error_details` | string | Error message to the client |
| `status_additional_info` | string | Additional error information |
| `status_error_code` | number | Our unique error code |
```json
{
"status_code": 1,
"status_error_details": "Wrong terminalID",
"status_additional_info": null,
"status_error_code": -1001
}
```
- [Authenticate New Device](https://docs-staging.payme.io/payments/point-of-sale-pos/post-authenticate): POST /vas/pos/authenticate — Authenticate New Device
# Authenticate New Device
- Sandbox: `POST https://sandbox.payme.io/api/vas/pos/authenticate`
- Production: `POST https://live.payme.io/api/vas/pos/authenticate`
## Credentials
- Request body field `payme_client_key` (required): Your private API Key
- Request body field `seller_payme_id` (required): Your Merchant's unique ID in our system
## Overview
This method completes the pairing process started with the pair method.
## Parameters
This endpoint takes no path, query or header parameters.
## Request body
Content type: `application/json`
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `payme_client_key` | string | yes | Your private API Key |
| `seller_payme_id` | string | yes | Your Merchant's unique ID in our system |
| `pos_id` | string | yes | The ID you must choose for your POS. Must be a string of digits, between "001" and "999" |
| `terminal_id` | string | yes | A unique payment terminal identifier, this ID is displayed on the POS in the pairing process |
| `verification_code` | string | no | OTP as displayed on the POS device |
### Request example
```json
{
"payme_client_key": "partner_key",
"seller_payme_id": "MPLXXXXX-XXXXXXXX-XXXXXXXX-XXXXXXXX",
"pos_id": "001",
"terminal_id": "9000015000",
"verification_code": "123987"
}
```
## Code samples
### curl
```bash
curl -X POST 'https://sandbox.payme.io/api/vas/pos/authenticate' \
-H 'Content-Type: application/json' \
--data-raw '{
"payme_client_key": "partner_key",
"seller_payme_id": "MPLXXXXX-XXXXXXXX-XXXXXXXX-XXXXXXXX",
"pos_id": "001",
"terminal_id": "9000015000",
"verification_code": "123987"
}'
```
### Node.js
```javascript
const response = await fetch("https://sandbox.payme.io/api/vas/pos/authenticate", {
method: "POST",
headers: {
"Content-Type": "application/json",
},
body: JSON.stringify({
"payme_client_key": "partner_key",
"seller_payme_id": "MPLXXXXX-XXXXXXXX-XXXXXXXX-XXXXXXXX",
"pos_id": "001",
"terminal_id": "9000015000",
"verification_code": "123987"
}),
});
console.log(await response.text());
```
### Python
```python
import requests
response = requests.post(
"https://sandbox.payme.io/api/vas/pos/authenticate",
json={
"payme_client_key": "partner_key",
"seller_payme_id": "MPLXXXXX-XXXXXXXX-XXXXXXXX-XXXXXXXX",
"pos_id": "001",
"terminal_id": "9000015000",
"verification_code": "123987",
},
)
print(response.text)
```
### PHP
```php
'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;
```
## Responses
### 200 — OK (success)
- [New POS Payment](https://docs-staging.payme.io/payments/point-of-sale-pos/post-payment): POST /sales — New POS Payment
# New POS Payment
- Sandbox: `POST https://sandbox.payme.io/api/sales`
- Production: `POST https://live.payme.io/api/sales`
## Credentials
- Request body field `seller_payme_id` (required): PayMe's unqiue seller ID
## Overview
Calling this method will "push" a payment request to the POS, synchronously awaiting the payment result.
## Parameters
This endpoint takes no path, query or header parameters.
## Request body
Content type: `application/json`
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `seller_payme_id` | string | yes | PayMe's unqiue seller ID |
| `product_name` | string | yes | Product's description |
| `sale_price` | number | yes | Sale Price |
| `sale_type` | string | no | You can find all the sale types [Sale Types](/marketplaces-and-platforms/lists-statuses/sale-types). |
| `currency` | string | no | Sale currency. [3-letter ISO 4217 name](https://en.wikipedia.org/wiki/ISO_4217). |
| `transaction_id` | string | yes | Transaction ID |
| `sale_callback_url` | string | yes | Sale Callback URL |
| `payment` | object | yes | |
| `payment.method` | string | yes | Payment method |
| `payment.pos_id` | string | yes | The ID you must choose for your POS. Must be a string of digits, between "001" and "999" |
| `customer` | object | no | The customer object is **not** mandatory. **If this object is added** to the request, it should include its **required fields**: name, email and phone. |
| `customer.name` | string | no | Customer name |
| `customer.email` | string | no | Customer email |
| `customer.zip_code` | string | no | Customer address zip code |
| `customer.phone` | string | no | Customer mobile phone number |
| `customer.social_id` | string | no | Customer social ID / national ID for additional verification |
| `language` | string | no | Customer language |
### Request example
```json
{
"seller_payme_id": "MPLXXXXX-XXXXXXXX-XXXXXXXX-XXXXXXXX",
"product_name": "My Product",
"sale_price": 10000,
"currency": "USD",
"transaction_id": "12345",
"sale_callback_url": "https://www.example.com/payment/callback",
"payment": {
"method": "emv",
"pos_id": "001"
},
"customer": {
"name": "John Due",
"email": "test@test.com",
"phone": "+498963648018"
},
"language": "en"
}
```
## Code samples
### curl
```bash
curl -X POST 'https://sandbox.payme.io/api/sales' \
-H 'Content-Type: application/json' \
--data-raw '{
"seller_payme_id": "MPLXXXXX-XXXXXXXX-XXXXXXXX-XXXXXXXX",
"product_name": "My Product",
"sale_price": 10000,
"currency": "USD",
"transaction_id": "12345",
"sale_callback_url": "https://www.example.com/payment/callback",
"payment": {
"method": "emv",
"pos_id": "001"
},
"customer": {
"name": "John Due",
"email": "test@test.com",
"phone": "+498963648018"
},
"language": "en"
}'
```
### Node.js
```javascript
const response = await fetch("https://sandbox.payme.io/api/sales", {
method: "POST",
headers: {
"Content-Type": "application/json",
},
body: JSON.stringify({
"seller_payme_id": "MPLXXXXX-XXXXXXXX-XXXXXXXX-XXXXXXXX",
"product_name": "My Product",
"sale_price": 10000,
"currency": "USD",
"transaction_id": "12345",
"sale_callback_url": "https://www.example.com/payment/callback",
"payment": {
"method": "emv",
"pos_id": "001"
},
"customer": {
"name": "John Due",
"email": "test@test.com",
"phone": "+498963648018"
},
"language": "en"
}),
});
console.log(await response.text());
```
### Python
```python
import requests
response = requests.post(
"https://sandbox.payme.io/api/sales",
json={
"seller_payme_id": "MPLXXXXX-XXXXXXXX-XXXXXXXX-XXXXXXXX",
"product_name": "My Product",
"sale_price": 10000,
"currency": "USD",
"transaction_id": "12345",
"sale_callback_url": "https://www.example.com/payment/callback",
"payment": {
"method": "emv",
"pos_id": "001",
},
"customer": {
"name": "John Due",
"email": "test@test.com",
"phone": "+498963648018",
},
"language": "en",
},
)
print(response.text)
```
### PHP
```php
'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;
```
## Responses
### 200 — OK (success)
| Field | Type | Description |
| --- | --- | --- |
| `status_code` | integer | PayMe's payment status (success/failure) |
| `payme_status` | string | PayMe's payment status (success/failure) |
| `payme_sale_id` | string | PayMe's unique Sale ID |
| `payme_sale_code` | integer | PayMe's unique Sale code |
| `sale_created` | string | The date the sale was created (timestamp) |
| `payme_sale_status` | string | PayMe's sale status |
| `sale_status` | string | Sale status |
| `currency` | string | Sale currency. [3-letter ISO 4217 name](https://en.wikipedia.org/wiki/ISO_4217). |
| `transaction_id` | string | Transaction ID |
| `is_token_sale` | boolean | Was the card tokenized or not |
| `price` | integer | Payment price |
| `payme_signature` | string | PayMe's signature for the payment |
| `sale_description` | string | Sale description |
| `payme_transaction_id` | string | PayMe transaction ID |
| `payme_transaction_total` | string | Transaction total amount |
| `payme_transaction_card_brand` | string | The card brand |
| `payme_transaction_auth_number` | string | Transaction authorization number |
| `buyer_name` | string | Buyer's full name |
| `buyer_email` | string | Buyer's email address |
| `buyer_phone` | string | Buyer's phone number |
| `buyer_card_mask` | string | Card mask |
| `buyer_card_exp` | string | Buyer's card expiration date |
| `buyer_card_is_foreign` | boolean | Is the card foreign or domestic? (For IL Sellers only) |
| `buyer_social_id` | string | Buyer's social ID number |
| `installments` | integer | Number of installments used for the payment |
| `sale_paid_date` | string | Sale paid date |
```json
{
"status_code": 0,
"payme_status": "success",
"status_error_code": 0,
"payme_sale_id": "SALE1688-XXXXXXXX-XXXXXXXX-XXXXXXXX",
"payme_sale_code": 12346578,
"sale_created": "2023-06-29 13:33:54",
"payme_sale_status": "authorized",
"sale_status": "authorized",
"currency": "ILS",
"transaction_id": "string",
"is_token_sale": false,
"price": 100,
"payme_signature": "db1c276**********c5b39",
"sale_description": "bbb",
"sale_deferred_months": null,
"payme_transaction_id": "TRAN1688-034834SZ-OYNALKNE-DWOXFEUZ",
"payme_transaction_total": "100",
"payme_transaction_card_brand": "Mastercard",
"payme_transaction_auth_number": "12345678",
"payme_transaction_voucher": null,
"payme_transaction_emv_uid": "2306**********102613",
"payme_transaction_acquirer": "PayMe",
"payme_transaction_auth_source": "CreditCompany",
"payme_transaction_card_issuer": "Isracard",
"payme_transaction_credit_type": "RegularCredit",
"buyer_name": "First Name",
"buyer_email": "test@example.com",
"buyer_phone": "+15417543010",
"buyer_card_mask": "532610******5846",
"buyer_card_exp": "0426",
"buyer_card_is_foreign": false,
"buyer_social_id": "123456782",
"installments": 1,
"transaction_first_payment": "100",
"transaction_periodical_payment": 0,
"transaction_arn": "2306**********2613",
"sale_paid_date": "2023-06-29 13:33:54",
"sale_release_date": null,
"sale_3ds": false,
"redirect_url": null
}
```
### 500 — Internal Server Error (error)
| Field | Type | Description |
| --- | --- | --- |
| `status_code` | number | Status of the request (0 - success, 1 - error) |
| `status_error_details` | string | Error message |
| `status_additional_info` | string | Additional error information |
| `status_error_code` | number | Our unique error code |
```json
{
"status_code": 1,
"status_error_details": "קישור משתמש לא נמצא",
"status_additional_info": null,
"status_error_code": 251
}
```
- [Refund POS Sale](https://docs-staging.payme.io/payments/point-of-sale-pos/put-sales): PUT /sales — Refund POS Sale
# Refund POS Sale
- Sandbox: `PUT https://sandbox.payme.io/api/sales`
- Production: `PUT https://live.payme.io/api/sales`
## Credentials
- Request body field `seller_payme_id` (optional): PayMe's unqiue seller ID
In order to refund a sale paid via a POS device, you can use PUT function which will trigger a manual refund request sent back to the device.
### You will need to chain the sale GUID unique identifier to the endpoint URL in the following form:
`https://.payme.io/api/sales/{sale_guid}`
#### Example:
`https://.payme.io/api/sales/SALEGUID-TEST123-TEST123-TEST123`
The request will trigger a refund that will be sent to the designated device per the device ID mentioned in the request (see request example below)
## Parameters
This endpoint takes no path, query or header parameters.
## Request body
Content type: `application/json`
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `seller_payme_id` | string | no | PayMe's unqiue seller ID |
| `product_name` | string | no | Product's description |
| `currency` | string | no | Sale currency. [3-letter ISO 4217 name](https://en.wikipedia.org/wiki/ISO_4217). |
| `transaction_id` | string | no | The external transaction ID. |
| `sale_callback_url` | string | no | The callback url for the specific sale. |
| `payment` | object | no | The payment object. |
| `payment.method` | string | no | The payment method. |
| `payment.pos_id` | string | no | The POS ID - the device that will be used to process the refund request. |
| `payment.action` | string | no | The action - must be `refund` in order to complete this action. |
| `payment.amount` | string | no | The sale amount in Agorot |
| `language` | string | no | The language of the customer's interface. |
### Request example
```json
{
"seller_payme_id": "string",
"sale_price": 0,
"currency": "USD",
"payment": {
"method": "pos",
"pos_id": "002",
"action": "refund"
},
"customer": {
"name": "string",
"email": "string",
"phone": "string",
"zip_code": "string",
"social_id": "string"
},
"language": "he"
}
```
## Code samples
### curl
```bash
curl -X PUT 'https://sandbox.payme.io/api/sales' \
-H 'Content-Type: application/json' \
--data-raw '{
"seller_payme_id": "string",
"sale_price": 0,
"currency": "USD",
"payment": {
"method": "pos",
"pos_id": "002",
"action": "refund"
},
"customer": {
"name": "string",
"email": "string",
"phone": "string",
"zip_code": "string",
"social_id": "string"
},
"language": "he"
}'
```
### Node.js
```javascript
const response = await fetch("https://sandbox.payme.io/api/sales", {
method: "PUT",
headers: {
"Content-Type": "application/json",
},
body: JSON.stringify({
"seller_payme_id": "string",
"sale_price": 0,
"currency": "USD",
"payment": {
"method": "pos",
"pos_id": "002",
"action": "refund"
},
"customer": {
"name": "string",
"email": "string",
"phone": "string",
"zip_code": "string",
"social_id": "string"
},
"language": "he"
}),
});
console.log(await response.text());
```
### Python
```python
import requests
response = requests.put(
"https://sandbox.payme.io/api/sales",
json={
"seller_payme_id": "string",
"sale_price": 0,
"currency": "USD",
"payment": {
"method": "pos",
"pos_id": "002",
"action": "refund",
},
"customer": {
"name": "string",
"email": "string",
"phone": "string",
"zip_code": "string",
"social_id": "string",
},
"language": "he",
},
)
print(response.text)
```
### PHP
```php
'PUT',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;
```
## Responses
### 200 — OK (success)
| Field | Type | Description |
| --- | --- | --- |
| `status_code` | integer | PayMe's payment status (success/failure) |
| `payme_status` | string | Sale status |
| `payme_sale_id` | string | PayMe's unique Sale ID |
| `payme_sale_code` | integer | PayMe's unique Sale code |
| `sale_created` | string | The date the sale was created (timestamp) |
| `payme_sale_status` | string | PayMe's sale status |
| `sale_status` | string | Sale status |
| `currency` | string | Sale currency. [3-letter ISO 4217 name](https://en.wikipedia.org/wiki/ISO_4217). |
| `transaction_id` | string | Transaction ID |
| `is_token_sale` | boolean | Was the card tokenized or not |
| `price` | integer | Payment price |
| `payme_signature` | string | PayMe's signature for the payment |
| `sale_description` | string | Sale description |
| `payme_transaction_id` | string | PayMe transaction ID |
| `payme_transaction_total` | string | Transaction total amount |
| `payme_transaction_card_brand` | string | The card brand |
| `payme_transaction_auth_number` | string | Transaction authorization number |
| `buyer_name` | string | Buyer's full name |
| `buyer_email` | string | Buyer's email address |
| `buyer_phone` | string | Buyer's phone number |
| `buyer_card_mask` | string | Card mask |
| `buyer_card_exp` | string | Buyer's card expiration date |
| `buyer_card_is_foreign` | boolean | Is the card foreign or domestic? (For IL Sellers only) |
| `buyer_social_id` | string | Buyer's social ID number |
| `installments` | integer | Number of installments used for the payment |
| `sale_paid_date` | string | Sale paid date |
```json
{
"status_code": 0,
"payme_status": "success",
"status_error_code": 0,
"payme_sale_id": "SALE1688-XXXXXXXX-XXXXXXXX-XXXXXXXX",
"payme_sale_code": 12346578,
"sale_created": "2023-06-29 13:33:54",
"payme_sale_status": "authorized",
"sale_status": "authorized",
"currency": "ILS",
"transaction_id": "string",
"is_token_sale": false,
"price": 100,
"payme_signature": "db1c276**********c5b39",
"sale_description": "bbb",
"sale_deferred_months": null,
"payme_transaction_id": "TRAN1688-034834SZ-OYNALKNE-DWOXFEUZ",
"payme_transaction_total": "100",
"payme_transaction_card_brand": "Mastercard",
"payme_transaction_auth_number": "12345678",
"payme_transaction_voucher": null,
"payme_transaction_emv_uid": "2306**********102613",
"payme_transaction_acquirer": "PayMe",
"payme_transaction_auth_source": "CreditCompany",
"payme_transaction_card_issuer": "Isracard",
"payme_transaction_credit_type": "RegularCredit",
"buyer_name": "First Name",
"buyer_email": "test@example.com",
"buyer_phone": "+15417543010",
"buyer_card_mask": "532610******5846",
"buyer_card_exp": "0426",
"buyer_card_is_foreign": false,
"buyer_social_id": "123456782",
"installments": 1,
"transaction_first_payment": "100",
"transaction_periodical_payment": 0,
"transaction_arn": "2306**********2613",
"sale_paid_date": "2023-06-29 13:33:54",
"sale_release_date": null,
"sale_3ds": false,
"redirect_url": null
}
```
## Post Sale Actions
- [Refund Sale](https://docs-staging.payme.io/payments/post-sale-actions/post-refund-sale): POST /refund-sale — Refund Sale
# Refund Sale
- Sandbox: `POST https://sandbox.payme.io/api/refund-sale`
- Production: `POST https://live.payme.io/api/refund-sale`
## Credentials
- Request body field `payme_client_key` (optional): PayMe partner key. Only partners (platforms managing many sellers) have one; a merchant authenticates with seller_payme_id alone. Can also be sent in the PayMe-Partner-Key header.
- Request body field `seller_payme_id` (required): MPL. Your private key in PayMe system.
## Overview
Refund request enable you to reimburse a charge that was previously generated but remains unreimbursed. The funds will be returned to the initial payment method used for the charge.
### Callback
Once the sale is refunded successfully, we will update the marketplace with the sale details with a POST request of type `x-www-form-urlencoded` to the marketplace Callback URL.
#### Note:
You can refund multiple times per sale as long as you do not exceed the total amount of the sale.
If you do not send the `sale_refund_amount' parameter, the sale will be fully refunded.
## Parameters
This endpoint takes no path, query or header parameters.
## Request body
Content type: `application/json`
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `payme_client_key` | string | no | PayMe partner key. Only partners (platforms managing many sellers) have one; a merchant authenticates with seller_payme_id alone. Can also be sent in the PayMe-Partner-Key header. |
| `seller_payme_id` | string | yes | MPL. Your private key in PayMe system. |
| `payme_sale_id` | string | yes | Our unique sale ID. |
| `sale_refund_amount` | integer | no | **Used only for partial refunds**, for a full refund exclude this attribute. For example: if the amount is 50.75 (max 2 decimal points) the value that recieved is 5075. Note that the minimum value is 500. |
| `language` | string | no | Changes the error message language to English. |
### Request example
```json
{
"payme_client_key": "XXXXXXXX",
"seller_payme_id": "MPL1DEMO-XXXXXXXX-XXXXXXXX-XXXXXXXX",
"payme_sale_id": "SALEDEMO-XXXXXXXX-XXXXXXXX-XXXXXXXX",
"sale_refund_amount": 1000,
"language": "he"
}
```
## Code samples
### curl
```bash
curl -X POST 'https://sandbox.payme.io/api/refund-sale' \
-H 'Content-Type: application/json' \
--data-raw '{
"payme_client_key": "XXXXXXXX",
"seller_payme_id": "MPL1DEMO-XXXXXXXX-XXXXXXXX-XXXXXXXX",
"payme_sale_id": "SALEDEMO-XXXXXXXX-XXXXXXXX-XXXXXXXX",
"sale_refund_amount": 1000,
"language": "he"
}'
```
### Node.js
```javascript
const response = await fetch("https://sandbox.payme.io/api/refund-sale", {
method: "POST",
headers: {
"Content-Type": "application/json",
},
body: JSON.stringify({
"payme_client_key": "XXXXXXXX",
"seller_payme_id": "MPL1DEMO-XXXXXXXX-XXXXXXXX-XXXXXXXX",
"payme_sale_id": "SALEDEMO-XXXXXXXX-XXXXXXXX-XXXXXXXX",
"sale_refund_amount": 1000,
"language": "he"
}),
});
console.log(await response.text());
```
### Python
```python
import requests
response = requests.post(
"https://sandbox.payme.io/api/refund-sale",
json={
"payme_client_key": "XXXXXXXX",
"seller_payme_id": "MPL1DEMO-XXXXXXXX-XXXXXXXX-XXXXXXXX",
"payme_sale_id": "SALEDEMO-XXXXXXXX-XXXXXXXX-XXXXXXXX",
"sale_refund_amount": 1000,
"language": "he",
},
)
print(response.text)
```
### PHP
```php
'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;
```
## Responses
### 200 — OK (success)
| Field | Type | Description |
| --- | --- | --- |
| `status_code` | integer | Status of the request (0 - success, 1 - error). |
| `status_error_code` | integer | Our unique error code. |
| `payme_status` | string | Status of the request (success, error) |
| `refunded_from_creditcard` | boolean | Return true if seller has not enough money for refund and we complete the refund from the seller credit card. |
| `sale_invoice_number` | integer | Sale invoice Number. |
| `sale_invoice_url` | string | Sale invoice URL, if the seller has enabled the invoices module in his account panel. |
| `sale_refund_buffer` | integer | The refund buffer of this sale. |
| `sale_status` | string | Refund status. |
| `payme_transaction_total` | integer | The refund amount that the buyer will get. |
| `payme_transaction_total_aft_deduction` | integer | The amount that the seller will be charge on. |
| `payme_transaction_id` | string | The transaction unique id. |
| `payme_transaction_card_brand` | string | Card brand. |
| `payme_transaction_auth_number` | string | Authorization number from credit company. |
| `payme_transaction_voucher` | string | Transaction voucher |
| `payme_signature` | string | MD5 Signature |
| `payme_transaction_acquirer` | string | Transaction acquirer |
```json
{
"status_code": 0,
"status_error_code": 0,
"payme_status": "success",
"refunded_from_creditcard": false,
"sale_invoice_number": null,
"sale_invoice_url": null,
"sale_refund_buffer": 18800,
"sale_status": "partial-refund",
"payme_transaction_total": 1000,
"payme_transaction_total_aft_deduction": 1000,
"payme_transaction_id": "TRANDEMO-XXXXXXXX-XXXXXXXX-XXXXXXXX",
"payme_transaction_card_brand": "XXXXXXXX",
"payme_transaction_auth_number": "72****4",
"payme_transaction_voucher": "24****9",
"payme_signature": "b71e**************ca5a",
"payme_transaction_arn": null
}
```
- [Void Sale](https://docs-staging.payme.io/payments/post-sale-actions/void-sale): How to call POST /refund-sale for Post Sale Actions.
# Void Sale
This is a variant of [POST /refund-sale — Refund Sale](https://docs-staging.payme.io/payments/post-sale-actions/post-refund-sale); the request and responses below are the ones documented for Post Sale Actions.
- Sandbox: `POST https://sandbox.payme.io/api/refund-sale`
- Production: `POST https://live.payme.io/api/refund-sale`
## Credentials
- Request body field `seller_payme_id` (required): MPL. Your private key in PayMe system.
## Overview
In order to initiatea void for an authorization, you will be able to do so using the same API call for a refund.
In order to be eligible for a void, the request must be initiated for:
1. Sale type must be authorization
2. The amount required to be voided must be the equal to amount requested and authorized initially.
#### Sale Types
You can find all the sale statuses [Sale Statuses](https://docs-staging.payme.io/marketplaces-and-platforms/lists-statuses/sale-statuses).
## Parameters
This endpoint takes no path, query or header parameters.
## Request body
Content type: `application/json`
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `seller_payme_id` | string | yes | MPL. Your private key in PayMe system. |
| `payme_sale_id` | string | yes | Our unique sale ID. |
| `sale_currency` | string | no | Sale currency. |
| `language` | string | no | Changes the error message language to English. |
### Request example
```json
{
"payme_client_key": "XXXXXXXX",
"seller_payme_id": "MPL1DEMO-XXXXXXXX-XXXXXXXX-XXXXXXXX",
"payme_sale_id": "SALEDEMO-XXXXXXXX-XXXXXXXX-XXXXXXXX",
"sale_refund_amount": 1000,
"language": "he"
}
```
## Code samples
### curl
```bash
curl -X POST 'https://sandbox.payme.io/api/refund-sale' \
-H 'Content-Type: application/json' \
--data-raw '{
"payme_client_key": "XXXXXXXX",
"seller_payme_id": "MPL1DEMO-XXXXXXXX-XXXXXXXX-XXXXXXXX",
"payme_sale_id": "SALEDEMO-XXXXXXXX-XXXXXXXX-XXXXXXXX",
"sale_refund_amount": 1000,
"language": "he"
}'
```
### Node.js
```javascript
const response = await fetch("https://sandbox.payme.io/api/refund-sale", {
method: "POST",
headers: {
"Content-Type": "application/json",
},
body: JSON.stringify({
"payme_client_key": "XXXXXXXX",
"seller_payme_id": "MPL1DEMO-XXXXXXXX-XXXXXXXX-XXXXXXXX",
"payme_sale_id": "SALEDEMO-XXXXXXXX-XXXXXXXX-XXXXXXXX",
"sale_refund_amount": 1000,
"language": "he"
}),
});
console.log(await response.text());
```
### Python
```python
import requests
response = requests.post(
"https://sandbox.payme.io/api/refund-sale",
json={
"payme_client_key": "XXXXXXXX",
"seller_payme_id": "MPL1DEMO-XXXXXXXX-XXXXXXXX-XXXXXXXX",
"payme_sale_id": "SALEDEMO-XXXXXXXX-XXXXXXXX-XXXXXXXX",
"sale_refund_amount": 1000,
"language": "he",
},
)
print(response.text)
```
### PHP
```php
'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;
```
## Responses
### 200 — OK (success)
| Field | Type | Description |
| --- | --- | --- |
| `status_code` | integer | Status of the request (0 - success, 1 - error). |
| `status_error_code` | integer | Our unique error code. |
| `payme_status` | string | |
| `refunded_from_creditcard` | boolean | Return true if seller has not enough money for refund and we complete the refund from the seller credit card. |
| `sale_invoice_number` | integer | Sale invoice Number. |
| `sale_invoice_url` | string | Sale invoice URL, if the seller has enabled the invoices module in his account panel. |
| `sale_refund_buffer` | integer | The refund buffer of this sale. |
| `sale_status` | string | Refund status. |
| `payme_transaction_total` | integer | The refund amount that the buyer will get. |
| `payme_transaction_total_aft_deduction` | integer | The amount that the seller will be charge on. |
| `payme_transaction_id` | string | The transaction unique id. |
| `payme_transaction_card_brand` | string | Card brand. |
| `payme_transaction_auth_number` | string | Authorization number from credit company. |
| `payme_transaction_voucher` | string | Transaction voucher |
| `payme_signature` | string | MD5 Signature |
```json
{
"status_code": 0,
"status_error_code": 0,
"payme_status": "success",
"refunded_from_creditcard": false,
"sale_invoice_number": null,
"sale_invoice_url": null,
"sale_refund_buffer": 18800,
"sale_status": "partial-refund",
"payme_transaction_total": 1000,
"payme_transaction_total_aft_deduction": 1000,
"payme_transaction_id": "TRANDEMO-XXXXXXXX-XXXXXXXX-XXXXXXXX",
"payme_transaction_card_brand": "XXXXXXXX",
"payme_transaction_auth_number": "72****4",
"payme_transaction_voucher": "24****9",
"payme_signature": "b71e**************ca5a",
"payme_transaction_arn": null
}
```
- [Capture Sale](https://docs-staging.payme.io/payments/post-sale-actions/post-capture-sale): POST /capture-sale — Capture Sale
# Capture Sale
- Sandbox: `POST https://sandbox.payme.io/api/capture-sale`
- Production: `POST https://live.payme.io/api/capture-sale`
## Credentials
- Request body field `payme_client_key` (optional): PayMe Partner Key.
- Request body field `seller_payme_id` (optional): MPL. Your private key in PayMe system.
## Overview
This endpoint enable you to execute the sale after authorization (`generate-sale` with `sale_type` = "authorize").
For more information, go to the [Capture Sale (Authorization) Guide](/marketplaces-and-platforms/payments/capture-sale).
## Parameters
This endpoint takes no path, query or header parameters.
## Request body
Content type: `application/json`
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `payme_client_key` | string | no | PayMe Partner Key. |
| `seller_payme_id` | string | no | MPL. Your private key in PayMe system. |
| `payme_sale_id` | string | no | Our unique sale ID |
### Request example
```json
{
"payme_client_key": "XXXXXXXX",
"seller_payme_id": "MPL1DEMO-XXXXXXXX-XXXXXXXX-XXXXXXXX",
"payme_sale_id": "SALEDEMO-XXXXXXXX-XXXXXXXX-XXXXXXXX"
}
```
## Code samples
### curl
```bash
curl -X POST 'https://sandbox.payme.io/api/capture-sale' \
-H 'Content-Type: application/json' \
--data-raw '{
"payme_client_key": "XXXXXXXX",
"seller_payme_id": "MPL1DEMO-XXXXXXXX-XXXXXXXX-XXXXXXXX",
"payme_sale_id": "SALEDEMO-XXXXXXXX-XXXXXXXX-XXXXXXXX"
}'
```
### Node.js
```javascript
const response = await fetch("https://sandbox.payme.io/api/capture-sale", {
method: "POST",
headers: {
"Content-Type": "application/json",
},
body: JSON.stringify({
"payme_client_key": "XXXXXXXX",
"seller_payme_id": "MPL1DEMO-XXXXXXXX-XXXXXXXX-XXXXXXXX",
"payme_sale_id": "SALEDEMO-XXXXXXXX-XXXXXXXX-XXXXXXXX"
}),
});
console.log(await response.text());
```
### Python
```python
import requests
response = requests.post(
"https://sandbox.payme.io/api/capture-sale",
json={
"payme_client_key": "XXXXXXXX",
"seller_payme_id": "MPL1DEMO-XXXXXXXX-XXXXXXXX-XXXXXXXX",
"payme_sale_id": "SALEDEMO-XXXXXXXX-XXXXXXXX-XXXXXXXX",
},
)
print(response.text)
```
### PHP
```php
'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;
```
## Responses
### 200 — OK (success)
| Field | Type | Description |
| --- | --- | --- |
| `status_code` | integer | Status of the request (0 - success, 1 - error) |
| `payme_status` | string | Status of the request (success, error) |
| `payme_sale_id` | string | Our unique sale ID. |
| `payme_sale_code` | integer | Sale code |
| `sale_created` | string | The date the sale was created (timestamp) |
| `payme_sale_status` | string | Sale status. You can find all the sale statuses [Sale Statuses](/marketplaces-and-platforms/lists-statuses/sale-statuses). |
| `sale_status` | string | Sale status. You can find all the sale statuses [Sale Statuses](/marketplaces-and-platforms/lists-statuses/sale-statuses). |
| `currency` | string | Sale currency. [3-letter ISO 4217 name](https://en.wikipedia.org/wiki/ISO_4217). |
| `transaction_id` | string | The transaction ID. |
| `is_token_sale` | boolean | Indicates if the sale paid with token. |
| `price` | integer | The sale price. |
| `payme_signature` | string | PayMe's signature for the payment |
| `sale_description` | string | Sale description |
| `payme_transaction_id` | string | PayMe transaction ID |
| `payme_transaction_total` | string | Transaction total amount |
| `payme_transaction_card_brand` | string | The card brand |
| `payme_transaction_auth_number` | string | Transaction authorization number |
| `buyer_name` | string | Buyer's full name |
| `buyer_email` | string | Buyer's email address |
| `buyer_phone` | string | Buyer's phone number |
| `buyer_card_mask` | string | Card mask |
| `buyer_card_exp` | string | Buyer's card expiration date |
| `buyer_card_is_foreign` | boolean | Is the card foreign or domestic? (For IL Sellers only) |
| `buyer_social_id` | string | Buyer's social ID number |
| `installments` | integer | Number of installments used for the payment |
| `sale_paid_date` | string | Sale paid date |
```json
{
"status_code": 0,
"payme_status": "success",
"status_error_code": 0,
"payme_sale_id": "SALEDEMO-XXXXXXXX-XXXXXXXX-XXXXXXXX",
"payme_sale_code": 1111111,
"sale_created": "2023-06-22 14:01:47",
"payme_sale_status": "completed",
"sale_status": "completed",
"currency": "ILS",
"transaction_id": "12345",
"is_token_sale": false,
"price": 150000,
"payme_signature": "93a1ca34ed43bc00c62b9f467c40be8e",
"sale_description": "Computer",
"sale_deferred_months": null,
"payme_transaction_id": "TRANDEMO-XXXXXXXX-XXXXXXXX-XXXXXXXX",
"payme_transaction_total": "150000",
"payme_transaction_card_brand": "Mastercard",
"payme_transaction_auth_number": "8906759",
"payme_transaction_voucher": "111111",
"payme_transaction_emv_uid": null,
"payme_transaction_acquirer": "PayMe",
"payme_transaction_auth_source": "VoiceMail",
"payme_transaction_card_issuer": "Isracard",
"payme_transaction_credit_type": "RegularCredit",
"buyer_name": "Test User",
"buyer_email": "test@payme.io",
"buyer_phone": "9725254448888",
"buyer_card_mask": "532610******5846",
"buyer_card_exp": "0426",
"buyer_card_is_foreign": false,
"buyer_social_id": "123456789",
"installments": 1,
"transaction_first_payment": 150000,
"transaction_periodical_payment": 0,
"transaction_arn": null,
"sale_paid_date": "2023-06-22 14:04:28",
"sale_release_date": null,
"sale_3ds": false
}
```
- [Cancel Multi Payment Page](https://docs-staging.payme.io/payments/post-sale-actions/post-cancel-template): POST /cancel-template — Cancel Multi Payment Page
# Cancel Multi Payment Page
- Sandbox: `POST https://sandbox.payme.io/api/cancel-template`
- Production: `POST https://live.payme.io/api/cancel-template`
## Credentials
- Request body field `seller_payme_id` (required): MPL. Your private key in PayMe system.
## Overview
This endpoint enable you to cancle a Multi Payment Page.
Multi Payment Page enables payments on a single sale link, by multiple buyers.
You can find more information in our [Multi Payment Page Guide](/marketplaces-and-platforms/payments/multi-payment-page).
## Parameters
This endpoint takes no path, query or header parameters.
## Request body
Content type: `application/json`
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `seller_payme_id` | string | yes | MPL. Your private key in PayMe system. |
| `payme_sale_id` | string | yes | Our unique sale ID. |
### Request example
```json
{
"payme_client_key": "XXXXXXXX",
"seller_payme_id": "MPL1DEMO-XXXXXXXX-XXXXXXXX-XXXXXXXX",
"payme_sale_id": "SALEDEMO-XXXXXXXX-XXXXXXXX-XXXXXXXX",
"sale_refund_amount": 1000,
"language": "he"
}
```
## Code samples
### curl
```bash
curl -X POST 'https://sandbox.payme.io/api/cancel-template' \
-H 'Content-Type: application/json' \
--data-raw '{
"payme_client_key": "XXXXXXXX",
"seller_payme_id": "MPL1DEMO-XXXXXXXX-XXXXXXXX-XXXXXXXX",
"payme_sale_id": "SALEDEMO-XXXXXXXX-XXXXXXXX-XXXXXXXX",
"sale_refund_amount": 1000,
"language": "he"
}'
```
### Node.js
```javascript
const response = await fetch("https://sandbox.payme.io/api/cancel-template", {
method: "POST",
headers: {
"Content-Type": "application/json",
},
body: JSON.stringify({
"payme_client_key": "XXXXXXXX",
"seller_payme_id": "MPL1DEMO-XXXXXXXX-XXXXXXXX-XXXXXXXX",
"payme_sale_id": "SALEDEMO-XXXXXXXX-XXXXXXXX-XXXXXXXX",
"sale_refund_amount": 1000,
"language": "he"
}),
});
console.log(await response.text());
```
### Python
```python
import requests
response = requests.post(
"https://sandbox.payme.io/api/cancel-template",
json={
"payme_client_key": "XXXXXXXX",
"seller_payme_id": "MPL1DEMO-XXXXXXXX-XXXXXXXX-XXXXXXXX",
"payme_sale_id": "SALEDEMO-XXXXXXXX-XXXXXXXX-XXXXXXXX",
"sale_refund_amount": 1000,
"language": "he",
},
)
print(response.text)
```
### PHP
```php
'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;
```
## Responses
### 200 — OK (success)
| Field | Type | Description |
| --- | --- | --- |
| `status_code` | integer | Status of the request (0 - success, 1 - error). |
```json
{
"status_code": 0,
"status_error_code": 0,
"payme_status": "success",
"refunded_from_creditcard": false,
"sale_invoice_number": null,
"sale_invoice_url": null,
"sale_refund_buffer": 18800,
"sale_status": "partial-refund",
"payme_transaction_total": 1000,
"payme_transaction_total_aft_deduction": 1000,
"payme_transaction_id": "TRANDEMO-XXXXXXXX-XXXXXXXX-XXXXXXXX",
"payme_transaction_card_brand": "XXXXXXXX",
"payme_transaction_auth_number": "72****4",
"payme_transaction_voucher": "24****9",
"payme_signature": "b71e**************ca5a",
"payme_transaction_arn": null
}
```
### 251 — Seller not found (success)
| Field | Type | Description |
| --- | --- | --- |
| `status_code` | integer | Status of the request (0 - success, 1 - error). |
| `status_error_details` | string | |
| `status_additional_info` | string | |
| `status_error_code` | integer | |
| `session` | string | |
```json
{
"status_code": 1,
"status_error_details": "מוכר לא נמצא",
"status_additional_info": "seller_payme_id",
"status_error_code": 251,
"session": "MfH3Hc80"
}
```
### 305 — This operation cannot be completed due to an inappropriate sale status (error)
| Field | Type | Description |
| --- | --- | --- |
| `status_code` | integer | Status of the request (0 - success, 1 - error). |
| `status_error_details` | string | |
| `status_additional_info` | string | |
| `status_error_code` | integer | |
| `session` | string | |
```json
{
"status_code": 1,
"status_error_details": "לא ניתן להשלים פעולה זו עקב סטטוס מכירה לא מתאים",
"status_additional_info": "canceled",
"status_error_code": 305,
"session": "NGQ1QpYB"
}
```
## Apple Pay
- [Activate Service (Apple Pay)](https://docs-staging.payme.io/payments/apple-pay/post-vas-enable-apple-pay): How to call POST /vas-enable for Apple Pay.
# Activate Service (Apple Pay)
This is a variant of [POST /vas-enable — Order New POS Device](https://docs-staging.payme.io/payments/point-of-sale-pos/post-vas-enable); the request and responses below are the ones documented for Apple Pay.
- Sandbox: `POST https://sandbox.payme.io/api/vas-enable`
- Production: `POST https://live.payme.io/api/vas-enable`
## Credentials
- Request body field `payme_client_key` (required): Your PayMe API Partner Key.
- Request body field `seller_payme_id` (required): The unique seller ID the service is activated for.
- Request body field `vas_payme_id` (required): The service activation unique partner ID.
## Overview
#### **Apple Pay VAS-Enable**
In order to be able to use Apple Pay in our platform, you will need to set up the service via API.
### Website Enrollment Procedure
After you added the Apple's file into the proper folder and path of your website, you can use our VAS Enable request to sign your website for the Apple Pay service on our platform.
By using the Activate service API request, you will need to register your websites to PayMes system.
The request works as in the following form:
```json
{
"payme_client_key": "payme_partner_key",
"seller_payme_id": "MPLDEMO-MPLDEMO-MPLDEMO-1234567",
"vas_payme_id": "VASLDEMO-VASLDEMO-VASLDEMO-1234567",
"vas_data": {
"websites": [
"payme.io", "marketplace.payme.io"
]
},
"language": "en"
}
```
A successful response will be 200 and includes a payload in the form of:
```json
{
"status_code": 0,
"seller_payme_id": "MPLDEMO-MPLDEMO-MPLDEMO-1234567",
"vas_payme_id": "VASLDEMO-VASLDEMO-VASLDEMO-1234567",
"vas_description": "Payments Account",
"vas_type": "AlternativePaymentMethod",
"vas_api_key": "",
"vas_is_active": true,
"vas_payer_type": 2,
"vas_price_currency": "ILS",
"vas_price_setup_fixed": 0,
"vas_price_periodic_fixed": 0,
"vas_price_periodic_variable": "0.00",
"vas_price_usage_fixed": 0,
"vas_price_usage_variable": "0.00",
"vas_market_fee": null,
"vas_period": 1,
"vas_data": {
"websites": [
"test5.paymeservice.com"
]
}
}
```
A failed response will be 500 and includes a payload in the form of:
```json
{
"status_code": 1,
"status_error_details": "The service was not activated",
"status_additional_info": null,
"status_error_code": 720
}
```
## Parameters
This endpoint takes no path, query or header parameters.
## Request body
Content type: `application/json`
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `payme_client_key` | string | yes | Your PayMe API Partner Key. |
| `seller_payme_id` | string | yes | The unique seller ID the service is activated for. |
| `vas_payme_id` | string | yes | The service activation unique partner ID. |
| `vas_data` | object | yes | |
| `vas_data.websites` | array | yes | The websites domains the service is activated for. Example: `https://payme.io` |
| `language` | string | yes | |
### Request example
```json
{
"payme_client_key": "payme_partner_key",
"seller_payme_id": "MPLDEMO-MPLDEMO-MPLDEMO-1234567",
"vas_payme_id": "VASLDEMO-VASLDEMO-VASLDEMO-1234567",
"vas_data": {
"websites": [
"payme.io",
"marketplace.payme.io"
]
},
"language": "en"
}
```
## Code samples
### curl
```bash
curl -X POST 'https://sandbox.payme.io/api/vas-enable' \
-H 'Content-Type: application/json' \
--data-raw '{
"payme_client_key": "payme_partner_key",
"seller_payme_id": "MPLDEMO-MPLDEMO-MPLDEMO-1234567",
"vas_payme_id": "VASLDEMO-VASLDEMO-VASLDEMO-1234567",
"vas_data": {
"websites": [
"payme.io",
"marketplace.payme.io"
]
},
"language": "en"
}'
```
### Node.js
```javascript
const response = await fetch("https://sandbox.payme.io/api/vas-enable", {
method: "POST",
headers: {
"Content-Type": "application/json",
},
body: JSON.stringify({
"payme_client_key": "payme_partner_key",
"seller_payme_id": "MPLDEMO-MPLDEMO-MPLDEMO-1234567",
"vas_payme_id": "VASLDEMO-VASLDEMO-VASLDEMO-1234567",
"vas_data": {
"websites": [
"payme.io",
"marketplace.payme.io"
]
},
"language": "en"
}),
});
console.log(await response.text());
```
### Python
```python
import requests
response = requests.post(
"https://sandbox.payme.io/api/vas-enable",
json={
"payme_client_key": "payme_partner_key",
"seller_payme_id": "MPLDEMO-MPLDEMO-MPLDEMO-1234567",
"vas_payme_id": "VASLDEMO-VASLDEMO-VASLDEMO-1234567",
"vas_data": {
"websites": [
"payme.io",
"marketplace.payme.io",
],
},
"language": "en",
},
)
print(response.text)
```
### PHP
```php
'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;
```
## Responses
### 200 — OK (success)
| Field | Type | Description |
| --- | --- | --- |
| `status_code` | number | 0 - Success 1 - Failure |
| `seller_payme_id` | string | Our unique seller ID. |
| `vas_payme_id` | string | The partner unique service API key. |
| `vas_description` | string | The description of the service that was activated. |
| `vas_type` | string | The type of the service that was activated. You can find all the VAS types [VAS Types](https://docs-staging.payme.io/marketplaces-and-platforms/lists-statuses/vas-types). |
| `vas_api_key` | string | Empty by default. |
| `vas_is_active` | boolean | Was the service activated successfully |
| `vas_payer_type` | number | Internal payer identity. 1 = Partner 2 = Seller 3 = Reseller |
| `vas_price_currency` | string | The currency that the service is charged in. |
| `vas_price_setup_fixed` | number | Partner account configuration of the setup costs. |
| `vas_price_periodic_fixed` | number | Partner account configuration of the periodical costs. |
| `vas_price_periodic_variable` | string | Partner account configuration of the periodical costs. |
| `vas_price_usage_fixed` | number | Partner account configuration of the fixed costs. |
| `vas_price_usage_variable` | string | Partner account configuration of the usage costs. |
| `vas_period` | number | |
| `vas_data` | object | The peiod of the VAS charge. Instant = 1, Daily = 2, Monthly = 3, Yearly = 4 |
| `vas_data.websites` | array | The websites domains the service is activated for. |
```json
{
"status_code": 0,
"seller_payme_id": "MPLDEMO-MPLDEMO-MPLDEMO-1234567",
"vas_payme_id": "VASLDEMO-VASLDEMO-VASLDEMO-1234567",
"vas_description": "Payments Account",
"vas_type": "AlternativePaymentMethod",
"vas_api_key": "",
"vas_is_active": true,
"vas_payer_type": 2,
"vas_price_currency": "ILS",
"vas_price_setup_fixed": 0,
"vas_price_periodic_fixed": 0,
"vas_price_periodic_variable": "0.00",
"vas_price_usage_fixed": 0,
"vas_price_usage_variable": "0.00",
"vas_market_fee": null,
"vas_period": 1,
"vas_data": {
"websites": [
"test5.paymeservice.com"
]
}
}
```
### 500 — Request Failed (error)
| Field | Type | Description |
| --- | --- | --- |
| `status_code` | number | Status code - will always be 1 for failed requests. |
| `status_error_details` | string | Reasons for the failed request. |
| `status_additional_info` | string | Null |
| `status_error_code` | number | Error code for further support. |
```json
{
"status_code": 1,
"status_error_details": "The service was not activated",
"status_additional_info": null,
"status_error_code": 720
}
```
- [Generate Sale with Apple Pay](https://docs-staging.payme.io/payments/apple-pay/post-generate-sale-apple-pay): How to call POST /generate-sale for Apple Pay.
# Generate Sale with Apple Pay
This is a variant of [POST /generate-sale — Generate Payment](https://docs-staging.payme.io/payments/hosted-payment-page/post-generate-sale); the request and responses below are the ones documented for Apple Pay.
- Sandbox: `POST https://sandbox.payme.io/api/generate-sale`
- Production: `POST https://live.payme.io/api/generate-sale`
## Credentials
- Request body field `seller_payme_id` (required): Our unique seller ID (MPL).
## Overview
In order to initiate the process of paying using Apple Pay APM, you will first need to initiate a generate-sale request to our API.
The request shall include "apple-pay" as the `sale_payment_method`.
## Parameters
This endpoint takes no path, query or header parameters.
## Request body
Content type: `application/json`
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `seller_payme_id` | string | yes | Our unique seller ID (MPL). |
| `sale_price` | string | yes | The sale price. |
| `currency` | string | yes | The sale currency (ISO 4217 Code). |
| `product_name` | string | yes | What is the payment for. |
| `language` | string | no | The language of the user interface. |
| `sale_payment_method` | string | yes | The payment method used for the transaction. |
| `sale_type` | string | yes | The required sale type. |
### Request example
```json
{
"seller_payme_id": "MPLDEMO-MPLDEMO-MPLDEMO-1234567",
"sale_price": "1000",
"currency": "ILS",
"product_name": "Shirt",
"language": "en",
"sale_payment_method": "apple-pay",
"sale_type": "sale"
}
```
## Code samples
### curl
```bash
curl -X POST 'https://sandbox.payme.io/api/generate-sale' \
-H 'Content-Type: application/json' \
--data-raw '{
"seller_payme_id": "MPLDEMO-MPLDEMO-MPLDEMO-1234567",
"sale_price": "1000",
"currency": "ILS",
"product_name": "Shirt",
"language": "en",
"sale_payment_method": "apple-pay",
"sale_type": "sale"
}'
```
### Node.js
```javascript
const response = await fetch("https://sandbox.payme.io/api/generate-sale", {
method: "POST",
headers: {
"Content-Type": "application/json",
},
body: JSON.stringify({
"seller_payme_id": "MPLDEMO-MPLDEMO-MPLDEMO-1234567",
"sale_price": "1000",
"currency": "ILS",
"product_name": "Shirt",
"language": "en",
"sale_payment_method": "apple-pay",
"sale_type": "sale"
}),
});
console.log(await response.text());
```
### Python
```python
import requests
response = requests.post(
"https://sandbox.payme.io/api/generate-sale",
json={
"seller_payme_id": "MPLDEMO-MPLDEMO-MPLDEMO-1234567",
"sale_price": "1000",
"currency": "ILS",
"product_name": "Shirt",
"language": "en",
"sale_payment_method": "apple-pay",
"sale_type": "sale",
},
)
print(response.text)
```
### PHP
```php
'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;
```
## Responses
### 200 — OK (success)
| Field | Type | Description |
| --- | --- | --- |
| `status_code` | number | 0 - Success 1 - Failure |
| `sale_url` | string | The URL to complete the payment. |
| `payme_sale_id` | string | Our unique sale ID |
| `payme_sale_code` | number | Our unique sale code (for display purposes only) |
| `price` | number | Sale final price. For example, if the price is 50.75 (max 2 decimal points) the value that needs to be sent is 5075 |
| `transaction_id` | string | Merchant's unique sale ID for correlation with us |
| `currency` | string | The currency of the payment. |
| `sale_payment_method` | string | The payment method used to generate the new payment. |
```json
{
"status_code": 0,
"sale_url": "https://preprod.paymeservice.com/sale/generate/Sale_guid",
"payme_sale_id": "SALEguid",
"payme_sale_code": 1032526,
"price": 1000,
"transaction_id": "",
"currency": "ILS",
"sale_payment_method": "apple-pay"
}
```
### 500 — Internal Server Error (error)
## Google Pay
- [Activate Service (Google Pay)](https://docs-staging.payme.io/payments/google-pay/post-vas-enable-google-pay): How to call POST /vas-enable for Google Pay.
# Activate Service (Google Pay)
This is a variant of [POST /vas-enable — Order New POS Device](https://docs-staging.payme.io/payments/point-of-sale-pos/post-vas-enable); the request and responses below are the ones documented for Google Pay.
- Sandbox: `POST https://sandbox.payme.io/api/vas-enable`
- Production: `POST https://live.payme.io/api/vas-enable`
## Credentials
- Request body field `payme_client_key` (required): Your PayMe API Partner Key.
- Request body field `seller_payme_id` (required): The unique seller ID the service is activated for.
- Request body field `vas_payme_id` (required): The service activation unique partner ID.
## Overview
#### **Google Pay VAS-Enable**
In order to be able to use Google Pay in our platform, you will need to set up the service via API, using our VAS Enable request.
The request works as in the following form:
```json
{
"payme_client_key": "payme_partner_key",
"seller_payme_id": "MPLDEMO-MPLDEMO-MPLDEMO-1234567",
"vas_payme_id": "VASLDEMO-VASLDEMO-VASLDEMO-1234567",
"language": "en"
}
```
A successful response will be 200 and includes a payload in the form of:
```json
{
"status_code": 0,
"seller_payme_id": "MPLDEMO-MPLDEMO-MPLDEMO-1234567",
"vas_payme_id": "VASLDEMO-VASLDEMO-VASLDEMO-1234567",
"vas_description": "Payments Account",
"vas_type": "AlternativePaymentMethod",
"vas_api_key": "",
"vas_is_active": true,
"vas_payer_type": 2,
"vas_price_currency": "ILS",
"vas_price_setup_fixed": 0,
"vas_price_periodic_fixed": 0,
"vas_price_periodic_variable": "0.00",
"vas_price_usage_fixed": 0,
"vas_price_usage_variable": "0.00",
"vas_market_fee": null,
"vas_period": 1
}
```
A failed response will be 500 and includes a payload in the form of:
```json
{
"status_code": 1,
"status_error_details": "The service was not activated",
"status_additional_info": null,
"status_error_code": 720
}
```
## Parameters
This endpoint takes no path, query or header parameters.
## Request body
Content type: `application/json`
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `payme_client_key` | string | yes | Your PayMe API Partner Key. |
| `seller_payme_id` | string | yes | The unique seller ID the service is activated for. |
| `vas_payme_id` | string | yes | The service activation unique partner ID. |
| `language` | string | yes | |
### Request example
```json
{
"payme_client_key": "payme_partnerkey",
"seller_payme_id": "MPLDEMO-MPLDEMO-MPLDEMO-1234567",
"vas_payme_id": "VASLDEMO-VASLDEMO-VASLDEMO-1234567",
"language": "he"
}
```
## Code samples
### curl
```bash
curl -X POST 'https://sandbox.payme.io/api/vas-enable' \
-H 'Content-Type: application/json' \
--data-raw '{
"payme_client_key": "payme_partnerkey",
"seller_payme_id": "MPLDEMO-MPLDEMO-MPLDEMO-1234567",
"vas_payme_id": "VASLDEMO-VASLDEMO-VASLDEMO-1234567",
"language": "he"
}'
```
### Node.js
```javascript
const response = await fetch("https://sandbox.payme.io/api/vas-enable", {
method: "POST",
headers: {
"Content-Type": "application/json",
},
body: JSON.stringify({
"payme_client_key": "payme_partnerkey",
"seller_payme_id": "MPLDEMO-MPLDEMO-MPLDEMO-1234567",
"vas_payme_id": "VASLDEMO-VASLDEMO-VASLDEMO-1234567",
"language": "he"
}),
});
console.log(await response.text());
```
### Python
```python
import requests
response = requests.post(
"https://sandbox.payme.io/api/vas-enable",
json={
"payme_client_key": "payme_partnerkey",
"seller_payme_id": "MPLDEMO-MPLDEMO-MPLDEMO-1234567",
"vas_payme_id": "VASLDEMO-VASLDEMO-VASLDEMO-1234567",
"language": "he",
},
)
print(response.text)
```
### PHP
```php
'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;
```
## Responses
### 200 — OK (success)
| Field | Type | Description |
| --- | --- | --- |
| `status_code` | number | 0 - Success 1 - Failure |
| `seller_payme_id` | string | Our unique seller ID. |
| `vas_payme_id` | string | The partner unique service API key. |
| `vas_description` | string | The description of the service that was activated. |
| `vas_type` | string | The type of the service that was activated. You can find all the VAS types [VAS Types](https://docs-staging.payme.io/marketplaces-and-platforms/lists-statuses/vas-types). |
| `vas_api_key` | string | Empty by default. |
| `vas_is_active` | boolean | Was the service activated successfully |
| `vas_payer_type` | number | Internal payer identity. 1 = Partner 2 = Seller 3 = Reseller |
| `vas_price_currency` | string | The currency that the service is charged in. |
| `vas_price_setup_fixed` | number | Partner account configuration of the setup costs. |
| `vas_price_periodic_fixed` | number | Partner account configuration of the periodical costs. |
| `vas_price_periodic_variable` | string | Partner account configuration of the periodical costs. |
| `vas_price_usage_fixed` | number | Partner account configuration of the fixed costs. |
| `vas_price_usage_variable` | string | Partner account configuration of the usage costs. |
| `vas_period` | number | |
### 500 — Request Failed (error)
| Field | Type | Description |
| --- | --- | --- |
| `status_code` | number | Status code - will always be 1 for failed requests. |
| `status_error_details` | string | Reasons for the failed request. |
| `status_additional_info` | string | |
| `status_error_code` | number | Error code for further support. |
- [Generate Sale with Google Pay](https://docs-staging.payme.io/payments/google-pay/post-generate-sale-google-pay): How to call POST /generate-sale for Google Pay.
# Generate Sale with Google Pay
This is a variant of [POST /generate-sale — Generate Payment](https://docs-staging.payme.io/payments/hosted-payment-page/post-generate-sale); the request and responses below are the ones documented for Google Pay.
- Sandbox: `POST https://sandbox.payme.io/api/generate-sale`
- Production: `POST https://live.payme.io/api/generate-sale`
## Credentials
- Request body field `seller_payme_id` (required): Our unique seller ID (MPL).
## Overview
In order to initiate the process of paying using Google Pay APM, you will first need to initiate a generate-sale request to our API.
The request shall include "google-pay" as the `sale_payment_method`.
## Parameters
This endpoint takes no path, query or header parameters.
## Request body
Content type: `application/json`
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `seller_payme_id` | string | yes | Our unique seller ID (MPL). |
| `sale_price` | string | yes | The sale price. For example, if the price is 50.75 (max 2 decimal points) the value that needs to be sent is 5075 |
| `currency` | string | yes | The sale currency (ISO 4217 Code). |
| `product_name` | string | yes | What is the payment for. |
| `language` | string | no | The language of the user interface. |
| `sale_payment_method` | string | yes | The payment method used for the transaction. You can use also `multi` to allow buyer to select his preffered payment method. |
| `sale_type` | string | yes | The required sale type. |
### Request example
No example is documented; this template is generated from the fields — replace the placeholder values.
```json
{
"seller_payme_id": "",
"sale_price": "",
"currency": "",
"product_name": "",
"language": "",
"sale_payment_method": "",
"sale_type": ""
}
```
## Code samples
### curl
```bash
curl -X POST 'https://sandbox.payme.io/api/generate-sale' \
-H 'Content-Type: application/json' \
--data-raw '{
"seller_payme_id": "",
"sale_price": "",
"currency": "",
"product_name": "",
"sale_payment_method": "",
"sale_type": ""
}'
```
### Node.js
```javascript
const response = await fetch("https://sandbox.payme.io/api/generate-sale", {
method: "POST",
headers: {
"Content-Type": "application/json",
},
body: JSON.stringify({
"seller_payme_id": "",
"sale_price": "",
"currency": "",
"product_name": "",
"sale_payment_method": "",
"sale_type": ""
}),
});
console.log(await response.text());
```
### Python
```python
import requests
response = requests.post(
"https://sandbox.payme.io/api/generate-sale",
json={
"seller_payme_id": "",
"sale_price": "",
"currency": "",
"product_name": "",
"sale_payment_method": "",
"sale_type": "",
},
)
print(response.text)
```
### PHP
```php
",
"sale_price": "",
"currency": "",
"product_name": "",
"sale_payment_method": "",
"sale_type": ""
}
BODY;
$ch = curl_init('https://sandbox.payme.io/api/generate-sale');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;
```
## Responses
### 200 — OK (success)
| Field | Type | Description |
| --- | --- | --- |
| `status_code` | number | 0 - Success 1 - Failure |
| `sale_url` | string | The URL to complete the payment. |
| `payme_sale_id` | string | Our unique sale ID |
| `payme_sale_code` | number | Our unique sale code (for display purposes only) |
| `price` | number | Sale final price. |
| `transaction_id` | string | Merchant's unique sale ID for correlation with us |
| `currency` | string | The currency of the payment. |
| `sale_payment_method` | string | The payment method used to generate the new payment. |
### 500 — Internal Server Error (error)
| Field | Type | Description |
| --- | --- | --- |
| `status_code` | number | Status code - will always be 1 for failed requests. |
| `status_error_details` | string | Reasons for the failed request. |
| `status_additional_info` | string | |
| `status_error_code` | number | Error code for further support. |
## IL Direct Debit
- [Generate New Authorization](https://docs-staging.payme.io/payments/il-direct-debit/post-generate-sale-il-direct-debit): How to call POST /generate-sale for IL Direct Debit.
# Generate New Authorization
This is a variant of [POST /generate-sale — Generate Payment](https://docs-staging.payme.io/payments/hosted-payment-page/post-generate-sale); the request and responses below are the ones documented for IL Direct Debit.
- Sandbox: `POST https://sandbox.payme.io/api/generate-sale`
- Production: `POST https://live.payme.io/api/generate-sale`
## Credentials
- Request body field `seller_payme_id` (required): The MPL the authorization will be given for
## Overview
The Israeli Direct Debit alternative payment method works in a two-phase setup:
1. Setting up the bank authorization <- **You are here**
2. Completing the payment using the bank authorization
### Bank Authorization Setup
In order to setup the bank Authorization, you will need to use our generate-sale endpoint, using a few specific parameters.
1. `sale_type = token`
2. `sale_payment_method = il-direct-debit`
The authorization page is based on our `hosted-payment-page` and will collect information regarding the buyer's identity and bank account.
After the buyer completes the setup, the authorization will be sent to the bank and will be `inactive` until we receive an update (takes up to 96 hours).
### Callbacks
You will get two callbacks:
1. **Callback that indicates that the sale complete** - Not relevant, as the `sale_type` is from type "token" and not sale.
* You can find all the sale types [Sale Types](https://docs-staging.payme.io/marketplaces-and-platforms/lists-statuses/sale-types)
* You can find all the sale callbacks [Sale Callbacks](https://docs-staging.payme.io/marketplaces-and-platforms/lists-statuses/sale-callbacks)
2. **Callback that inditates the authorization status** - You can find all the bank authorization statuses [Bank Authorization Statuses](https://docs-staging.payme.io/marketplaces-and-platforms/lists-statuses/bank-authorization-statuses).
```
{
"status": 1,
"error_code": "11",
"internal_reference_id": 10000,
"customer_name": "Test test",
"charge_limit": 200
}
```
### Testing
Information for testing can be found here - [Israeli Direct Debit Testing Information](https://docs-staging.payme.io/payments/introduction/test-cards-and-payment-methods#israeli-direct-debit-testing-information).
Please note that in our sandbox environment you will receive only bank authorization statuses from type 1 or 2 (Success/failure).
You can find all the bank authorization statuses [Bank Authorization Statuses](https://docs-staging.payme.io/marketplaces-and-platforms/lists-statuses/bank-authorization-statuses).
## Parameters
This endpoint takes no path, query or header parameters.
## Request body
Content type: `application/json`
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `seller_payme_id` | string | yes | The MPL the authorization will be given for |
| `sale_price` | string | yes | Must be included, won't be charged as a part of the authorization setup |
| `currency` | string | yes | Sale currency. [3-letter ISO 4217 name](https://en.wikipedia.org/wiki/ISO_4217). |
| `product_name` | string | yes | Use a generic value here (will not affect the authorization setup process) |
| `language` | string | no | The language the page will be presented in |
| `sale_type` | string | yes | The sale type. For authorization setup, use `token` by default |
| `sale_payment_method` | string | yes | The sale payment method. Must be `il-direct-debit` for the authorization setup process |
| `sale_return_url` | string | no | The URL the user will be redirected to after completing the authorization setup process |
### Request example
```json
{
"seller_payme_id": "MPL00009-00009EXM-EXAMPLE0-EXAMPLE9",
"sale_price": "1000",
"currency": "ILS",
"product_name": "Shirt",
"language": "en",
"sale_type": "token",
"sale_payment_method": "il-direct-debit",
"sale_return_url": "https://sport5.co.il"
}
```
## Code samples
### curl
```bash
curl -X POST 'https://sandbox.payme.io/api/generate-sale' \
-H 'Content-Type: application/json' \
--data-raw '{
"seller_payme_id": "MPL00009-00009EXM-EXAMPLE0-EXAMPLE9",
"sale_price": "1000",
"currency": "ILS",
"product_name": "Shirt",
"language": "en",
"sale_type": "token",
"sale_payment_method": "il-direct-debit",
"sale_return_url": "https://sport5.co.il"
}'
```
### Node.js
```javascript
const response = await fetch("https://sandbox.payme.io/api/generate-sale", {
method: "POST",
headers: {
"Content-Type": "application/json",
},
body: JSON.stringify({
"seller_payme_id": "MPL00009-00009EXM-EXAMPLE0-EXAMPLE9",
"sale_price": "1000",
"currency": "ILS",
"product_name": "Shirt",
"language": "en",
"sale_type": "token",
"sale_payment_method": "il-direct-debit",
"sale_return_url": "https://sport5.co.il"
}),
});
console.log(await response.text());
```
### Python
```python
import requests
response = requests.post(
"https://sandbox.payme.io/api/generate-sale",
json={
"seller_payme_id": "MPL00009-00009EXM-EXAMPLE0-EXAMPLE9",
"sale_price": "1000",
"currency": "ILS",
"product_name": "Shirt",
"language": "en",
"sale_type": "token",
"sale_payment_method": "il-direct-debit",
"sale_return_url": "https://sport5.co.il",
},
)
print(response.text)
```
### PHP
```php
'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;
```
## Responses
### 200 — OK (success)
| Field | Type | Description |
| --- | --- | --- |
| `status_code` | string | Status of the request (0 - success, 1 - error) |
| `sale_url` | string | The URL of the IFRAME secured payment form to display to the buyer |
| `payme_sale_id` | string | Our unique sale ID |
| `payme_sale_code` | integer | Our unique sale code (for display purposes only) |
| `price` | integer | Sale final price. For example, if the price is 50.75 (max 2 decimal points) the value that needs to be sent is 5075 |
| `transaction_id` | string | Transaction ID |
| `currency` | string | |
| `sale_payment_method` | string | The sale payment method. Must be il-direct-debit for the authorization setup process |
```json
{
"status_code": 0,
"sale_url": "https://sandbox.payme.io/sale/generate/SALETEST-XXXXXXXX-XXXXXXXX-XXXXXXXX",
"payme_sale_id": "SALE1687-957072WX-0MEX63QM-GMHDMGNU",
"payme_sale_code": 1234567,
"price": 1000,
"transaction_id": "12345",
"currency": "ILS",
"sale_payment_method": "il-direct-debit"
}
```
- [Generate New Payment](https://docs-staging.payme.io/payments/il-direct-debit/post-generate-sale-2-il-direct-debit): How to call POST /generate-sale for IL Direct Debit.
# Generate New Payment
This is a variant of [POST /generate-sale — Generate Payment](https://docs-staging.payme.io/payments/hosted-payment-page/post-generate-sale); the request and responses below are the ones documented for IL Direct Debit.
- Sandbox: `POST https://sandbox.payme.io/api/generate-sale`
- Production: `POST https://live.payme.io/api/generate-sale`
## Credentials
- Request body field `seller_payme_id` (required): The MPL the authorization will be given for
## Overview
The Israeli Direct Debit alternative payment method works in a two-phase setup:
1. Setting up the bank authorization
2. Completing the payment using the bank authorization <- **You are here**
### Generate a new payment using Israeli Direct Debit
In order to setup a new payment using the Israeli Direct Debit alternative payment method, you will need to use our `generate-sale` endpoint, using a few specific parameters.
1. `sale_type = sale`
2. `sale_payment_method = il-direct-debit`
3. include a `buyer-key` parameter as a part of your `generate-sale` request in order to initiate the payment flow
### Callbacks
Status | Description
---- | ----
Success | In case the payment was successful, you won't get any callback. Please note that the payment process can take up to 8 days.
Failure | In case that payment failed, you will get a callback indicates on failure.
### Testing
Information for testing can be found here - [Israeli Direct Debit Testing Information](https://docs-staging.payme.io/payments/introduction/test-cards-and-payment-methods#israeli-direct-debit-testing-information).
## Parameters
This endpoint takes no path, query or header parameters.
## Request body
Content type: `application/json`
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `seller_payme_id` | string | yes | The MPL the authorization will be given for |
| `sale_price` | string | yes | Must be included, won't be charged as a part of the authorization setup |
| `currency` | string | yes | Sale currency. [3-letter ISO 4217 name](https://en.wikipedia.org/wiki/ISO_4217). |
| `product_name` | string | yes | Use a generic value here (will not affect the authorization setup process) |
| `language` | string | no | The language the page will be presented in |
| `sale_type` | string | yes | The sale type. For authorization setup, use `token` by default |
| `sale_payment_method` | string | yes | The sale payment method. Must be `il-direct-debit` for the authorization setup process |
| `sale_return_url` | string | no | The URL the user will be redirected to after completing the authorization setup process |
### Request example
```json
{
"seller_payme_id": "MPL00009-00009EXM-EXAMPLE0-EXAMPLE9",
"sale_price": "1000",
"currency": "ILS",
"product_name": "Shirt",
"language": "en",
"sale_type": "token",
"sale_payment_method": "il-direct-debit",
"sale_return_url": "https://sport5.co.il"
}
```
## Code samples
### curl
```bash
curl -X POST 'https://sandbox.payme.io/api/generate-sale' \
-H 'Content-Type: application/json' \
--data-raw '{
"seller_payme_id": "MPL00009-00009EXM-EXAMPLE0-EXAMPLE9",
"sale_price": "1000",
"currency": "ILS",
"product_name": "Shirt",
"language": "en",
"sale_type": "token",
"sale_payment_method": "il-direct-debit",
"sale_return_url": "https://sport5.co.il"
}'
```
### Node.js
```javascript
const response = await fetch("https://sandbox.payme.io/api/generate-sale", {
method: "POST",
headers: {
"Content-Type": "application/json",
},
body: JSON.stringify({
"seller_payme_id": "MPL00009-00009EXM-EXAMPLE0-EXAMPLE9",
"sale_price": "1000",
"currency": "ILS",
"product_name": "Shirt",
"language": "en",
"sale_type": "token",
"sale_payment_method": "il-direct-debit",
"sale_return_url": "https://sport5.co.il"
}),
});
console.log(await response.text());
```
### Python
```python
import requests
response = requests.post(
"https://sandbox.payme.io/api/generate-sale",
json={
"seller_payme_id": "MPL00009-00009EXM-EXAMPLE0-EXAMPLE9",
"sale_price": "1000",
"currency": "ILS",
"product_name": "Shirt",
"language": "en",
"sale_type": "token",
"sale_payment_method": "il-direct-debit",
"sale_return_url": "https://sport5.co.il",
},
)
print(response.text)
```
### PHP
```php
'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;
```
## Responses
### 200 — OK (success)
| Field | Type | Description |
| --- | --- | --- |
| `status_code` | string | Status of the request (0 - success, 1 - error) |
| `sale_url` | string | The URL of the IFRAME secured payment form to display to the buyer |
| `payme_sale_id` | string | Our unique sale ID |
| `payme_sale_code` | integer | Our unique sale code (for display purposes only) |
| `price` | integer | Sale final price. For example, if the price is 50.75 (max 2 decimal points) the value that needs to be sent is 5075 |
| `transaction_id` | string | Transaction ID |
| `currency` | string | |
| `sale_payment_method` | string | The sale payment method. Must be il-direct-debit for the authorization setup process |
```json
{
"status_code": 0,
"sale_url": "https://sandbox.payme.io/sale/generate/SALETEST-XXXXXXXX-XXXXXXXX-XXXXXXXX",
"payme_sale_id": "SALE1687-957072WX-0MEX63QM-GMHDMGNU",
"payme_sale_code": 1234567,
"price": 1000,
"transaction_id": "12345",
"currency": "ILS",
"sale_payment_method": "il-direct-debit"
}
```
## Subscriptions
- [Generate](https://docs-staging.payme.io/payments/subscriptions/post-generate-subscription): POST /generate-subscription — Generate
# Generate
- Sandbox: `POST https://sandbox.payme.io/api/generate-subscription`
- Production: `POST https://live.payme.io/api/generate-subscription`
## Credentials
- Request body field `payme_client_key` (required): PayMe Partner Key.
- Request body field `seller_payme_id` (required): MPL. Your private key in PayMe system.
## Overview
This endpoint is used to generate new subscriptions.
You can find more information in our guide - [How to create a subscription
](/marketplaces-and-platforms/payments/how-to-create-subscription).
## Parameters
This endpoint takes no path, query or header parameters.
## Request body
Content type: `application/json`
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `payme_client_key` | string | yes | PayMe Partner Key. |
| `seller_payme_id` | string | yes | MPL. Your private key in PayMe system. |
| `sub_currency` | string | yes | Subscription currency. [3-letter ISO 4217 name](https://en.wikipedia.org/wiki/ISO_4217). |
| `sub_price` | string | yes | A single iteration final price. For example, if the price is 50.75 (max 2 decimal points) the value that needs to be sent is 5075. Note that the minimum value is 500 |
| `sub_description` | string | yes | The description of the service/product |
| `sub_iteration_type` | string | yes | 1 - Daily, 2 - Weekly, 3 - Monthly, 4 - Yearly |
| `language` | string | no | Changes the language of the payment IFRAME to English, as well as the error messages. Default value is Hebrew (he) |
| `sub_start_date` | string | no | Subscription initiation date. For iteration type = 3 (monthly) the day value should be between 1 to 28 |
| `sub_payment_method` | string | no | Sale Payment Method (for the list see [Payment Methods](/payments/direct-api/available-payment-methods)) |
| `sub_type` | number | no | subscription type: 1-regular, 10-template |
| `buyer_key` | string | no | Buyer key for subscription payment with the token. Relevant only for sub_type = regular. This key is received through the use of capture_buyer. Note that with this attribute no need to activate pay-subscription. |
| `subscription_id` | string | no | Merchant's unique subscription ID for correlation with us |
| `sub_iterations` | number | no | The iterations count set for the subscription. Default value is set to unlimited by -1 value. |
| `sub_callback_url` | string | no | Callback response to your page regarding updates on subscription events. |
| `sub_return_url` | string | no | Once the subscription was paid successfully, the user will be redirected to this URL Relevant to the first subscription iteration, if it is paid through our iframe. |
| `sub_indicative_name` | string | no | Indicative name for the subscribition |
| `sub_email_address` | string | no | Email address of the subscription payer |
| `sub_indicative_mobile` | string | no | Phone number to send receipt |
| `sub_send_notification` | boolean | no | Indication if to send notifications on subscription events. |
### Request example
```json
{
"seller_payme_id": "XXXXXXXX-XXXXXXXX-XXXXXXXX-XXXXXXXX",
"sub_price": 500,
"sub_currency": "USD",
"sub_description": "Subscription for something",
"sub_iteration_type": "3",
"sub_iterations": 12,
"sub_start_date": "1440354488",
"sub_callback_url": "https://www.example.com/payment/callback",
"sub_return_url": "https://www.example.com/payment/success",
"buyer_key": "XXXXXXXX",
"language": "en"
}
```
## Code samples
### curl
```bash
curl -X POST 'https://sandbox.payme.io/api/generate-subscription' \
-H 'Content-Type: application/json' \
--data-raw '{
"seller_payme_id": "XXXXXXXX-XXXXXXXX-XXXXXXXX-XXXXXXXX",
"sub_price": 500,
"sub_currency": "USD",
"sub_description": "Subscription for something",
"sub_iteration_type": "3",
"sub_iterations": 12,
"sub_start_date": "1440354488",
"sub_callback_url": "https://www.example.com/payment/callback",
"sub_return_url": "https://www.example.com/payment/success",
"buyer_key": "XXXXXXXX",
"language": "en"
}'
```
### Node.js
```javascript
const response = await fetch("https://sandbox.payme.io/api/generate-subscription", {
method: "POST",
headers: {
"Content-Type": "application/json",
},
body: JSON.stringify({
"seller_payme_id": "XXXXXXXX-XXXXXXXX-XXXXXXXX-XXXXXXXX",
"sub_price": 500,
"sub_currency": "USD",
"sub_description": "Subscription for something",
"sub_iteration_type": "3",
"sub_iterations": 12,
"sub_start_date": "1440354488",
"sub_callback_url": "https://www.example.com/payment/callback",
"sub_return_url": "https://www.example.com/payment/success",
"buyer_key": "XXXXXXXX",
"language": "en"
}),
});
console.log(await response.text());
```
### Python
```python
import requests
response = requests.post(
"https://sandbox.payme.io/api/generate-subscription",
json={
"seller_payme_id": "XXXXXXXX-XXXXXXXX-XXXXXXXX-XXXXXXXX",
"sub_price": 500,
"sub_currency": "USD",
"sub_description": "Subscription for something",
"sub_iteration_type": "3",
"sub_iterations": 12,
"sub_start_date": "1440354488",
"sub_callback_url": "https://www.example.com/payment/callback",
"sub_return_url": "https://www.example.com/payment/success",
"buyer_key": "XXXXXXXX",
"language": "en",
},
)
print(response.text)
```
### PHP
```php
'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;
```
## Responses
### 200 — OK (success)
| Field | Type | Description |
| --- | --- | --- |
| `sub_url` | string | Subscription Unique URL |
| `status_code` | string | Status code (0 - sucess, 1 - failed) |
| `payme_status` | string | PayMe updated status` |
| `seller_payme_id` | string | |
| `seller_id` | string | Our unique seller ID |
| `sub_payme_id` | string | PayMe's unique subscription ID |
| `sub_payme_code` | string | PayMe's subscription code |
| `subscription_id` | string | Subscription unique ID |
| `sub_created` | string | The date the subscription was created |
| `sub_start_date` | string | Subscription initiation date |
| `sub_prev_date` | string | Previous subscription payment date |
| `sub_next_date` | string | Subscription next payment due date |
| `sub_status` | string | Subscription status (0 - active, 1 - inactive) |
| `sub_iteration_type` | string | 1 - Daily, 2 - Weekly, 3 - Monthly, 4 - Yearly |
| `sub_currency` | string | Subscription currency. [3-letter ISO 4217 name](https://en.wikipedia.org/wiki/ISO_4217). |
| `sub_price` | string | A single iteration final price. For example, if the price is 50.75 (max 2 decimal points) the value that needs to be sent is 5075. Note that the minimum value is 500 |
| `sub_description` | string | Subscription description - What is the subscription for? |
| `sub_iterations` | string | The iterations count set for the subscription according to the request command |
| `sub_iterations_completed` | number | The number of iterations completed for the specific subscription |
| `sub_iterations_left` | string | Count of iteration left for the specific subscription |
| `sub_paid` | boolean | Was the subscription fully paid or not |
| `status_error_code` | number | Error code in case of an error |
| `sub_error_text` | string | Error description in case of an error |
```json
{
"sub_url": "string",
"status_code": "0",
"payme_status": "string",
"status_error_code": "string",
"seller_payme_id": "string",
"seller_id": "string",
"sub_payme_id": "string",
"sub_payme_code": "string",
"subscription_id": "string",
"sub_created": "string",
"sub_start_date": "string",
"sub_prev_date": "string",
"sub_status": "string",
"sub_next_date": "string",
"sub_iteration_type": "string",
"sub_currency": "string",
"sub_price": "string",
"sub_description": "string",
"sub_iterations": "string",
"sub_iterations_completed": 0,
"sub_iterations_left": "string",
"sub_paid": true,
"sub_error_text": "string"
}
```
### 500 — Internal Server Error (error)
| Field | Type | Description |
| --- | --- | --- |
| `status_code` | number | Status code 1 (for failure) |
| `status_error_details` | string | What caused the error |
| `status_additional_info` | string | The parameters related to the error |
| `status_error_code` | number | Status error code - 1 |
```json
{
"status_code": 1,
"status_error_details": "Required parameter is missing",
"status_additional_info": "seller_payme_id",
"status_error_code": 1
}
```
- [Recurring Payments](https://docs-staging.payme.io/payments/subscriptions/recurring-payments): Recurring payments help you to oversee regular payments for subscriptions, providing convenience to customers and predictable revenue streams for your business.
# Recurring Payments
Recurring payments help you to oversee regular payments for subscriptions, providing convenience to customers and predictable revenue streams for your business.
PayMe's subscriptions are a common use case for recurring payments, allowing customers to easily manage and pay for services on a regular basis.
PayMe's tokenization secures recurring payments by replacing sensitive data with unique tokens, simplifies compliance by reducing the scope of PCI DSS requirements for your business.
- [Pay](https://docs-staging.payme.io/payments/subscriptions/post-generate-subscription-2): POST /pay-subscription — Pay
# Pay
- Sandbox: `POST https://sandbox.payme.io/api/pay-subscription`
- Production: `POST https://live.payme.io/api/pay-subscription`
## Credentials
No credentials are documented for this endpoint.
## Overview
**Relevant only for Direct API Integration**
This endpoint is used to pay subscriptions.
**No API key is needed.** The subscription (`sub_payme_id`) identifies the seller, so — like pay-sale — this call can be made from the buyer's browser. Do not send `seller_payme_id` or `payme_client_key` here.
Only a subscription whose status is initial, failed or failed-retry can be paid; any other status returns error `305`.
You can find more information in our guide - [How to create a subscription
](/marketplaces-and-platforms/payments/how-to-create-subscription).
## Parameters
This endpoint takes no path, query or header parameters.
## Request body
Content type: `application/json`
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `sub_payme_id` | string | yes | Our unique subscription ID |
| `credit_card_number` | string | yes | Buyer's credit card number |
| `credit_card_cvv` | string | yes | Buyer's credit card CVV |
| `credit_card_exp` | string | yes | Buyer's credit card expiary date |
| `buyer_email` | string | yes | Buyer's email address |
| `buyer_name` | string | yes | Buyer's full name |
### Request example
```json
{
"sub_payme_id": "SUB16885-68336QPL-UQSSS1CC-SYKXI53N",
"credit_card_number": "4580458045804580",
"credit_card_cvv": "123",
"credit_card_exp": "0130",
"buyer_email": "user2@example.com",
"buyer_name": "sarit hadad"
}
```
## Code samples
### curl
```bash
curl -X POST 'https://sandbox.payme.io/api/pay-subscription' \
-H 'Content-Type: application/json' \
--data-raw '{
"sub_payme_id": "SUB16885-68336QPL-UQSSS1CC-SYKXI53N",
"credit_card_number": "4580458045804580",
"credit_card_cvv": "123",
"credit_card_exp": "0130",
"buyer_email": "user2@example.com",
"buyer_name": "sarit hadad"
}'
```
### Node.js
```javascript
const response = await fetch("https://sandbox.payme.io/api/pay-subscription", {
method: "POST",
headers: {
"Content-Type": "application/json",
},
body: JSON.stringify({
"sub_payme_id": "SUB16885-68336QPL-UQSSS1CC-SYKXI53N",
"credit_card_number": "4580458045804580",
"credit_card_cvv": "123",
"credit_card_exp": "0130",
"buyer_email": "user2@example.com",
"buyer_name": "sarit hadad"
}),
});
console.log(await response.text());
```
### Python
```python
import requests
response = requests.post(
"https://sandbox.payme.io/api/pay-subscription",
json={
"sub_payme_id": "SUB16885-68336QPL-UQSSS1CC-SYKXI53N",
"credit_card_number": "4580458045804580",
"credit_card_cvv": "123",
"credit_card_exp": "0130",
"buyer_email": "user2@example.com",
"buyer_name": "sarit hadad",
},
)
print(response.text)
```
### PHP
```php
'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;
```
## Responses
### 200 — OK (success)
| Field | Type | Description |
| --- | --- | --- |
| `status_code` | integer | Cancellation status code ( 0 - Success, 1 - Failure) |
| `payme_status` | string | PayMe status |
| `seller_payme_id` | string | Our unique seller ID (MPL) |
| `sub_payme_id` | string | Subscription ID |
| `sub_payme_code` | integer | Subscription code |
| `sub_created` | string | Subscription creation timestamp |
| `sub_start_date` | string | Subscription start timestamp |
| `sub_prev_date` | string | Subscription last payment date |
| `sub_next_date` | string | Subscription next payment date |
| `sub_status` | integer | You can find all the subscription statuses [Subscription Statuses](/marketplaces-and-platforms/lists-statuses/subscription-statuses) |
| `sub_iteration_type` | integer | You can find all the subscription iteration types [Subscription Iteration Types](/marketplaces-and-platforms/lists-statuses/subscription-iteration-types) |
| `sub_currency` | string | Subscription currency |
| `sub_price` | integer | Total subscription price |
| `sub_description` | string | Subscription description |
| `sub_iterations` | integer | Number of iterations |
| `sub_iterations_completed` | integer | Number of iterations that was paid |
| `sub_iterations_skipped` | integer | The count of unpaid iterations and their corresponding dates have elapsed. |
| `sub_iterations_left` | integer | The count of iterations left |
| `sub_paid` | boolean | Indicates if the current iteration paid |
| `sub_payment_date` | string | The payment due date |
| `buyer_card_mask` | string | Buyer's credit card number |
| `buyer_card_exp` | string | Buyer's credit card expiary date |
| `buyer_name` | string | Buyer's full name |
| `buyer_email` | string | Buyer's email address |
| `buyer_phone` | string | Buyer's phone number |
| `buyer_social_id` | string | Buyer's social ID |
```json
{
"status_code": 0,
"payme_status": "success",
"status_error_code": 0,
"seller_payme_id": "MPL90005-90005EXM-EXAMPLE0-EXAMPLE9",
"sub_payme_id": "SUB16885-68336QPL-UQSSS1CC-SYKXI53N",
"sub_payme_code": 477004,
"sub_created": "2023-07-05 17:45:36",
"sub_start_date": "2023-07-05 17:45:36",
"sub_prev_date": null,
"sub_next_date": "2023-07-05 17:45:36",
"sub_status": 2,
"sub_iteration_type": 1,
"sub_currency": "USD",
"sub_price": 100,
"sub_description": "sub-description",
"sub_iterations": -1,
"sub_iterations_completed": 0,
"sub_iterations_skipped": 0,
"sub_iterations_left": -1,
"sub_paid": true,
"sub_error_text": null,
"sub_payment_date": "2022-08-15 15:51:29",
"buyer_card_mask": "458045******4580",
"buyer_card_exp": "0130",
"buyer_name": "Jhon Doe",
"buyer_email": "user3@example.com",
"buyer_phone": null,
"buyer_social_id": null
}
```
### 500 — Internal Server Error (error)
| Field | Type | Description |
| --- | --- | --- |
| `status_code` | number | Status code 1 (for failure) |
| `status_error_details` | string | What caused the error |
| `status_additional_info` | string | The parameters related to the error |
| `status_error_code` | number | Status error code - 1 |
```json
{
"status_code": 1,
"status_error_details": "Required parameter is missing",
"status_additional_info": "seller_payme_id",
"status_error_code": 1
}
```
- [Cancel](https://docs-staging.payme.io/payments/subscriptions/postcancel-subscription): POST /cancel-subscription — Cancel
# Cancel
- Sandbox: `POST https://sandbox.payme.io/api/cancel-subscription`
- Production: `POST https://live.payme.io/api/cancel-subscription`
## Credentials
- Request body field `seller_payme_id` (required): Our unique seller ID
## Overview
This endpoint is used to cancel existing subscriptions.
## Parameters
This endpoint takes no path, query or header parameters.
## Request body
Content type: `application/json`
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `seller_payme_id` | string | yes | Our unique seller ID |
| `sub_payme_id` | string | yes | Our unique subscription ID |
| `language` | string | no | Changes the error message language to English. Default value is Hebrew (he) |
### Request example
```json
{
"seller_payme_id": "string",
"sub_payme_id": "string"
}
```
## Code samples
### curl
```bash
curl -X POST 'https://sandbox.payme.io/api/cancel-subscription' \
-H 'Content-Type: application/json' \
--data-raw '{
"seller_payme_id": "string",
"sub_payme_id": "string"
}'
```
### Node.js
```javascript
const response = await fetch("https://sandbox.payme.io/api/cancel-subscription", {
method: "POST",
headers: {
"Content-Type": "application/json",
},
body: JSON.stringify({
"seller_payme_id": "string",
"sub_payme_id": "string"
}),
});
console.log(await response.text());
```
### Python
```python
import requests
response = requests.post(
"https://sandbox.payme.io/api/cancel-subscription",
json={
"seller_payme_id": "string",
"sub_payme_id": "string",
},
)
print(response.text)
```
### PHP
```php
'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;
```
## Responses
### 200 — OK (success)
| Field | Type | Description |
| --- | --- | --- |
| `status_code` | string | Cancellation status code ( 0 - Success, 1 - Failure) |
```json
{
"status_code": "string"
}
```
### 500 — Internal Server Error (error)
| Field | Type | Description |
| --- | --- | --- |
| `status_code` | string | Cancellation status code ( 0 - Success, 1 - Failure) |
```json
{
"status_code": "string"
}
```
- [Pause](https://docs-staging.payme.io/payments/subscriptions/post-pause-subscription): POST /pause-subscription — Pause
# Pause
- Sandbox: `POST https://sandbox.payme.io/api/pause-subscription`
- Production: `POST https://live.payme.io/api/pause-subscription`
## Credentials
- Request body field `seller_payme_id` (optional): MPL. Your private key in PayMe system.
## Overview
**Relevant only for Direct API Integration**
This endpoint is used to pause subscriptions.
You can find more information in our guide - [How to create a subscription
](/marketplaces-and-platforms/payments/how-to-create-subscription).
## Parameters
This endpoint takes no path, query or header parameters.
## Request body
Content type: `application/json`
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `seller_payme_id` | string | no | MPL. Your private key in PayMe system. |
| `sub_payme_id` | string | no | PayMe's unique subscription ID |
### Request example
```json
{
"seller_payme_id": "MPL00007-00007EXM-EXAMPLE0-EXAMPLE7",
"sub_payme_id": "SUB16999-507640UD-83RNQDGN-YHSXHXHG"
}
```
## Code samples
### curl
```bash
curl -X POST 'https://sandbox.payme.io/api/pause-subscription' \
-H 'Content-Type: application/json' \
--data-raw '{
"seller_payme_id": "MPL00007-00007EXM-EXAMPLE0-EXAMPLE7",
"sub_payme_id": "SUB16999-507640UD-83RNQDGN-YHSXHXHG"
}'
```
### Node.js
```javascript
const response = await fetch("https://sandbox.payme.io/api/pause-subscription", {
method: "POST",
headers: {
"Content-Type": "application/json",
},
body: JSON.stringify({
"seller_payme_id": "MPL00007-00007EXM-EXAMPLE0-EXAMPLE7",
"sub_payme_id": "SUB16999-507640UD-83RNQDGN-YHSXHXHG"
}),
});
console.log(await response.text());
```
### Python
```python
import requests
response = requests.post(
"https://sandbox.payme.io/api/pause-subscription",
json={
"seller_payme_id": "MPL00007-00007EXM-EXAMPLE0-EXAMPLE7",
"sub_payme_id": "SUB16999-507640UD-83RNQDGN-YHSXHXHG",
},
)
print(response.text)
```
### PHP
```php
'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;
```
## Responses
### 200 — OK (success)
| Field | Type | Description |
| --- | --- | --- |
| `status_code` | integer | |
| `payme_status` | string | |
| `status_error_code` | integer | |
| `seller_payme_id` | string | |
| `seller_id` | string | |
| `sub_payme_id` | string | |
| `sub_payme_code` | integer | |
| `subscription_id` | string | |
| `sub_created` | string | |
| `sub_start_date` | string | |
| `sub_prev_date` | string | |
| `sub_next_date` | string | |
| `sub_status` | integer | |
| `sub_iteration_type` | integer | |
| `sub_currency` | string | |
| `sub_price` | integer | |
| `sub_description` | string | |
| `sub_iterations` | integer | |
| `sub_iterations_completed` | integer | |
| `sub_iterations_skipped` | integer | |
| `sub_iterations_left` | integer | |
| `sub_paid` | boolean | |
| `sub_error_text` | string | |
| `sub_payment_date` | string | |
| `buyer_card_mask` | string | |
| `buyer_card_exp` | string | |
| `buyer_name` | string | |
| `buyer_email` | string | |
| `buyer_phone` | string | |
| `buyer_social_id` | string | |
```json
{
"status_code": 0,
"payme_status": "success",
"status_error_code": 0,
"seller_payme_id": "MPL00007-00007EXM-EXAMPLE0-EXAMPLE7",
"seller_id": null,
"sub_payme_id": "SUB16999-507640UD-83RNQDGN-YHSXHXHG",
"sub_payme_code": 343324,
"subscription_id": null,
"sub_created": "2023-11-14 10:32:44",
"sub_start_date": "2023-11-14 08:00:00",
"sub_prev_date": null,
"sub_next_date": "2023-11-14 08:00:00",
"sub_status": 3,
"sub_iteration_type": 1,
"sub_currency": "ILS",
"sub_price": 10000,
"sub_description": "blablabla",
"sub_iterations": 1,
"sub_iterations_completed": 0,
"sub_iterations_skipped": 0,
"sub_iterations_left": 1,
"sub_paid": true,
"sub_error_text": "הושהה על ידי המשתמש בתאריך 14/11/2023 10:33:35",
"sub_payment_date": "2023-10-31 14:23:49",
"buyer_card_mask": "532610******5846",
"buyer_card_exp": "0426",
"buyer_name": "Ran Tester",
"buyer_email": "TestTest@paymeservice.com",
"buyer_phone": "05222222",
"buyer_social_id": "123456789"
}
```
- [Resume](https://docs-staging.payme.io/payments/subscriptions/patch-subscriptions-sub-payme-id-resume): PATCH /subscriptions/{sub_payme_id}/resume — Resume
# Resume
- Sandbox: `PATCH https://sandbox.payme.io/api/subscriptions/{sub_payme_id}/resume`
- Production: `PATCH https://live.payme.io/api/subscriptions/{sub_payme_id}/resume`
## Credentials
- Header `PayMe-Merchant-Key` (API key)
## Overview
**Relevant only for Direct API Integration**
This endpoint is used to resume subscriptions is in status "paused".
You can find more information in our guide - [How to create a subscription
](/marketplaces-and-platforms/payments/how-to-create-subscription).
## Parameters
| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `PayMe-Merchant-Key` | header | string | no | MPL. Your private key in PayMe system. |
| `sub_payme_id` | path | string | yes | |
## Request body
Content type: `application/json`
## Code samples
### curl
```bash
curl -X PATCH 'https://sandbox.payme.io/api/subscriptions//resume' \
-H 'Content-Type: application/json' \
-H 'PayMe-Merchant-Key: ' \
--data-raw '{}'
```
### Node.js
```javascript
const response = await fetch("https://sandbox.payme.io/api/subscriptions//resume", {
method: "PATCH",
headers: {
"Content-Type": "application/json",
"PayMe-Merchant-Key": "",
},
body: JSON.stringify({}),
});
console.log(await response.text());
```
### Python
```python
import requests
response = requests.patch(
"https://sandbox.payme.io/api/subscriptions//resume",
headers={
"PayMe-Merchant-Key": "",
},
json={},
)
print(response.text)
```
### PHP
```php
/resume');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'PATCH',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Content-Type: application/json',
'PayMe-Merchant-Key: ',
],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;
```
## Responses
### 200 — OK (success)
- [Update Price](https://docs-staging.payme.io/payments/subscriptions/patch-subscriptions-sub-id-set-price): PATCH /subscriptions/{sub_id}/set-price — Update Price
# Update Price
- Sandbox: `PATCH https://sandbox.payme.io/api/subscriptions/{sub_id}/set-price`
- Production: `PATCH https://live.payme.io/api/subscriptions/{sub_id}/set-price`
## Credentials
- Request body field `seller_payme_id` (required): MPL. Your private key in PayMe system.
## Overview
This endpoint is used to update a subscription price.
This will apply subscriptions in status "active" or subscription template in status "initial".
You can find more information in our guide - [Subscriptions
](/payments/subscriptions/post-generate-subscription).
## Parameters
| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `sub_id` | path | string | yes | |
## Request body
Content type: `application/json`
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `seller_payme_id` | string | yes | MPL. Your private key in PayMe system. |
| `sub_price` | string | yes | A single iteration final price. For example, if the price is 50.75 (max 2 decimal points) the value that needs to be sent is 5075. Note that the minimum value is 500 |
### Request example
```json
{
"seller_payme_id": "MPLDEMO-MPLDEMO-MPLDEMO-1234567",
"sub_price": 500
}
```
## Code samples
### curl
```bash
curl -X PATCH 'https://sandbox.payme.io/api/subscriptions//set-price' \
-H 'Content-Type: application/json' \
--data-raw '{
"seller_payme_id": "MPLDEMO-MPLDEMO-MPLDEMO-1234567",
"sub_price": 500
}'
```
### Node.js
```javascript
const response = await fetch("https://sandbox.payme.io/api/subscriptions//set-price", {
method: "PATCH",
headers: {
"Content-Type": "application/json",
},
body: JSON.stringify({
"seller_payme_id": "MPLDEMO-MPLDEMO-MPLDEMO-1234567",
"sub_price": 500
}),
});
console.log(await response.text());
```
### Python
```python
import requests
response = requests.patch(
"https://sandbox.payme.io/api/subscriptions//set-price",
json={
"seller_payme_id": "MPLDEMO-MPLDEMO-MPLDEMO-1234567",
"sub_price": 500,
},
)
print(response.text)
```
### PHP
```php
/set-price');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'PATCH',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;
```
## Responses
### 200 — OK (success)
| Field | Type | Description |
| --- | --- | --- |
| `status_code` | integer | Status of the request (0 - success, 1 - error)> Allowed values `0` `1` |
### 400 (error)
| Field | Type | Description |
| --- | --- | --- |
| `status_code` | integer | Status of the request (0 - success, 1 - error)> Allowed values `0` `1` |
| `status_error_details` | string | |
| `status_additional_info` | string | |
| `status_error_code` | number | |
## Tokenization
- [Capture Buyer Token](https://docs-staging.payme.io/payments/tokenization/post-capture-buyer-token): POST /capture-buyer-token — Capture Buyer Token
# Capture Buyer Token
- Sandbox: `POST https://sandbox.payme.io/api/capture-buyer-token`
- Production: `POST https://live.payme.io/api/capture-buyer-token`
## Credentials
- Request body field `seller_payme_id` (required): Our unique seller ID
## Overview
This endpoint can be used only if you are PCI compliant and are able to handle raw credit card infromation.
This end-point is used to create a new token, by sending a request with the full credit card data and getting a response with the token. This token can be used later on to perform sales and other payment actions.
## Parameters
This endpoint takes no path, query or header parameters.
## Request body
Content type: `application/json`
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `seller_payme_id` | string | yes | Our unique seller ID |
| `buyer_name` | string | no | Buyer's full name |
| `buyer_social_id` | string | no | Buyer's social ID number |
| `buyer_email` | string | no | Buyer's email address |
| `buyer_phone` | string | no | Buyer's phone number |
| `buyer_zip_code` | string | no | Buyer's address zip code |
| `credit_card_number` | integer | yes | Card number |
| `credit_card_exp` | string | yes | Buyer's card exp (MMYY) |
| `credit_card_cvv` | integer | yes | |
| `buyer_perform_validation` | boolean | no | Flag for performing an online validation of the card with the Issuer. |
### Request example
```json
{
"seller_payme_id": "MPLDEMO-MPLDEMO-MPLDEMO-1234567",
"buyer_name": "Idan testing",
"buyer_social_id": "123456789",
"buyer_email": "TestTest@paymeservice.com",
"buyer_phone": "05222222",
"buyer_zip_code": "1q2w3exx",
"credit_card_number": 4111111111111111,
"credit_card_exp": "0322",
"credit_card_cvv": 123
}
```
## Code samples
### curl
```bash
curl -X POST 'https://sandbox.payme.io/api/capture-buyer-token' \
-H 'Content-Type: application/json' \
--data-raw '{
"seller_payme_id": "MPLDEMO-MPLDEMO-MPLDEMO-1234567",
"buyer_name": "Idan testing",
"buyer_social_id": "123456789",
"buyer_email": "TestTest@paymeservice.com",
"buyer_phone": "05222222",
"buyer_zip_code": "1q2w3exx",
"credit_card_number": 4111111111111111,
"credit_card_exp": "0322",
"credit_card_cvv": 123
}'
```
### Node.js
```javascript
const response = await fetch("https://sandbox.payme.io/api/capture-buyer-token", {
method: "POST",
headers: {
"Content-Type": "application/json",
},
body: JSON.stringify({
"seller_payme_id": "MPLDEMO-MPLDEMO-MPLDEMO-1234567",
"buyer_name": "Idan testing",
"buyer_social_id": "123456789",
"buyer_email": "TestTest@paymeservice.com",
"buyer_phone": "05222222",
"buyer_zip_code": "1q2w3exx",
"credit_card_number": 4111111111111111,
"credit_card_exp": "0322",
"credit_card_cvv": 123
}),
});
console.log(await response.text());
```
### Python
```python
import requests
response = requests.post(
"https://sandbox.payme.io/api/capture-buyer-token",
json={
"seller_payme_id": "MPLDEMO-MPLDEMO-MPLDEMO-1234567",
"buyer_name": "Idan testing",
"buyer_social_id": "123456789",
"buyer_email": "TestTest@paymeservice.com",
"buyer_phone": "05222222",
"buyer_zip_code": "1q2w3exx",
"credit_card_number": 4111111111111111,
"credit_card_exp": "0322",
"credit_card_cvv": 123,
},
)
print(response.text)
```
### PHP
```php
'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;
```
## Responses
### 200 — OK (success)
| Field | Type | Description |
| --- | --- | --- |
| `status_code` | integer | Action status code (0 - Success, 1 - Failure) |
| `buyer_key` | string | Buyer's unique token |
| `buyer_name` | string | Buyer's full name |
| `buyer_email` | string | Buyer's email address |
| `buyer_phone` | string | Buyer's phone number |
| `buyer_card_mask` | string | Buyer's card mask |
| `buyer_card_exp` | string | Buyer's card exp (MMYY) |
| `buyer_social_id` | string | Buyer's social ID number |
| `buyer_is_permanent` | boolean | Is the token temporary or permanant |
| `buyer_status` | integer | The status's buyer |
```json
{
"status_code": 0,
"buyer_key": "BUYER168-6667348Q-V8Z99RXJ-CQ60HNGY",
"buyer_name": "Ran Tester",
"buyer_email": "TestTest@paymeservice.com",
"buyer_phone": "05222222",
"buyer_card_mask": "532610******5846",
"buyer_card_exp": "0426",
"buyer_social_id": "123456789",
"buyer_is_permanent": false,
"buyer_status": null
}
```
### 356 (error)
| Field | Type | Description |
| --- | --- | --- |
| `status_code` | integer | |
| `status_error_details` | string | |
| `status_additional_info` | boolean | |
| `status_error_code` | integer | |
| `session` | string | |
```json
{
"status_code": 1,
"status_error_details": "תוקף כרטיס אשראי לא תקין",
"status_additional_info": false,
"status_error_code": 356,
"session": "khANe7Jl"
}
```
### 500 — Internal Server Error (error)
| Field | Type | Description |
| --- | --- | --- |
| `status_code` | integer | |
| `status_error_details` | string | |
| `status_additional_info` | string | |
| `status_error_code` | integer | |
| `session` | string | |
```json
{
"status_code": 1,
"status_error_details": "Required parameter is missing",
"status_additional_info": "credit_card_cvv",
"status_error_code": 1,
"session": "0PFThooQ"
}
```
- [Generate Sale with Token](https://docs-staging.payme.io/payments/tokenization/post-generate-sale-tokenization): How to call POST /generate-sale for Tokenization.
# Generate Sale with Token
This is a variant of [POST /generate-sale — Generate Payment](https://docs-staging.payme.io/payments/hosted-payment-page/post-generate-sale); the request and responses below are the ones documented for Tokenization.
- Sandbox: `POST https://sandbox.payme.io/api/generate-sale`
- Production: `POST https://live.payme.io/api/generate-sale`
## Credentials
- Request body field `seller_payme_id` (required): your seller ID (MPL). It authenticates the request, so send it only from your server.
## Overview
#### Generating tokens
Please yeste that you can receive a token representing the buyer (including credit card information) as part of the [`generate-sale`](https://docs.paymeservice.com/docs/payme-public/b3A6MjYyMzkxODU-generate-sale) API call. This token can be used to generate future server-to-server sales without requiring the buyer to re-enter his credit card information. The token will be returned only as part of the callback.
#### Obtaining Tokens
There are two ways of obtaining a token:
In order to receive a token in addition to charging the credit card use the `capture_buyer` attribute.
In order to receive a token without charging the credit card use the dedicated `sale_type` attribute and set the value to token.
Attribute| Description
---|---
`capture_buyer`| `1` Flag for requesting the buyer's token in addition to charging the credit card (0 - do yest capture token, 1 - capture token)
`sale_type` |`token` Flag for requesting the buyer's token without charging the credit card
#### Charging Tokens
After generating a token you may charge the buyer at any point by using the buyer_key attribute when generating a new sale.
Attribute| Description
---|---
`buyer_key` |`XXXXXXXX-XXXXXXXX-XXXXXXXX-XXXXXXXX` Buyer key for an instant-payment with the token
## Parameters
This endpoint takes yes path, query or header parameters.
## Request body
Content type: `application/json`
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `seller_payme_id` | string | yes | MPL. Your private key in PayMe system. |
| `sale_price` | integer | no | For example, if the price is 50.75 (max 2 decimal points) the value that needs to be sent is 5075. Note that the minimum value is 500. |
| `currency` | string | no | Sale currency. [3-letter ISO 4217 name](https://en.wikipedia.org/wiki/ISO_4217). |
| `product_name` | string | no | Short name and description of the product/service. This text will be shown in the invoice as well, if the seller has enabled the invoices module in his account panel. Limited to 500 characters |
| `transaction_id` | string | no | Merchant's unique sale ID for correlation with us |
| `installments` | string | no | Amount of installments for the sale. We allow you to manually set the number of installments or to specify a top limit of installments for the buyer to choose from while paying. Setting a fixed number of installments is simply entering a number between 1 and 12. The sale will be initiated with this number of installments and the buyer will not be able to change it. To set a range for the buyer to choose from, enter the following: 103 - allow up to 3 installments 106 - allow up to 6 installments 109 - allow up to 9 installments 112 - allow up to 12 installments |
| `market_fee` | number | no | A decimal representing the percent of the sale price that is collected for the marketplace (includes VAT). This fee is added on top of our fees and transferred to the marketplace once a month. Default value is the market fee of the Seller, as set upon Seller creation. |
| `sale_send_notification` | boolean | no | Flag to send email and/or SMS notifications |
| `sale_callback_url` | string | no | Callback response to your page regarding call to our API. Default value is taken from the Merchant's settings. Note that you may not send a "localhost" URL as value |
| `sale_email` | string | no | In case sale send notification is true provide the address to send email notification |
| `sale_return_url` | string | no | We will redirect the IFRAME and the buyer to this URL upon payment success. Default value is taken from the Merchant's settings |
| `sale_mobile` | string | no | In case sale send notification is true, provide the phone number to send SMS notification, if the seller has enabled the SMS module in his account panel |
| `sale_name` | string | no | The name that will be displayed when sending a notification |
| `capture_buyer` | boolean | no | Flag for requesting the buyer's token for this payment (0 - do not capture token, 1 - capture token). For additional information see Tokens explanation below |
| `buyer_perform_validation` | boolean | no | Flag for performing an online validation of the card with the Issuer. |
| `sale_type` | string | no | You can find all the sale types [Sale Types](https://docs-staging.payme.io/marketplaces-and-platforms/lists-statuses/sale-types). |
| `sale_payment_method` | string | no | the Payment method used to pay the sale. For all the payment methods see [Available Payment Methods](https://docs-staging.payme.io/payments/direct-api/available-payment-methods). |
| `layout` | string | no | IFRAME payment page layout. Optional attribute which may be used with "bit" sale_payment_method. Avai lable layouts are:dynamic, qr-sms or dynamic-loose dynamic loose removes the validation for the social ID and CVV. |
| `language` | string | no | Changes the language of the payment IFRAME to English, as well as the error messages. Default value is Hebrew (he) |
### Request example
```json
{
"seller_payme_id": "MPLDEMO-MPLDEMO-MPLDEMO-1234567",
"sale_price": 1000,
"currency": "ILS",
"product_name": "Smartphone",
"transaction_id": "12345",
"installments": "1",
"market_fee": 0.5,
"sale_send_notification": true,
"sale_callback_url": "https://www.payme.io",
"sale_email": "test@payme.io",
"sale_return_url": "https://www.payme.io",
"sale_mobile": "+9725254448888",
"sale_name": "Test User",
"capture_buyer": false,
"buyer_perform_validation": false,
"sale_type": "sale",
"sale_payment_method": "credit-card",
"layout": "string",
"language": "he"
}
```
## Code samples
### curl
```bash
curl -X POST 'https://sandbox.payme.io/api/generate-sale' \
-H 'Content-Type: application/json' \
--data-raw '{
"seller_payme_id": "MPLDEMO-MPLDEMO-MPLDEMO-1234567",
"sale_price": 1000,
"currency": "ILS",
"product_name": "Smartphone",
"transaction_id": "12345",
"installments": "1",
"market_fee": 0.5,
"sale_send_notification": true,
"sale_callback_url": "https://www.payme.io",
"sale_email": "test@payme.io",
"sale_return_url": "https://www.payme.io",
"sale_mobile": "+9725254448888",
"sale_name": "Test User",
"capture_buyer": false,
"buyer_perform_validation": false,
"sale_type": "sale",
"sale_payment_method": "credit-card",
"layout": "string",
"language": "he"
}'
```
### Node.js
```javascript
const response = await fetch("https://sandbox.payme.io/api/generate-sale", {
method: "POST",
headers: {
"Content-Type": "application/json",
},
body: JSON.stringify({
"seller_payme_id": "MPLDEMO-MPLDEMO-MPLDEMO-1234567",
"sale_price": 1000,
"currency": "ILS",
"product_name": "Smartphone",
"transaction_id": "12345",
"installments": "1",
"market_fee": 0.5,
"sale_send_notification": true,
"sale_callback_url": "https://www.payme.io",
"sale_email": "test@payme.io",
"sale_return_url": "https://www.payme.io",
"sale_mobile": "+9725254448888",
"sale_name": "Test User",
"capture_buyer": false,
"buyer_perform_validation": false,
"sale_type": "sale",
"sale_payment_method": "credit-card",
"layout": "string",
"language": "he"
}),
});
console.log(await response.text());
```
### Python
```python
import requests
response = requests.post(
"https://sandbox.payme.io/api/generate-sale",
json={
"seller_payme_id": "MPLDEMO-MPLDEMO-MPLDEMO-1234567",
"sale_price": 1000,
"currency": "ILS",
"product_name": "Smartphone",
"transaction_id": "12345",
"installments": "1",
"market_fee": 0.5,
"sale_send_notification": True,
"sale_callback_url": "https://www.payme.io",
"sale_email": "test@payme.io",
"sale_return_url": "https://www.payme.io",
"sale_mobile": "+9725254448888",
"sale_name": "Test User",
"capture_buyer": False,
"buyer_perform_validation": False,
"sale_type": "sale",
"sale_payment_method": "credit-card",
"layout": "string",
"language": "he",
},
)
print(response.text)
```
### PHP
```php
'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;
```
## Responses
### 200 — OK (success)
| Field | Type | Description |
| --- | --- | --- |
| `status_code` | integer | Status of the request (0 - success, 1 - error) |
| `sale_url` | string | The URL of the IFRAME secured payment form to display to the buyer |
| `payme_sale_id` | string | Our unique sale ID |
| `payme_sale_code` | integer | Our unique sale code (for display purposes only) |
| `price` | integer | Sale final price. For example, if the price is 50.75 (max 2 decimal points) the value that needs to be sent is 5075 |
| `transaction_id` | string | Merchant's unique sale ID for correlation with us |
| `currency` | string | Sale currency. [3-letter ISO 4217 name](https://en.wikipedia.org/wiki/ISO_4217). |
```json
{
"status_code": 0,
"sale_url": "string",
"payme_sale_id": "string",
"payme_sale_code": 12345678,
"price": 10000,
"transaction_id": "12345",
"currency": "string"
}
```
- [Get Buyer Key](https://docs-staging.payme.io/payments/tokenization/post-get-buyer-key): POST /get-buyer-key — Get Buyer Key
# Get Buyer Key
- Sandbox: `POST https://sandbox.payme.io/api/get-buyer-key`
- Production: `POST https://live.payme.io/api/get-buyer-key`
## Credentials
- Request body field `seller_payme_id` (required): Our unique seller ID.
## Overview
This API endpoint will allow you to get the buyer-key created and used to pay for a certain payment request in our system.
#### Use Case for Israeli Direct Debit
Once a new authorization request is created and the buyer is approved, a new buyer key is generated behind the scenes and can be obtained using this API endpoint.
## Parameters
This endpoint takes no path, query or header parameters.
## Request body
Content type: `application/json`
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `payme_sale_id` | string | yes | Our unique sale ID. |
| `seller_payme_id` | string | yes | Our unique seller ID. |
### Request example
```json
{
"payme_sale_id": "SALE1686-XXXXXXXX-XXXXXXXX-XXXXXXXX",
"seller_payme_id": "MPL16852-XXXXXXXX-XXXXXXXX-XXXXXXXX"
}
```
## Code samples
### curl
```bash
curl -X POST 'https://sandbox.payme.io/api/get-buyer-key' \
-H 'Content-Type: application/json' \
--data-raw '{
"payme_sale_id": "SALE1686-XXXXXXXX-XXXXXXXX-XXXXXXXX",
"seller_payme_id": "MPL16852-XXXXXXXX-XXXXXXXX-XXXXXXXX"
}'
```
### Node.js
```javascript
const response = await fetch("https://sandbox.payme.io/api/get-buyer-key", {
method: "POST",
headers: {
"Content-Type": "application/json",
},
body: JSON.stringify({
"payme_sale_id": "SALE1686-XXXXXXXX-XXXXXXXX-XXXXXXXX",
"seller_payme_id": "MPL16852-XXXXXXXX-XXXXXXXX-XXXXXXXX"
}),
});
console.log(await response.text());
```
### Python
```python
import requests
response = requests.post(
"https://sandbox.payme.io/api/get-buyer-key",
json={
"payme_sale_id": "SALE1686-XXXXXXXX-XXXXXXXX-XXXXXXXX",
"seller_payme_id": "MPL16852-XXXXXXXX-XXXXXXXX-XXXXXXXX",
},
)
print(response.text)
```
### PHP
```php
'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;
```
## Responses
### 200 — OK (success)
| Field | Type | Description |
| --- | --- | --- |
| `payme_sale_id` | string | Our unique sale ID. |
| `buyer_key` | string | Buyer's unique token. |
| `buyer_card_mask` | string | Buyer's card mask. |
| `buyer_card_expiry` | string | Buyer's card exp (MMYY). |
| `buyer_card_brand` | string | Buyer's card brand. |
| `status_code` | string | |
```json
{
"payme_sale_id": "MPL90005-90005EXM-EXAMPLE0-EXAMPLE9",
"buyer_key": "BUYER166-5640185F-UFEKYAYD-WLJSO6QS",
"buyer_card_mask": "532610******5846",
"buyer_card_expiry": "0426",
"buyer_card_brand": "099474924",
"buyer_is_permanent": null,
"status_code": null
}
```
### 600 (error)
| Field | Type | Description |
| --- | --- | --- |
| `status_code` | integer | |
| `status_error_details` | string | |
| `status_additional_info` | string | |
| `status_error_code` | integer | |
| `session` | string | |
```json
{
"status_code": 1,
"status_error_details": "Buyer not found",
"status_additional_info": "No Buyer for Sale",
"status_error_code": 600,
"session": "St4K2Azk"
}
```
- [Get card details by token](https://docs-staging.payme.io/payments/tokenization/post-buyer-token-to-card-number): POST /buyer-token-to-card-number — Get card details by token
# Get card details by token
- Sandbox: `POST https://sandbox.payme.io/api/buyer-token-to-card-number`
- Production: `POST https://live.payme.io/api/buyer-token-to-card-number`
## Credentials
- Request body field `seller_payme_id` (optional): Our unique seller ID.
## Overview
This endpoint can be used only if you are PCI compliant and allow to handle raw credit card infromation.
This end-point is used for receiving the full credit card data by sending a request with the buyer token.
Please note that in the response you won't receive CVV details, as we don't save it due to regulation.
## Parameters
This endpoint takes no path, query or header parameters.
## Request body
Content type: `application/json`
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `seller_payme_id` | string | no | Our unique seller ID. |
| `buyer_uuid2` | string | no | Buyer's public key |
| `buyer_key` | string | no | Buyer's private key |
### Request example
```json
{
"seller_payme_id": "MPL1DEMO-XXXXXXXX-XXXXXXXX-XXXXXXXX",
"buyer_uuid2": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
"buyer_key": "BUYER111-XXXXXXXX-XXXXXXXX-XXXXXXXX"
}
```
## Code samples
### curl
```bash
curl -X POST 'https://sandbox.payme.io/api/buyer-token-to-card-number' \
-H 'Content-Type: application/json' \
--data-raw '{
"seller_payme_id": "MPL1DEMO-XXXXXXXX-XXXXXXXX-XXXXXXXX",
"buyer_uuid2": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
"buyer_key": "BUYER111-XXXXXXXX-XXXXXXXX-XXXXXXXX"
}'
```
### Node.js
```javascript
const response = await fetch("https://sandbox.payme.io/api/buyer-token-to-card-number", {
method: "POST",
headers: {
"Content-Type": "application/json",
},
body: JSON.stringify({
"seller_payme_id": "MPL1DEMO-XXXXXXXX-XXXXXXXX-XXXXXXXX",
"buyer_uuid2": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
"buyer_key": "BUYER111-XXXXXXXX-XXXXXXXX-XXXXXXXX"
}),
});
console.log(await response.text());
```
### Python
```python
import requests
response = requests.post(
"https://sandbox.payme.io/api/buyer-token-to-card-number",
json={
"seller_payme_id": "MPL1DEMO-XXXXXXXX-XXXXXXXX-XXXXXXXX",
"buyer_uuid2": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
"buyer_key": "BUYER111-XXXXXXXX-XXXXXXXX-XXXXXXXX",
},
)
print(response.text)
```
### PHP
```php
'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;
```
## Responses
### 200 — OK (success)
| Field | Type | Description |
| --- | --- | --- |
| `buyer_key` | string | Buyer's unique token. |
| `buyer_card_number` | string | Buyer's card mask. |
| `buyer_card_exp_month` | string | Buyer's card exp (MMYY). |
| `buyer_card_exp_year` | string | Credit card expiration date |
```json
{
"buyer_key": "BUYER111-XXXXXXXX-XXXXXXXX-XXXXXXXX",
"buyer_card_number": "532**********846",
"buyer_card_exp_month": "04",
"buyer_card_exp_year": "26",
"status_code": 0
}
```
## Merchants Management
- [Create Seller](https://docs-staging.payme.io/payments/merchants-management/post-create-seller): POST /create-seller — Create Seller
# Create Seller
- Sandbox: `POST https://sandbox.payme.io/api/create-seller`
- Production: `POST https://live.payme.io/api/create-seller`
## Credentials
- Request body field `payme_client_key` (required): PayMe Partner Key.
## Overview
**Relevant only to PayMe's partners.**
This endpoint allows you to create a seller as one of PayMe's partners.
You can find more information in the following guide - [How to Create New Sellers](/marketplaces-and-platforms/sellers/create-seller).
##### Testing
For testing purposes you can use the following testing values:
Attributes |Value
---|---
seller_social_id| `9999999999`
seller_email |`random@paymeservice.com` Note that by using this email you will not receive any automatic emails sent from the system
seller_bank_code| `54`
seller_bank_branch| `123` Any 3 digits
seller_bank_account_number| `123456` Any 6 digits
#### Callback upon Seller creation or update
Once the Seller is created or updated, we will notify the marketplace with the Seller details with a POST request of type `x-www-form-urlencoded` to the marketplace Default Callback URL.
## Parameters
This endpoint takes no path, query or header parameters.
## Request body
Content type: `application/json`
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `payme_client_key` | string | yes | PayMe Partner Key. |
| `seller_first_name` | string | yes | Seller's first name |
| `seller_last_name` | string | yes | Seller's last name |
| `seller_social_id` | string | yes | Seller's social ID |
| `seller_birthdate` | string | yes | Seller's personal birth date. ( dd/mm/yyyy structured) |
| `seller_social_id_issued` | string | yes | Seller's personal social ID issuing day.( dd/mm/yyyy structured) |
| `seller_gender` | number | yes | Seller's gender ( 0- Male, 1- Female) |
| `seller_email` | string | yes | Seller's email address |
| `seller_phone` | string | yes | Seller's phone number |
| `seller_contact_email` | string | no | Seller's contact email |
| `seller_contact_phone` | string | no | Seller's contact phone number that will be displayed to the buyers. If not stated, will be copied from seller_phone |
| `seller_bank_code` | number | yes | Seller's bank code (Israeli only) Please see the full list of banks [Banks in Israel](/marketplaces-and-platforms/lists-statuses/banks-in-israel). |
| `seller_bank_branch` | number | yes | Seller's bank branch code |
| `seller_bank_account_number` | string | yes | Seller's bank account number |
| `seller_description` | string | yes | Seller’s description, including offered product line and services. Limited to 255 characters. |
| `seller_site_url` | string | yes | Seller’s site URL. |
| `seller_person_business_type` | number | yes | Business MCC (Merchant category code). List of codes [MCC List](/marketplaces-and-platforms/lists-statuses/mcc-list). |
| `seller_inc` | number | yes | Seller incorporation type (IL Only) You can find all the seller incorporation types [Seller Incorporation Types (IL)](/marketplaces-and-platforms/lists-statuses/seller-incorporation-types-il). |
| `seller_inc_code` | string | no | Seller's business ID (ח.פ, ע.מ), required when seller_inc is not 1. |
| `seller_retail_type` | number | no | Seller's retail type. (1 - Card not present (online) seller, 2 - Card present seller). |
| `seller_merchant_name` | string | yes | Seller's merchant name, required when seller_inc is not 1. |
| `seller_address_city` | string | yes | Seller's business address - City. |
| `seller_address_street` | string | yes | Seller's business address - Street. |
| `seller_address_street_number` | string | yes | Street number |
| `seller_address_country` | string | yes | Seller's business address - Country code according to the ISO 3166. You can fond all the country codes [here](https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes). |
| `market_fee` | number | no | A decimal between 0.00 and 60.00 representing the percent of the sale price that is collected for the marketplace (includes VAT). This fee is added on top of our fees and transferred to the marketplace once a month. Default value is 0 |
| `language` | string | no | Changes the error message language to English. Default value is Hebrew (he). |
| `seller_plan` | string | no | A predefined set of settings for the seller. If required, this value will be provided by your Account Manager. |
| `seller_merchant_name_en` | string | no | The seller's international name in English |
| `seller_additional_details` | object | no | |
| `seller_additional_details.first_name` | string | no | Seller's first name |
| `seller_additional_details.last_name` | string | no | Seller's last name |
| `seller_additional_details.social_id` | string | no | Seller's social ID |
| `seller_additional_details.social_id_issued` | string | no | The social id document issuing date ( dd/mm/yyyy structured) |
| `seller_additional_details.type` | array | no | Possible Role. An individual can have multiple roles in a company. You can find all the individual seller types [Individual Seller Types](/marketplaces-and-platforms/lists-statuses/individual-seller-types). |
| `seller_additional_details.type_copy` | array | no | Possible Role. An individual can have multiple roles in a company. You can find all the individual seller types [Individual Seller Types](/marketplaces-and-platforms/lists-statuses/individual-seller-types). |
| `seller_additional_details.email` | string | no | Seller's Email |
| `seller_additional_details.files` | object | no | Files related to the individual, like id |
| `seller_additional_details.files.type` | number | no | You can find [File Types](/marketplaces-and-platforms/lists-statuses/file-types) the file types you can upload. Only individual types are valid: 90-95. |
| `seller_additional_details.files.url` | string | no | File URL |
| `seller_additional_details.files.base64` | string | no | The base64 encoded file |
| `seller_additional_details.files.name` | string | no | File name with extension. Allowed file extensions: `pdf`, `jpg`, `jpeg`, `png`, `bmp`, `tiff`, `doc`, `docx` |
| `seller_additional_details.files.mime_type` | string | no | The mime type of the file. Most common mime types are supported, such as `application/pdf`, `application/msword`, `image/png`, `image/jpg`, `image/jpeg`, `image/tiff`, `jfif`. |
| `seller_dba` | string | no | The seller's legal/registered name in Hebrew. |
| `seller_dba_en` | string | no | The seller's legal/registered international name in English. |
| `seller_id` | string | no | Merchant's unique seller ID for correlation with us. |
### Request example
```json
{
"payme_client_key": "string",
"seller_id": "1234",
"seller_first_name": "string",
"seller_last_name": "string",
"seller_social_id": "string",
"seller_birthdate": "string",
"seller_social_id_issued": "string",
"seller_gender": 0,
"seller_email": "string",
"seller_phone": "string",
"seller_bank_code ": 0,
"seller_bank_branch": 0,
"seller_bank_account_number": "string",
"seller_description": "string",
"seller_site_url": "string",
"seller_person_business_type": 0,
"seller_inc": 0,
"seller_retail_type": 1,
"seller_merchant_name": "string",
"seller_address_city": "string",
"seller_address_street": "string",
"seller_address_street_number": "string",
"seller_address_country": "string",
"market_fee": 0,
"seller_registration_date": "string"
}
```
## Code samples
### curl
```bash
curl -X POST 'https://sandbox.payme.io/api/create-seller' \
-H 'Content-Type: application/json' \
--data-raw '{
"payme_client_key": "string",
"seller_id": "1234",
"seller_first_name": "string",
"seller_last_name": "string",
"seller_social_id": "string",
"seller_birthdate": "string",
"seller_social_id_issued": "string",
"seller_gender": 0,
"seller_email": "string",
"seller_phone": "string",
"seller_bank_code ": 0,
"seller_bank_branch": 0,
"seller_bank_account_number": "string",
"seller_description": "string",
"seller_site_url": "string",
"seller_person_business_type": 0,
"seller_inc": 0,
"seller_retail_type": 1,
"seller_merchant_name": "string",
"seller_address_city": "string",
"seller_address_street": "string",
"seller_address_street_number": "string",
"seller_address_country": "string",
"market_fee": 0,
"seller_registration_date": "string"
}'
```
### Node.js
```javascript
const response = await fetch("https://sandbox.payme.io/api/create-seller", {
method: "POST",
headers: {
"Content-Type": "application/json",
},
body: JSON.stringify({
"payme_client_key": "string",
"seller_id": "1234",
"seller_first_name": "string",
"seller_last_name": "string",
"seller_social_id": "string",
"seller_birthdate": "string",
"seller_social_id_issued": "string",
"seller_gender": 0,
"seller_email": "string",
"seller_phone": "string",
"seller_bank_code ": 0,
"seller_bank_branch": 0,
"seller_bank_account_number": "string",
"seller_description": "string",
"seller_site_url": "string",
"seller_person_business_type": 0,
"seller_inc": 0,
"seller_retail_type": 1,
"seller_merchant_name": "string",
"seller_address_city": "string",
"seller_address_street": "string",
"seller_address_street_number": "string",
"seller_address_country": "string",
"market_fee": 0,
"seller_registration_date": "string"
}),
});
console.log(await response.text());
```
### Python
```python
import requests
response = requests.post(
"https://sandbox.payme.io/api/create-seller",
json={
"payme_client_key": "string",
"seller_id": "1234",
"seller_first_name": "string",
"seller_last_name": "string",
"seller_social_id": "string",
"seller_birthdate": "string",
"seller_social_id_issued": "string",
"seller_gender": 0,
"seller_email": "string",
"seller_phone": "string",
"seller_bank_code ": 0,
"seller_bank_branch": 0,
"seller_bank_account_number": "string",
"seller_description": "string",
"seller_site_url": "string",
"seller_person_business_type": 0,
"seller_inc": 0,
"seller_retail_type": 1,
"seller_merchant_name": "string",
"seller_address_city": "string",
"seller_address_street": "string",
"seller_address_street_number": "string",
"seller_address_country": "string",
"market_fee": 0,
"seller_registration_date": "string",
},
)
print(response.text)
```
### PHP
```php
'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;
```
## Responses
### 200 — OK (success)
| Field | Type | Description |
| --- | --- | --- |
| `status_code` | number | Status of the request (0 - success, 1 - error) |
| `seller_payme_id` | string | The MPL the authorization will be given for |
| `seller_payme_secret` | string | The seller's secret key |
| `seller_public_key` | object | PayMe seller's public key details |
| `seller_public_key.uuid` | string | PayMe seller's public key |
| `seller_public_key.description` | string | PayMe seller's public key description |
| `seller_public_key.is_active` | boolean | Indicates if the public key is active or not (active = true) |
| `seller_id` | string | The seller's ID |
| `seller_dashboard_signup_link` | string | Link for the signup process |
```json
{
"status_code": 0,
"seller_payme_id": "string",
"seller_payme_secret": "string",
"seller_public_key": {
"uuid": "string",
"description": "string",
"is_active": true
},
"seller_id": "string",
"seller_dashboard_signup_link": "string"
}
```
### 500 — Internal Server Error (error)
| Field | Type | Description |
| --- | --- | --- |
| `status_code` | number | |
| `status_error_details` | string | |
| `status_additional_info` | string | |
| `status_error_code` | number | |
```json
{
"status_code": 0,
"status_error_details": "string",
"status_additional_info": null,
"status_error_code": 0
}
```
- [Update Seller](https://docs-staging.payme.io/payments/merchants-management/post-update-seller): POST /update-seller — Update Seller
# Update Seller
- Sandbox: `POST https://sandbox.payme.io/api/update-seller`
- Production: `POST https://live.payme.io/api/update-seller`
## Credentials
- Request body field `payme_client_key` (required): PayMe Partner Key.
- Request body field `seller_payme_id` (required): MPL. Your private key in PayMe system.
## Overview
**Relevant only to PayMe's partners.**
You can update your sellers information using the update-seller endpoint easily.
##### Testing
For testing purposes you can use the following testing values:
Attributes |Value
---|---
seller_social_id| `9999999999`
seller_email |`random@paymeservice.com` Note that by using this email you will not receive any automatic emails sent from the system
seller_bank_code| `54`
seller_bank_branch| `123` Any 3 digits
seller_bank_account_number| `123456` Any 6 digits
#### Callback upon Seller creation or update
Once the Seller is created or updated, we will notify the marketplace with the Seller details with a POST request of type `x-www-form-urlencoded` to the marketplace Default Callback URL.
## Parameters
This endpoint takes no path, query or header parameters.
## Request body
Content type: `application/json`
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `payme_client_key` | string | yes | PayMe Partner Key. |
| `seller_payme_id` | string | yes | MPL. Your private key in PayMe system. |
| `seller_first_name` | string | yes | Seller's first name |
| `seller_last_name` | string | yes | Seller's last name |
| `seller_social_id` | string | yes | Seller's social ID |
| `seller_birthdate` | string | yes | Seller's personal birth date. ( dd-mm-yyyy structured) |
| `seller_social_id_issued` | string | yes | Seller's personal social ID issuing day.( dd-mm-yyyy structured) |
| `seller_gender` | number | yes | Seller's gender ( 0- Male, 1- Female) |
| `seller_email` | string | yes | Seller's email address |
| `seller_phone` | string | yes | Seller's phone number |
| `seller_contact_email` | string | no | Seller's contact email |
| `seller_contact_phone` | string | no | Seller's contact phone number that will be displayed to the buyers. If not stated, will be copied from seller_phone |
| `seller_bank_code` | number | yes | Seller's bank code (Israeli only) Please see the full list of banks [Banks in Israel](/marketplaces-and-platforms/lists-statuses/banks-in-israel). |
| `seller_bank_branch` | number | yes | Seller's bank branch code |
| `seller_bank_account_number` | string | yes | Seller's bank account number |
| `seller_description` | string | yes | Seller’s description, including offered product line and services. Limited to 255 characters. |
| `seller_site_url` | string | yes | Seller’s site URL. |
| `seller_person_business_type` | number | yes | Business MCC (Merchant category code). List of codes [MCC List](/marketplaces-and-platforms/lists-statuses/mcc-list). |
| `seller_inc` | number | yes | Seller incorporation type (IL Only) You can find all the seller incorporation types [Seller Incorporation Types (IL)](/marketplaces-and-platforms/lists-statuses/seller-incorporation-types-il). |
| `seller_inc_code` | string | no | Seller's business ID (ח.פ, ע.מ), required when seller_inc is not 1. |
| `seller_retail_type` | number | no | Seller's retail type. (1 - Card not present (online) seller, 2 - Card present seller). |
| `seller_merchant_name` | string | yes | Seller's merchant name, required when seller_inc is not 1. |
| `seller_address_city` | string | yes | Seller's business address - City. |
| `seller_address_street` | string | yes | Seller's business address - Street. |
| `seller_address_street_number` | string | yes | Street number |
| `seller_address_country` | string | yes | Seller's business address - Country code according to the ISO 3166. You can fond all the country codes [here](https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes). |
| `market_fee` | number | no | A decimal between 0.00 and 60.00 representing the percent of the sale price that is collected for the marketplace (includes VAT). This fee is added on top of our fees and transferred to the marketplace once a month. Default value is 0 |
| `language` | string | no | Changes the error message language to English. Default value is Hebrew (he). |
| `seller_plan` | string | no | A predefined set of settings for the seller. If required, this value will be provided by your Account Manager. |
| `seller_merchant_name_en` | string | no | The seller's international name in English |
| `seller_additional_details` | object | no | |
| `seller_additional_details.first_name` | string | no | Seller's first name |
| `seller_additional_details.last_name` | string | no | Seller's last name |
| `seller_additional_details.social_id` | string | no | Seller's social ID |
| `seller_additional_details.type` | array | no | Possible Role. An individual can have multiple roles in a company. You can find all the individual seller types [Individual Seller Types](/marketplaces-and-platforms/lists-statuses/individual-seller-types). |
| `seller_additional_details.email` | string | no | Seller's Email |
| `seller_dba` | string | no | The seller's legal/registered name in Hebrew. |
| `seller_dba_en` | string | no | The seller's legal/registered international name in English. |
### Request example
```json
{
"payme_client_key": "string",
"seller_id": "1234",
"seller_first_name": "string",
"seller_last_name": "string",
"seller_social_id": "string",
"seller_birthdate": "string",
"seller_social_id_issued": "string",
"seller_gender": 0,
"seller_email": "string",
"seller_phone": "string",
"seller_bank_code ": 0,
"seller_bank_branch": 0,
"seller_bank_account_number": "string",
"seller_description": "string",
"seller_site_url": "string",
"seller_person_business_type": 0,
"seller_inc": 0,
"seller_retail_type": 1,
"seller_merchant_name": "string",
"seller_address_city": "string",
"seller_address_street": "string",
"seller_address_street_number": "string",
"seller_address_country": "string",
"market_fee": 0,
"seller_registration_date": "string"
}
```
## Code samples
### curl
```bash
curl -X POST 'https://sandbox.payme.io/api/update-seller' \
-H 'Content-Type: application/json' \
--data-raw '{
"payme_client_key": "string",
"seller_id": "1234",
"seller_first_name": "string",
"seller_last_name": "string",
"seller_social_id": "string",
"seller_birthdate": "string",
"seller_social_id_issued": "string",
"seller_gender": 0,
"seller_email": "string",
"seller_phone": "string",
"seller_bank_code ": 0,
"seller_bank_branch": 0,
"seller_bank_account_number": "string",
"seller_description": "string",
"seller_site_url": "string",
"seller_person_business_type": 0,
"seller_inc": 0,
"seller_retail_type": 1,
"seller_merchant_name": "string",
"seller_address_city": "string",
"seller_address_street": "string",
"seller_address_street_number": "string",
"seller_address_country": "string",
"market_fee": 0,
"seller_registration_date": "string"
}'
```
### Node.js
```javascript
const response = await fetch("https://sandbox.payme.io/api/update-seller", {
method: "POST",
headers: {
"Content-Type": "application/json",
},
body: JSON.stringify({
"payme_client_key": "string",
"seller_id": "1234",
"seller_first_name": "string",
"seller_last_name": "string",
"seller_social_id": "string",
"seller_birthdate": "string",
"seller_social_id_issued": "string",
"seller_gender": 0,
"seller_email": "string",
"seller_phone": "string",
"seller_bank_code ": 0,
"seller_bank_branch": 0,
"seller_bank_account_number": "string",
"seller_description": "string",
"seller_site_url": "string",
"seller_person_business_type": 0,
"seller_inc": 0,
"seller_retail_type": 1,
"seller_merchant_name": "string",
"seller_address_city": "string",
"seller_address_street": "string",
"seller_address_street_number": "string",
"seller_address_country": "string",
"market_fee": 0,
"seller_registration_date": "string"
}),
});
console.log(await response.text());
```
### Python
```python
import requests
response = requests.post(
"https://sandbox.payme.io/api/update-seller",
json={
"payme_client_key": "string",
"seller_id": "1234",
"seller_first_name": "string",
"seller_last_name": "string",
"seller_social_id": "string",
"seller_birthdate": "string",
"seller_social_id_issued": "string",
"seller_gender": 0,
"seller_email": "string",
"seller_phone": "string",
"seller_bank_code ": 0,
"seller_bank_branch": 0,
"seller_bank_account_number": "string",
"seller_description": "string",
"seller_site_url": "string",
"seller_person_business_type": 0,
"seller_inc": 0,
"seller_retail_type": 1,
"seller_merchant_name": "string",
"seller_address_city": "string",
"seller_address_street": "string",
"seller_address_street_number": "string",
"seller_address_country": "string",
"market_fee": 0,
"seller_registration_date": "string",
},
)
print(response.text)
```
### PHP
```php
'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;
```
## Responses
### 200 — OK (success)
| Field | Type | Description |
| --- | --- | --- |
| `status_code` | number | Status of the request (0 - success, 1 - error) |
| `seller_payme_id` | string | The MPL the authorization will be given for |
| `seller_payme_secret` | string | The seller's secret key |
| `seller_public_key` | object | PayMe seller's public key details |
| `seller_public_key.uuid` | string | PayMe seller's public key |
| `seller_public_key.description` | string | PayMe seller's public key description |
| `seller_public_key.is_active` | boolean | Indicates if the public key is active or not (active = true) |
| `seller_id` | string | The seller's ID |
| `seller_dashboard_signup_link` | string | Link for the signup process |
```json
{
"status_code": 0,
"seller_payme_id": "string",
"seller_payme_secret": "string",
"seller_public_key": {
"uuid": "string",
"description": "string",
"is_active": true
},
"seller_id": "string",
"seller_dashboard_signup_link": "string"
}
```
### 500 — Internal Server Error (error)
| Field | Type | Description |
| --- | --- | --- |
| `status_code` | number | |
| `status_error_details` | string | |
| `status_additional_info` | string | |
| `status_error_code` | number | |
```json
{
"status_code": 0,
"status_error_details": "string",
"status_additional_info": null,
"status_error_code": 0
}
```
- [Upload Seller Files](https://docs-staging.payme.io/payments/merchants-management/post-upload-seller-files): POST /upload-seller-files — Upload Seller Files
# Upload Seller Files
- Sandbox: `POST https://sandbox.payme.io/api/upload-seller-files`
- Production: `POST https://live.payme.io/api/upload-seller-files`
## Credentials
- Request body field `payme_client_key` (required): Your private key provided by us for authentication
- Request body field `seller_payme_id` (required): Our unique seller ID
## Overview
This endpoint is used to upload files of a seller.
You can find [File Types](/marketplaces-and-platforms/lists-statuses/file-types) the file types you can upload.
Uploading files can be done using one or both of the following formats:
#### URL of the file
Attribute|Description
---------|----------
name|`social_id.pdf` File name with extension
type| `1` The document type code
url| `https://www.mysite.com/files/social_id.pdf` The URL of the file
mime_type| `application/pdf` The mime type of the file
#### base64 encoded file
Attribute|Description
---------|----------
name|`social_id.pdf` File name with extension
type|`1` The document type code
base64|The base64 encoded file
mime_type|`application/pdf` The mime type of the file
## Parameters
This endpoint takes no path, query or header parameters.
## Request body
Content type: `application/json`
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `payme_client_key` | string | yes | Your private key provided by us for authentication |
| `seller_payme_id` | string | yes | Our unique seller ID |
| `seller_files` | array | yes | Array of files according to the format described below |
| `seller_files[].name` | string | yes | File name with extension. Allowed file extensions: `pdf`, `jpg`, `jpeg`, `png`, `bmp`, `tiff`, `doc`, `docx`. |
| `seller_files[].type` | number | yes | You can find [File Types](/marketplaces-and-platforms/lists-statuses/file-types) the file types you can upload. |
| `seller_files[].url` | string | no | File URL |
| `seller_files[].base64` | string | no | The base64 encoded file |
| `seller_files[].mime_type` | string | yes | The mime type of the file. Most common mime types are supported, such as `application/pdf`, `application/msword`, `image/png`, `image/jpg`, `image/jpeg`, `image/tiff`, `jfif`. |
### Request example
```json
{
"payme_client_key": "XXXXXXXX",
"seller_payme_id": "XXXXXXXX-XXXXXXXX-XXXXXXXX-XXXXXXXX",
"seller_files": [
{
"name": "dummy.pdf",
"type": 1,
"url": "https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf",
"mime_type": "application/pdf"
},
{
"name": "test.png",
"type": 2,
"base64": "iVBORw0KGgoAAAANSUhEUgAAAMgAAADICAYAAACtWK6eAAAAAklEQVR4AewaftIAAAkOSURBVO3BabDdZWEH4OecXKUUQeAmYRGtW2lLRVBIUkNhJgI6shgWW1nUCJgmpRMoEATNQLmFRtZWIhJEqLLHChkEKYsKKTTQkOgkECgoCtqyhL0hjEswtx/eD3/PnHO3JPeac8/veURERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERLShmvhdt+BgPIhJWpuMxRotwhTD5xHsgutxtNY+g6s0ugLTDZ9f4804G2dq7R9xhkZfwLnaQF0MxbuwWLPb/X7tj6s0u8Pv10ycodnt2kSXGIqTVbbHKpuGkxWv4y02HScrVmB3baguhmKS4hassumYpPiaTUc3/ljxNW2qLoaiW/GMTUcN2yiesenYVuVZbaouflevwek1snr1rabSa2T16ltNpVeb6tLeTsGFKtfi0wZ2Gs5V2RUr8ZqNYz5mqpyFHgO7HNNV/hC/xBobx13YX+VTuM7A7sYUxdPYSbEGmxnFatrTHlimb9/CEZrth+9p7SXciBl4EJNUHsOfaG0hDld8Egv0bS7maDYT87W2BGuwL67H0SpvYIzWzsdpijk4R9+OxTc0uwCztXYd9sI7cTbOVLwLP9O3Gbhcm+jSnu5VvIxulYtwMtZq9mF8T+VsnKlYhj0ww/rbEQsUSzFR5Tv4ONZq9jeYrzINVytexSQbZh+co7gBR6k8gl2wVrPzMVtlL9yPsXgBR+sANe3nMNyk2B6rDM6L6Fa8Fas12gJrFA9ikmY/xbsxH8dr9HmchzXY0uBsjVcUL2C8ZrthueJ6HK1RHb9VnIJ/1uhyTMdyfMDg7ImligcwWbNP4NuKs3GmRjvjccUh+I42VNd+xinWYpXB+Ry6FUdgtWav41brb5ziFwbvdJUDtLYCj1p/4xT/a/BOUzlAazfiN0a5uvazQvEmzDc4hymex7cMjxWKXXCKwTlUsRjLDI8VioMw1eAcprgar+pgde3nv3ClYiZ6cbH+7a5YZPhci0WKC9GLE/RtC+ysuNfwOQtPK25GLw7Qt/ejrvgPHa5Le/ocluMrihNwgmJbvKLRWMWzhtcUfBknKi7GxXgJYzUaq/KM4bUTvosDFbcpluAvNBqn8qwOV9e+LkENu2r0Ms7XaJ1ijOH396jhUJVu9GKGyjqVuuF3EGqYrTIJvdhXZZ3KGB2urv2tRA01PKc4FR9VeVHxNiPnZtTwFpXL8F7Fiyo7GTkXoYbdVb6v8oLKjjpc3eiyA55XHKLy34rJRt7r2EplquKXeEox2chbgQ+qTFU8pjJZh6sbfR5W/IHKnYrtcLi+bWt4vIafKzZXuVOxF3bTt27D42GVzRVv4PuKadhCa1vizUa5uvZzHHq1Ng77KpaqXKxyI7o1ewR7WX9fwhNa+xD+SLFMZZ7KPVr7Nbaz/r6NO7R2pMoylXkq92j2DqzWAbq0l7fjCkWv4jO4BrfiIMUqXKqyFtNwleJFrc3CVwzdFJyu6FVMxgN4FH+mWIw7VB7F2TgD26BXa+fj84ZuOj6h6FVsh+exFl2Kq/GEyq24HkdhAnq1dhsONIqN0V5Wowc7YE/FoTgLOyueww6arcByHKG1HbEN/hpP4wrNTsQ2WIbbVJ5CD/bGuxXH4SyMU/wn9tbsHqzBRzR7HZthD+yHh7FQoxr+QXEXHlD5EXpwDLZWnIqzUFd8E5/VbCG2wwTNHsL2mIIP4l7co1E3ZikW4HEREREREREREREREREREREREaNXTee6DkdhDuYa2OWYrtFtOEj/puJmrV2OGQbveYzDRCw1sCfxTo1OxDz9uwR/p7W/wo06RE1nmYglGs3BXH37EO7Xvz3xQ80exAT9+yH21Lcv4p80moil+nYmevTtZXRr9la8amDn4gs6QJfOcSrONzRH4nrFo/hzld2wXLEEXRq9CRMU++JujS7CydgDx+NSze7C/obmShyrmIcTVWbjAmyL2/ExjfZSrMMYzR7Crjgd38CPjXJjdI770YMe9OCLGIO7cZ/WfoNZmIMjNVqFWzEDdbyGB1TW4SbMws80uwszsCW6cK1m16AHPViEzyq+jme0thMOxERcqdH9+BX2w3uxEM+r/ASr8TGt3YfjFT/HA0a5uujPj1HDXK39CIsV+2i2Euv0bblivI3nUtSwVGuXqOyt2b/o20q8oRivA9TFhvqJYqyhG6tYZeS8jqcV4w3NNuhSrNIB6mJDbaV4zdB8ABMUC42srRSrDc10lYU6QJfYUB9WLDF4h2Kh4t/xdSNnArZULDF4l+JvFSfhKR2gS2yIY7G14ip9ew+e0GwO5hpZJymewGJ9m4n5mk3EUh2iLjbEJYqr8aShe8zI+kscqeixfh7XQbrE+roBmytm6N9PUVN5FtvjJryGrYyMmxX34Vr9uwyXKXbFQ4r/w0IcrgPUxfqYhSMUn8SvDM0OqOG32BJLDL9b0K2YamgeRg37Kg7DOTpAXQzVRzBPMQ//Zv1NVUzEPobPBThYcTBesX7uxsWK2TpAXQzF+3Gn4gc40YZZpLKH4XEKZitOx3dtmEWKzfA+o1xdDNZ7sELxOPaz4cao1G18M3Gh4hKcZ8ONUakb5epiMHbCE4qX8KcG9g7M1r8DVFbauI7BfMUCzDKw47Cb/h2gstIo1yUGsgP+R/EGxhqc+/E27I+PavZ23KD4Be608Xwa/6q4HUca2C64QnEqLtTsGByruBLrjHI1neFoXGtwTsKXFdvhOZUjsEDffoD9FMfjqwZnd6zQ6JuYZnDeh0cUn8I1invxJKbp2+k4T3EzphrYCxivA9RFf76k0QKDdylqWKtvb6CGFTaeuSr7YJrBOwRT9O92jBcRERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERETGa/D8Rm8iOzF+WUQAAAABJRU5ErkJggg==",
"mime_type": "image/png"
}
]
}
```
## Code samples
### curl
```bash
curl -X POST 'https://sandbox.payme.io/api/upload-seller-files' \
-H 'Content-Type: application/json' \
--data-raw '{
"payme_client_key": "XXXXXXXX",
"seller_payme_id": "XXXXXXXX-XXXXXXXX-XXXXXXXX-XXXXXXXX",
"seller_files": [
{
"name": "dummy.pdf",
"type": 1,
"url": "https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf",
"mime_type": "application/pdf"
},
{
"name": "test.png",
"type": 2,
"base64": "iVBORw0KGgoAAAANSUhEUgAAAMgAAADICAYAAACtWK6eAAAAAklEQVR4AewaftIAAAkOSURBVO3BabDdZWEH4OecXKUUQeAmYRGtW2lLRVBIUkNhJgI6shgWW1nUCJgmpRMoEATNQLmFRtZWIhJEqLLHChkEKYsKKTTQkOgkECgoCtqyhL0hjEswtx/eD3/PnHO3JPeac8/veURERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERLShmvhdt+BgPIhJWpuMxRotwhTD5xHsgutxtNY+g6s0ugLTDZ9f4804G2dq7R9xhkZfwLnaQF0MxbuwWLPb/X7tj6s0u8Pv10ycodnt2kSXGIqTVbbHKpuGkxWv4y02HScrVmB3baguhmKS4hassumYpPiaTUc3/ljxNW2qLoaiW/GMTUcN2yiesenYVuVZbaouflevwek1snr1rabSa2T16ltNpVeb6tLeTsGFKtfi0wZ2Gs5V2RUr8ZqNYz5mqpyFHgO7HNNV/hC/xBobx13YX+VTuM7A7sYUxdPYSbEGmxnFatrTHlimb9/CEZrth+9p7SXciBl4EJNUHsOfaG0hDld8Egv0bS7maDYT87W2BGuwL67H0SpvYIzWzsdpijk4R9+OxTc0uwCztXYd9sI7cTbOVLwLP9O3Gbhcm+jSnu5VvIxulYtwMtZq9mF8T+VsnKlYhj0ww/rbEQsUSzFR5Tv4ONZq9jeYrzINVytexSQbZh+co7gBR6k8gl2wVrPzMVtlL9yPsXgBR+sANe3nMNyk2B6rDM6L6Fa8Fas12gJrFA9ikmY/xbsxH8dr9HmchzXY0uBsjVcUL2C8ZrthueJ6HK1RHb9VnIJ/1uhyTMdyfMDg7ImligcwWbNP4NuKs3GmRjvjccUh+I42VNd+xinWYpXB+Ry6FUdgtWav41brb5ziFwbvdJUDtLYCj1p/4xT/a/BOUzlAazfiN0a5uvazQvEmzDc4hymex7cMjxWKXXCKwTlUsRjLDI8VioMw1eAcprgar+pgde3nv3ClYiZ6cbH+7a5YZPhci0WKC9GLE/RtC+ysuNfwOQtPK25GLw7Qt/ejrvgPHa5Le/ocluMrihNwgmJbvKLRWMWzhtcUfBknKi7GxXgJYzUaq/KM4bUTvosDFbcpluAvNBqn8qwOV9e+LkENu2r0Ms7XaJ1ijOH396jhUJVu9GKGyjqVuuF3EGqYrTIJvdhXZZ3KGB2urv2tRA01PKc4FR9VeVHxNiPnZtTwFpXL8F7Fiyo7GTkXoYbdVb6v8oLKjjpc3eiyA55XHKLy34rJRt7r2EplquKXeEox2chbgQ+qTFU8pjJZh6sbfR5W/IHKnYrtcLi+bWt4vIafKzZXuVOxF3bTt27D42GVzRVv4PuKadhCa1vizUa5uvZzHHq1Ng77KpaqXKxyI7o1ewR7WX9fwhNa+xD+SLFMZZ7KPVr7Nbaz/r6NO7R2pMoylXkq92j2DqzWAbq0l7fjCkWv4jO4BrfiIMUqXKqyFtNwleJFrc3CVwzdFJyu6FVMxgN4FH+mWIw7VB7F2TgD26BXa+fj84ZuOj6h6FVsh+exFl2Kq/GEyq24HkdhAnq1dhsONIqN0V5Wowc7YE/FoTgLOyueww6arcByHKG1HbEN/hpP4wrNTsQ2WIbbVJ5CD/bGuxXH4SyMU/wn9tbsHqzBRzR7HZthD+yHh7FQoxr+QXEXHlD5EXpwDLZWnIqzUFd8E5/VbCG2wwTNHsL2mIIP4l7co1E3ZikW4HEREREREREREREREREREREREaNXTee6DkdhDuYa2OWYrtFtOEj/puJmrV2OGQbveYzDRCw1sCfxTo1OxDz9uwR/p7W/wo06RE1nmYglGs3BXH37EO7Xvz3xQ80exAT9+yH21Lcv4p80moil+nYmevTtZXRr9la8amDn4gs6QJfOcSrONzRH4nrFo/hzld2wXLEEXRq9CRMU++JujS7CydgDx+NSze7C/obmShyrmIcTVWbjAmyL2/ExjfZSrMMYzR7Crjgd38CPjXJjdI770YMe9OCLGIO7cZ/WfoNZmIMjNVqFWzEDdbyGB1TW4SbMws80uwszsCW6cK1m16AHPViEzyq+jme0thMOxERcqdH9+BX2w3uxEM+r/ASr8TGt3YfjFT/HA0a5uujPj1HDXK39CIsV+2i2Euv0bblivI3nUtSwVGuXqOyt2b/o20q8oRivA9TFhvqJYqyhG6tYZeS8jqcV4w3NNuhSrNIB6mJDbaV4zdB8ABMUC42srRSrDc10lYU6QJfYUB9WLDF4h2Kh4t/xdSNnArZULDF4l+JvFSfhKR2gS2yIY7G14ip9ew+e0GwO5hpZJymewGJ9m4n5mk3EUh2iLjbEJYqr8aShe8zI+kscqeixfh7XQbrE+roBmytm6N9PUVN5FtvjJryGrYyMmxX34Vr9uwyXKXbFQ4r/w0IcrgPUxfqYhSMUn8SvDM0OqOG32BJLDL9b0K2YamgeRg37Kg7DOTpAXQzVRzBPMQ//Zv1NVUzEPobPBThYcTBesX7uxsWK2TpAXQzF+3Gn4gc40YZZpLKH4XEKZitOx3dtmEWKzfA+o1xdDNZ7sELxOPaz4cao1G18M3Gh4hKcZ8ONUakb5epiMHbCE4qX8KcG9g7M1r8DVFbauI7BfMUCzDKw47Cb/h2gstIo1yUGsgP+R/EGxhqc+/E27I+PavZ23KD4Be608Xwa/6q4HUca2C64QnEqLtTsGByruBLrjHI1neFoXGtwTsKXFdvhOZUjsEDffoD9FMfjqwZnd6zQ6JuYZnDeh0cUn8I1invxJKbp2+k4T3EzphrYCxivA9RFf76k0QKDdylqWKtvb6CGFTaeuSr7YJrBOwRT9O92jBcRERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERETGa/D8Rm8iOzF+WUQAAAABJRU5ErkJggg==",
"mime_type": "image/png"
}
]
}'
```
### Node.js
```javascript
const response = await fetch("https://sandbox.payme.io/api/upload-seller-files", {
method: "POST",
headers: {
"Content-Type": "application/json",
},
body: JSON.stringify({
"payme_client_key": "XXXXXXXX",
"seller_payme_id": "XXXXXXXX-XXXXXXXX-XXXXXXXX-XXXXXXXX",
"seller_files": [
{
"name": "dummy.pdf",
"type": 1,
"url": "https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf",
"mime_type": "application/pdf"
},
{
"name": "test.png",
"type": 2,
"base64": "iVBORw0KGgoAAAANSUhEUgAAAMgAAADICAYAAACtWK6eAAAAAklEQVR4AewaftIAAAkOSURBVO3BabDdZWEH4OecXKUUQeAmYRGtW2lLRVBIUkNhJgI6shgWW1nUCJgmpRMoEATNQLmFRtZWIhJEqLLHChkEKYsKKTTQkOgkECgoCtqyhL0hjEswtx/eD3/PnHO3JPeac8/veURERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERLShmvhdt+BgPIhJWpuMxRotwhTD5xHsgutxtNY+g6s0ugLTDZ9f4804G2dq7R9xhkZfwLnaQF0MxbuwWLPb/X7tj6s0u8Pv10ycodnt2kSXGIqTVbbHKpuGkxWv4y02HScrVmB3baguhmKS4hassumYpPiaTUc3/ljxNW2qLoaiW/GMTUcN2yiesenYVuVZbaouflevwek1snr1rabSa2T16ltNpVeb6tLeTsGFKtfi0wZ2Gs5V2RUr8ZqNYz5mqpyFHgO7HNNV/hC/xBobx13YX+VTuM7A7sYUxdPYSbEGmxnFatrTHlimb9/CEZrth+9p7SXciBl4EJNUHsOfaG0hDld8Egv0bS7maDYT87W2BGuwL67H0SpvYIzWzsdpijk4R9+OxTc0uwCztXYd9sI7cTbOVLwLP9O3Gbhcm+jSnu5VvIxulYtwMtZq9mF8T+VsnKlYhj0ww/rbEQsUSzFR5Tv4ONZq9jeYrzINVytexSQbZh+co7gBR6k8gl2wVrPzMVtlL9yPsXgBR+sANe3nMNyk2B6rDM6L6Fa8Fas12gJrFA9ikmY/xbsxH8dr9HmchzXY0uBsjVcUL2C8ZrthueJ6HK1RHb9VnIJ/1uhyTMdyfMDg7ImligcwWbNP4NuKs3GmRjvjccUh+I42VNd+xinWYpXB+Ry6FUdgtWav41brb5ziFwbvdJUDtLYCj1p/4xT/a/BOUzlAazfiN0a5uvazQvEmzDc4hymex7cMjxWKXXCKwTlUsRjLDI8VioMw1eAcprgar+pgde3nv3ClYiZ6cbH+7a5YZPhci0WKC9GLE/RtC+ysuNfwOQtPK25GLw7Qt/ejrvgPHa5Le/ocluMrihNwgmJbvKLRWMWzhtcUfBknKi7GxXgJYzUaq/KM4bUTvosDFbcpluAvNBqn8qwOV9e+LkENu2r0Ms7XaJ1ijOH396jhUJVu9GKGyjqVuuF3EGqYrTIJvdhXZZ3KGB2urv2tRA01PKc4FR9VeVHxNiPnZtTwFpXL8F7Fiyo7GTkXoYbdVb6v8oLKjjpc3eiyA55XHKLy34rJRt7r2EplquKXeEox2chbgQ+qTFU8pjJZh6sbfR5W/IHKnYrtcLi+bWt4vIafKzZXuVOxF3bTt27D42GVzRVv4PuKadhCa1vizUa5uvZzHHq1Ng77KpaqXKxyI7o1ewR7WX9fwhNa+xD+SLFMZZ7KPVr7Nbaz/r6NO7R2pMoylXkq92j2DqzWAbq0l7fjCkWv4jO4BrfiIMUqXKqyFtNwleJFrc3CVwzdFJyu6FVMxgN4FH+mWIw7VB7F2TgD26BXa+fj84ZuOj6h6FVsh+exFl2Kq/GEyq24HkdhAnq1dhsONIqN0V5Wowc7YE/FoTgLOyueww6arcByHKG1HbEN/hpP4wrNTsQ2WIbbVJ5CD/bGuxXH4SyMU/wn9tbsHqzBRzR7HZthD+yHh7FQoxr+QXEXHlD5EXpwDLZWnIqzUFd8E5/VbCG2wwTNHsL2mIIP4l7co1E3ZikW4HEREREREREREREREREREREREaNXTee6DkdhDuYa2OWYrtFtOEj/puJmrV2OGQbveYzDRCw1sCfxTo1OxDz9uwR/p7W/wo06RE1nmYglGs3BXH37EO7Xvz3xQ80exAT9+yH21Lcv4p80moil+nYmevTtZXRr9la8amDn4gs6QJfOcSrONzRH4nrFo/hzld2wXLEEXRq9CRMU++JujS7CydgDx+NSze7C/obmShyrmIcTVWbjAmyL2/ExjfZSrMMYzR7Crjgd38CPjXJjdI770YMe9OCLGIO7cZ/WfoNZmIMjNVqFWzEDdbyGB1TW4SbMws80uwszsCW6cK1m16AHPViEzyq+jme0thMOxERcqdH9+BX2w3uxEM+r/ASr8TGt3YfjFT/HA0a5uujPj1HDXK39CIsV+2i2Euv0bblivI3nUtSwVGuXqOyt2b/o20q8oRivA9TFhvqJYqyhG6tYZeS8jqcV4w3NNuhSrNIB6mJDbaV4zdB8ABMUC42srRSrDc10lYU6QJfYUB9WLDF4h2Kh4t/xdSNnArZULDF4l+JvFSfhKR2gS2yIY7G14ip9ew+e0GwO5hpZJymewGJ9m4n5mk3EUh2iLjbEJYqr8aShe8zI+kscqeixfh7XQbrE+roBmytm6N9PUVN5FtvjJryGrYyMmxX34Vr9uwyXKXbFQ4r/w0IcrgPUxfqYhSMUn8SvDM0OqOG32BJLDL9b0K2YamgeRg37Kg7DOTpAXQzVRzBPMQ//Zv1NVUzEPobPBThYcTBesX7uxsWK2TpAXQzF+3Gn4gc40YZZpLKH4XEKZitOx3dtmEWKzfA+o1xdDNZ7sELxOPaz4cao1G18M3Gh4hKcZ8ONUakb5epiMHbCE4qX8KcG9g7M1r8DVFbauI7BfMUCzDKw47Cb/h2gstIo1yUGsgP+R/EGxhqc+/E27I+PavZ23KD4Be608Xwa/6q4HUca2C64QnEqLtTsGByruBLrjHI1neFoXGtwTsKXFdvhOZUjsEDffoD9FMfjqwZnd6zQ6JuYZnDeh0cUn8I1invxJKbp2+k4T3EzphrYCxivA9RFf76k0QKDdylqWKtvb6CGFTaeuSr7YJrBOwRT9O92jBcRERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERETGa/D8Rm8iOzF+WUQAAAABJRU5ErkJggg==",
"mime_type": "image/png"
}
]
}),
});
console.log(await response.text());
```
### Python
```python
import requests
response = requests.post(
"https://sandbox.payme.io/api/upload-seller-files",
json={
"payme_client_key": "XXXXXXXX",
"seller_payme_id": "XXXXXXXX-XXXXXXXX-XXXXXXXX-XXXXXXXX",
"seller_files": [
{
"name": "dummy.pdf",
"type": 1,
"url": "https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf",
"mime_type": "application/pdf",
},
{
"name": "test.png",
"type": 2,
"base64": "iVBORw0KGgoAAAANSUhEUgAAAMgAAADICAYAAACtWK6eAAAAAklEQVR4AewaftIAAAkOSURBVO3BabDdZWEH4OecXKUUQeAmYRGtW2lLRVBIUkNhJgI6shgWW1nUCJgmpRMoEATNQLmFRtZWIhJEqLLHChkEKYsKKTTQkOgkECgoCtqyhL0hjEswtx/eD3/PnHO3JPeac8/veURERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERLShmvhdt+BgPIhJWpuMxRotwhTD5xHsgutxtNY+g6s0ugLTDZ9f4804G2dq7R9xhkZfwLnaQF0MxbuwWLPb/X7tj6s0u8Pv10ycodnt2kSXGIqTVbbHKpuGkxWv4y02HScrVmB3baguhmKS4hassumYpPiaTUc3/ljxNW2qLoaiW/GMTUcN2yiesenYVuVZbaouflevwek1snr1rabSa2T16ltNpVeb6tLeTsGFKtfi0wZ2Gs5V2RUr8ZqNYz5mqpyFHgO7HNNV/hC/xBobx13YX+VTuM7A7sYUxdPYSbEGmxnFatrTHlimb9/CEZrth+9p7SXciBl4EJNUHsOfaG0hDld8Egv0bS7maDYT87W2BGuwL67H0SpvYIzWzsdpijk4R9+OxTc0uwCztXYd9sI7cTbOVLwLP9O3Gbhcm+jSnu5VvIxulYtwMtZq9mF8T+VsnKlYhj0ww/rbEQsUSzFR5Tv4ONZq9jeYrzINVytexSQbZh+co7gBR6k8gl2wVrPzMVtlL9yPsXgBR+sANe3nMNyk2B6rDM6L6Fa8Fas12gJrFA9ikmY/xbsxH8dr9HmchzXY0uBsjVcUL2C8ZrthueJ6HK1RHb9VnIJ/1uhyTMdyfMDg7ImligcwWbNP4NuKs3GmRjvjccUh+I42VNd+xinWYpXB+Ry6FUdgtWav41brb5ziFwbvdJUDtLYCj1p/4xT/a/BOUzlAazfiN0a5uvazQvEmzDc4hymex7cMjxWKXXCKwTlUsRjLDI8VioMw1eAcprgar+pgde3nv3ClYiZ6cbH+7a5YZPhci0WKC9GLE/RtC+ysuNfwOQtPK25GLw7Qt/ejrvgPHa5Le/ocluMrihNwgmJbvKLRWMWzhtcUfBknKi7GxXgJYzUaq/KM4bUTvosDFbcpluAvNBqn8qwOV9e+LkENu2r0Ms7XaJ1ijOH396jhUJVu9GKGyjqVuuF3EGqYrTIJvdhXZZ3KGB2urv2tRA01PKc4FR9VeVHxNiPnZtTwFpXL8F7Fiyo7GTkXoYbdVb6v8oLKjjpc3eiyA55XHKLy34rJRt7r2EplquKXeEox2chbgQ+qTFU8pjJZh6sbfR5W/IHKnYrtcLi+bWt4vIafKzZXuVOxF3bTt27D42GVzRVv4PuKadhCa1vizUa5uvZzHHq1Ng77KpaqXKxyI7o1ewR7WX9fwhNa+xD+SLFMZZ7KPVr7Nbaz/r6NO7R2pMoylXkq92j2DqzWAbq0l7fjCkWv4jO4BrfiIMUqXKqyFtNwleJFrc3CVwzdFJyu6FVMxgN4FH+mWIw7VB7F2TgD26BXa+fj84ZuOj6h6FVsh+exFl2Kq/GEyq24HkdhAnq1dhsONIqN0V5Wowc7YE/FoTgLOyueww6arcByHKG1HbEN/hpP4wrNTsQ2WIbbVJ5CD/bGuxXH4SyMU/wn9tbsHqzBRzR7HZthD+yHh7FQoxr+QXEXHlD5EXpwDLZWnIqzUFd8E5/VbCG2wwTNHsL2mIIP4l7co1E3ZikW4HEREREREREREREREREREREREaNXTee6DkdhDuYa2OWYrtFtOEj/puJmrV2OGQbveYzDRCw1sCfxTo1OxDz9uwR/p7W/wo06RE1nmYglGs3BXH37EO7Xvz3xQ80exAT9+yH21Lcv4p80moil+nYmevTtZXRr9la8amDn4gs6QJfOcSrONzRH4nrFo/hzld2wXLEEXRq9CRMU++JujS7CydgDx+NSze7C/obmShyrmIcTVWbjAmyL2/ExjfZSrMMYzR7Crjgd38CPjXJjdI770YMe9OCLGIO7cZ/WfoNZmIMjNVqFWzEDdbyGB1TW4SbMws80uwszsCW6cK1m16AHPViEzyq+jme0thMOxERcqdH9+BX2w3uxEM+r/ASr8TGt3YfjFT/HA0a5uujPj1HDXK39CIsV+2i2Euv0bblivI3nUtSwVGuXqOyt2b/o20q8oRivA9TFhvqJYqyhG6tYZeS8jqcV4w3NNuhSrNIB6mJDbaV4zdB8ABMUC42srRSrDc10lYU6QJfYUB9WLDF4h2Kh4t/xdSNnArZULDF4l+JvFSfhKR2gS2yIY7G14ip9ew+e0GwO5hpZJymewGJ9m4n5mk3EUh2iLjbEJYqr8aShe8zI+kscqeixfh7XQbrE+roBmytm6N9PUVN5FtvjJryGrYyMmxX34Vr9uwyXKXbFQ4r/w0IcrgPUxfqYhSMUn8SvDM0OqOG32BJLDL9b0K2YamgeRg37Kg7DOTpAXQzVRzBPMQ//Zv1NVUzEPobPBThYcTBesX7uxsWK2TpAXQzF+3Gn4gc40YZZpLKH4XEKZitOx3dtmEWKzfA+o1xdDNZ7sELxOPaz4cao1G18M3Gh4hKcZ8ONUakb5epiMHbCE4qX8KcG9g7M1r8DVFbauI7BfMUCzDKw47Cb/h2gstIo1yUGsgP+R/EGxhqc+/E27I+PavZ23KD4Be608Xwa/6q4HUca2C64QnEqLtTsGByruBLrjHI1neFoXGtwTsKXFdvhOZUjsEDffoD9FMfjqwZnd6zQ6JuYZnDeh0cUn8I1invxJKbp2+k4T3EzphrYCxivA9RFf76k0QKDdylqWKtvb6CGFTaeuSr7YJrBOwRT9O92jBcRERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERETGa/D8Rm8iOzF+WUQAAAABJRU5ErkJggg==",
"mime_type": "image/png",
},
],
},
)
print(response.text)
```
### PHP
```php
'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;
```
## Responses
### 200 — OK (success)
| Field | Type | Description |
| --- | --- | --- |
| `status_code` | number | Status of the request (0 - success, 1 - error) |
```json
{
"status_code": 1
}
```
### 500 — Internal Server Error (error)
| Field | Type | Description |
| --- | --- | --- |
| `status_code` | number | |
| `status_error_details` | string | |
| `status_additional_info` | string | |
| `status_error_code` | number | |
```json
{
"status_code": 0,
"status_error_details": "string",
"status_additional_info": "string",
"status_error_code": 0
}
```
- [Retrieve Seller's Additional Services Data](https://docs-staging.payme.io/payments/merchants-management/post-get-vas-seller): POST /get-vas-seller — Retrieve Seller's Additional Services Data
# Retrieve Seller's Additional Services Data
- Sandbox: `POST https://sandbox.payme.io/api/get-vas-seller`
- Production: `POST https://live.payme.io/api/get-vas-seller`
## Credentials
- Request body field `payme_client_key` (required): The PayMe client key
- Request body field `seller_payme_id` (required): The MPL of the seller
## Overview
This endpoint is used to retrieve seller's additional services data.
## Parameters
This endpoint takes no path, query or header parameters.
## Request body
Content type: `application/json`
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `payme_client_key` | string | yes | The PayMe client key |
| `seller_payme_id` | string | yes | The MPL of the seller |
### Request example
```json
{
"payme_client_key": "",
"seller_payme_id": "MPL00011-00011EXM-EXAMPLE0-EXAMPLE1"
}
```
## Code samples
### curl
```bash
curl -X POST 'https://sandbox.payme.io/api/get-vas-seller' \
-H 'Content-Type: application/json' \
--data-raw '{
"payme_client_key": "",
"seller_payme_id": "MPL00011-00011EXM-EXAMPLE0-EXAMPLE1"
}'
```
### Node.js
```javascript
const response = await fetch("https://sandbox.payme.io/api/get-vas-seller", {
method: "POST",
headers: {
"Content-Type": "application/json",
},
body: JSON.stringify({
"payme_client_key": "",
"seller_payme_id": "MPL00011-00011EXM-EXAMPLE0-EXAMPLE1"
}),
});
console.log(await response.text());
```
### Python
```python
import requests
response = requests.post(
"https://sandbox.payme.io/api/get-vas-seller",
json={
"payme_client_key": "",
"seller_payme_id": "MPL00011-00011EXM-EXAMPLE0-EXAMPLE1",
},
)
print(response.text)
```
### PHP
```php
",
"seller_payme_id": "MPL00011-00011EXM-EXAMPLE0-EXAMPLE1"
}
BODY;
$ch = curl_init('https://sandbox.payme.io/api/get-vas-seller');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;
```
## Responses
### 200 — OK (success)
| Field | Type | Description |
| --- | --- | --- |
| `status_code` | integer | 0 success 1 failrue |
| `seller_payme_id` | string | The MPL of the seller |
| `vas_payme_id` | string | The VAS guid |
| `items_count` | integer | VASes count |
| `items` | array | |
| `items[].vas_description` | string | The VAS description |
| `items[].vas_type` | string | The VAS type |
| `items[].vas_api_key` | string | The VAS Guid |
| `items[].vas_is_active` | boolean | Is the VAS active or not |
| `items[].vas_payer_type` | integer | The payer type |
| `items[].vas_price_currency` | string | VAS fee currency |
| `items[].vas_price_setup_fixed` | integer | VAS setup price (fixed) |
| `items[].vas_price_periodic_fixed` | integer | VAS periodic price (fixed) |
| `items[].vas_price_periodic_variable` | string | VAS periodic price (fixed) |
| `items[].vas_price_usage_fixed` | integer | VAS usage price (fixed) |
| `items[].vas_price_usage_variable` | string | VAS usage price (fixed) |
| `items[].vas_market_fee` | string | VAS market fee |
| `items[].vas_period` | integer | VAS period \| Code ----\|---- Instant \| 1 Daily \| 2 Monthly \| 3 Yearly \| 4 |
| `items[].vas_data` | array | Data that saved under the VAS |
```json
{
"status_code": 0,
"seller_payme_id": "MPL16581-DEMO-DEMO-DEMO",
"vas_payme_id": null,
"items_count": 15,
"items": [
{
"vas_description": "עמלת סליקה",
"vas_type": "Settlements",
"vas_api_key": null,
"vas_is_active": true,
"vas_payer_type": 2,
"vas_price_currency": "ILS",
"vas_price_setup_fixed": 0,
"vas_price_periodic_fixed": 0,
"vas_price_periodic_variable": "0.00",
"vas_price_usage_fixed": 0,
"vas_price_usage_variable": "0.00",
"vas_market_fee": null,
"vas_period": 1,
"vas_data": []
}
]
}
```
- [Withdraw Balance](https://docs-staging.payme.io/payments/merchants-management/post-withdraw-balance): POST /withdraw-balance — Withdraw Balance
# Withdraw Balance
- Sandbox: `POST https://sandbox.payme.io/api/withdraw-balance`
- Production: `POST https://live.payme.io/api/withdraw-balance`
## Credentials
- Request body field `payme_client_key` (required): Your private key provided by us for authentication
- Request body field `seller_payme_id` (required): Our unique seller ID
## Overview
This endpoint is used to generate a new request to withdraw balance.
#### Notes
* Until we obtain and verify the 3 mandatory documents (`Social Id, Bank, Corporate Certificate`), funds will not be available for withdrawal to the Seller's bank account.
* **Partial-withdrawal** - In order to create a partial-withdrawal, you will need to add another parameter to your request which states which transactions you are willing to get the balance for to your bank account.
Parameter|Description
---|---
`transaction_ids`| The transaction GUIDs that will be included as a part of your withdrawal request.
### Withdrawal Callback Notification Types
Notification |Description
--|--
withdrawal-complete |A withdrawal was completed successfully
Attribute| Description
--|--
status_code |`0` Status of the request (0 - success, 1 - error)
notify_type |`withdrawal-complete`
seller_payme_id| `XXXXXXXX-XXXXXXXX-XXXXXXXX-XXXXXXXX`
tran_payme_code| `123456` Our unique Withdrawal code
tran_created |`2016-01-01 15:15:15`
tran_type |`40` Financial Transaction type Bank Withdrawal
tran_currency |`USD`
tran_total |`10000`
tran_description| `משיכה לבנק
## Parameters
This endpoint takes no path, query or header parameters.
## Request body
Content type: `application/json`
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `payme_client_key` | string | yes | Your private key provided by us for authentication |
| `seller_payme_id` | string | yes | Our unique seller ID |
| `withdrawal_currency` | string | yes | Sale currency. [3-letter ISO 4217 name](https://en.wikipedia.org/wiki/ISO_4217). |
| `language` | string | no | Changes the error message language to English. Default value is Hebrew (he) |
| `transaction_ids` | array | no | The transaction IDs that will be used for the partial withdrawal request. Transaction guids can be fetched using our `get-transcations` API endpoint. Example: TRANDEMO-XXXXXXXX-XXXXXXXX-XXXXXXXX |
### Request example
```json
{
"payme_client_key": "string",
"seller_payme_id": "string",
"withdrawal_currency": "string"
}
```
## Code samples
### curl
```bash
curl -X POST 'https://sandbox.payme.io/api/withdraw-balance' \
-H 'Content-Type: application/json' \
--data-raw '{
"payme_client_key": "string",
"seller_payme_id": "string",
"withdrawal_currency": "string"
}'
```
### Node.js
```javascript
const response = await fetch("https://sandbox.payme.io/api/withdraw-balance", {
method: "POST",
headers: {
"Content-Type": "application/json",
},
body: JSON.stringify({
"payme_client_key": "string",
"seller_payme_id": "string",
"withdrawal_currency": "string"
}),
});
console.log(await response.text());
```
### Python
```python
import requests
response = requests.post(
"https://sandbox.payme.io/api/withdraw-balance",
json={
"payme_client_key": "string",
"seller_payme_id": "string",
"withdrawal_currency": "string",
},
)
print(response.text)
```
### PHP
```php
'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;
```
## Responses
### 200 — OK (success)
| Field | Type | Description |
| --- | --- | --- |
| `status_code` | number | Status of the request (0 - success, 1 - error) |
```json
{
"status_code": 0
}
```
### 500 — Internal Server Error (error)
| Field | Type | Description |
| --- | --- | --- |
| `status_code` | number | |
| `status_error_details` | string | |
| `status_additional_info` | string | |
| `status_error_code` | number | |
```json
{
"status_code": 0,
"status_error_details": "string",
"status_additional_info": null,
"status_error_code": 0
}
```
- [Get Seller Public Key](https://docs-staging.payme.io/payments/merchants-management/get-sellers-mpl-public-keys): GET /sellers/{seller_payme_id}/public-keys — Get Seller Public Key
# Get Seller Public Key
- Sandbox: `GET https://sandbox.payme.io/api/sellers/{seller_payme_id}/public-keys`
- Production: `GET https://live.payme.io/api/sellers/{seller_payme_id}/public-keys`
## Credentials
- Header `PayMe-Partner-Key` (API key)
## Overview
This API endpoint will allow you as a partner to get the unique public keys used for various services in our system.
## Parameters
| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `PayMe-Partner-Key` | header | string | yes | The PayMe unique partner key. |
| `seller_payme_id` | path | string | yes | |
## Code samples
### curl
```bash
curl -X GET 'https://sandbox.payme.io/api/sellers//public-keys' \
-H 'PayMe-Partner-Key: '
```
### Node.js
```javascript
const response = await fetch("https://sandbox.payme.io/api/sellers//public-keys", {
method: "GET",
headers: {
"PayMe-Partner-Key": "",
},
});
console.log(await response.text());
```
### Python
```python
import requests
response = requests.get(
"https://sandbox.payme.io/api/sellers//public-keys",
headers={
"PayMe-Partner-Key": "",
},
)
print(response.text)
```
### PHP
```php
/public-keys');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'PayMe-Partner-Key: ',
],
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;
```
## Responses
### 200 — OK (success)
| Field | Type | Description |
| --- | --- | --- |
| `status_code` | integer | Status code 0 - Success Status code 1 - Failure |
| `page` | integer | Page presented |
| `items_total` | integer | Total count of items |
| `items_per_page` | integer | Items per page count |
| `seller_payme_id` | string | The unique seller ID |
| `items` | array | |
| `items[].uuid` | string | The unique public key |
| `items[].description` | string | The public key title |
```json
{
"status_code": 0,
"page": 1,
"items_total": 1,
"items_per_page": 1,
"seller_payme_id": "MPL151111-1111111-SAUCJ4KX-TVEDZCIN",
"items": [
{
"uuid": "12345678-7c83-46fc-ac97-12345678",
"description": "PayMe-Public-Key"
}
]
}
```
- [Delayed Market Fee](https://docs-staging.payme.io/payments/merchants-management/patch-sales-guid-external-market-fee): PATCH /sales/{guid}/external-market-fee — Delayed Market Fee
# Delayed Market Fee
- Sandbox: `PATCH https://sandbox.payme.io/api/sales/{guid}/external-market-fee`
- Production: `PATCH https://live.payme.io/api/sales/{guid}/external-market-fee`
## Credentials
- Header `PayMe-Partner-Key` (API key) and Header `PayMe-Merchant-Key` (API key)
## Overview
This endpoint allows you to create a new charge (fee) that is connected to a sale and is limited by the transaction amount.
### Limitations
1. You must include at least one of the following - `market_fee_percentage` or `market_fee_fixed`
2. The sale must be generated by the MPL
3. `market_fee_percentage` - can be from 0.0 to 60.0
4. `market_fee_fixed` - limited to the amount settled to the wallet and cannot be higher than that.
## Parameters
| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `PayMe-Partner-Key` | header | string | no | The partner secret key. |
| `PayMe-Merchant-Key` | header | string | no | The MPL of the seller. |
| `guid` | path | string | yes | |
## Request body
Content type: `application/json`
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `market_fee_percentage` | number | no | The percentage that will be charged. Limited to be between 0 to 60. |
| `market_fee_fixed` | integer | no | The fixed market fee - limited to the amount settled to the wallet. |
### Request example
```json
{
"market_fee_percentage": 10.2,
"market_fee_fixed": 15000
}
```
## Code samples
### curl
```bash
curl -X PATCH 'https://sandbox.payme.io/api/sales//external-market-fee' \
-H 'Content-Type: application/json' \
-H 'PayMe-Partner-Key: ' \
-H 'PayMe-Merchant-Key: ' \
--data-raw '{
"market_fee_percentage": 10.2,
"market_fee_fixed": 15000
}'
```
### Node.js
```javascript
const response = await fetch("https://sandbox.payme.io/api/sales//external-market-fee", {
method: "PATCH",
headers: {
"Content-Type": "application/json",
"PayMe-Partner-Key": "",
"PayMe-Merchant-Key": "",
},
body: JSON.stringify({
"market_fee_percentage": 10.2,
"market_fee_fixed": 15000
}),
});
console.log(await response.text());
```
### Python
```python
import requests
response = requests.patch(
"https://sandbox.payme.io/api/sales//external-market-fee",
headers={
"PayMe-Partner-Key": "",
"PayMe-Merchant-Key": "",
},
json={
"market_fee_percentage": 10.2,
"market_fee_fixed": 15000,
},
)
print(response.text)
```
### PHP
```php
/external-market-fee');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'PATCH',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Content-Type: application/json',
'PayMe-Partner-Key: ',
'PayMe-Merchant-Key: ',
],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;
```
## Responses
### 200 — OK (success)
| Field | Type | Description |
| --- | --- | --- |
| `status_code` | integer | 0 - Sucess 1 - Failure |
| `payme_status` | string | The status of the action. |
| `payme_sale_id` | string | The sale the fee was associated with. |
```json
{
"status_code": 0,
"payme_status": "success",
"payme_sale_id": "SALEGUID-SALEGUID-SALEGUID-SALEGUID"
}
```
- [Create Individual](https://docs-staging.payme.io/payments/merchants-management/post-sellers-mpl-key-individuals): POST /sellers/{mpl_key}/individuals — Create Individual
# Create Individual
- Sandbox: `POST https://sandbox.payme.io/api/sellers/{mpl_key}/individuals`
- Production: `POST https://live.payme.io/api/sellers/{mpl_key}/individuals`
## Credentials
- Header `PayMe-Merchant-Key` (API key)
- Header `PayMe-Signature` (optional): Example: sk_test__123123213123
## Overview
Using this method, you will be able to create a new individual under your company.
When creating an individual, you will need to set it's roles based on the following list:
Role | Enum
-- | --
Owner | 1
Signatory | 2
Director | 4
Executive | 8
Back Office | 16
## Parameters
| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `PayMe-Signature` | header | string | no | Example: sk_test__123123213123 |
| `PayMe-Merchant-Key` | header | string | no | Example: MPL123-123-123 |
| `mpl_key` | path | string | yes | |
## Request body
Content type: `application/json`
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `first_name` | string | no | Individual's first name in the company's local language. |
| `first_name_en` | string | no | Individual's first name in English. |
| `last_name` | string | no | Individual's last name in the company's local language. |
| `last_name_en` | string | no | Individual's last name in english. |
| `national_id` | string | no | Individual's national ID. |
| `social_id` | string | no | Individual's national ID (Will be deprecated). |
| `social_id_issued` | string | no | Individual's Social ID issuing date. |
| `social_id_country` | string | no | Individual's Social ID issuing country. |
| `birthdate` | string | no | The birthdate of the individual. |
| `gender` | string | no | The gender of the individual. |
| `email` | string | no | The email address of the individual. Must be in an email address format. |
| `phone` | string | no | The phone number of the individual. |
| `bank` | string | no | The bank code of the invdividual. |
| `bank_account` | string | no | The bank account number of the invdividual. |
| `bank_account_branch` | string | no | The bank account branch of the invdividual. |
| `bank_account_number_foreign` | string | no | The foreign bank account number of the individual. |
| `bank_routing_number_foreign` | string | no | The foreign bank account routing number of the individual. |
| `iban` | string | no | The individual's bank account IBAN. |
| `is_active` | boolean | no | The indicator whether the individual is a part of the company or not. |
| `block_reason` | string | no | The block reason of the individual from accessing PayMe's platform and data. |
| `account_status` | string | no | The individual's account status. |
| `address_street` | string | no | The street address of the individual. |
| `address_street_intl` | string | no | The international street address of the individual. |
| `address_street_number` | string | no | The street address number of the individual. |
| `address_zip` | string | no | The street address ZIP code of the individual. |
| `address_city` | string | no | The street address city of the individual. |
| `address_city_intl` | string | no | The international street address city of the individual. |
| `address_country` | string | no | The street address country of the individual. |
| `address_state` | string | no | The street address state of the individual. |
| `additional_data` | string | no | Any additional data that needs to be stored under the individual in a JSON format. |
| `role` | array | no | 1 => "Owner", 2 => "Signatory", 4 => "Director", 8 => "Executive", 16 => "Back Office", |
| `is_primary` | boolean | no | Setting the primary flag under the company whether the individual is the primary of the company. |
| `ownership_percentage` | string | no | Example: "20.5" |
| `business_title` | string | no | The business title of the individual. |
### Request example
```json
{
"individual_first_name": "John",
"individual_first_name_en": "John",
"individual_last_name": "Doe",
"individual_last_name_en": "Doe",
"individual_national_id": "1234567890",
"individual_social_id": "987654321",
"individual_social_id_issued": "2022-01-01",
"individual_social_id_country": "US",
"individual_birthdate": "1990-01-01",
"individual_gender": "Male",
"individual_email": "johndoe@example.com",
"individual_phone": "1234567890",
"individual_bank": "PayMe Bank",
"individual_bank_account": "9876543210",
"individual_bank_account_branch": "Main Branch",
"individual_bank_account_number_foreign": "1234567890",
"individual_bank_routing_number_foreign": "ABCDEFG12345",
"individual_iban": "US00 ABCD 1234 5678 90",
"individual_is_active": true,
"individual_block_reason": "No reason",
"individual_account_status": "Active",
"individual_address_street": "123 PayMe St.",
"individual_address_street_intl": "123 PayMe St.",
"individual_address_street_number": "123",
"individual_address_zip": "12345",
"individual_address_city": "PayMe City",
"individual_address_city_intl": "PayMe City",
"individual_address_country": "US",
"individual_address_state": "PayMe State",
"individual_additional_data": "Additional data here"
}
```
## Code samples
### curl
```bash
curl -X POST 'https://sandbox.payme.io/api/sellers//individuals' \
-H 'Content-Type: application/json' \
-H 'PayMe-Signature: ' \
-H 'PayMe-Merchant-Key: ' \
--data-raw '{
"individual_first_name": "John",
"individual_first_name_en": "John",
"individual_last_name": "Doe",
"individual_last_name_en": "Doe",
"individual_national_id": "1234567890",
"individual_social_id": "987654321",
"individual_social_id_issued": "2022-01-01",
"individual_social_id_country": "US",
"individual_birthdate": "1990-01-01",
"individual_gender": "Male",
"individual_email": "johndoe@example.com",
"individual_phone": "1234567890",
"individual_bank": "PayMe Bank",
"individual_bank_account": "9876543210",
"individual_bank_account_branch": "Main Branch",
"individual_bank_account_number_foreign": "1234567890",
"individual_bank_routing_number_foreign": "ABCDEFG12345",
"individual_iban": "US00 ABCD 1234 5678 90",
"individual_is_active": true,
"individual_block_reason": "No reason",
"individual_account_status": "Active",
"individual_address_street": "123 PayMe St.",
"individual_address_street_intl": "123 PayMe St.",
"individual_address_street_number": "123",
"individual_address_zip": "12345",
"individual_address_city": "PayMe City",
"individual_address_city_intl": "PayMe City",
"individual_address_country": "US",
"individual_address_state": "PayMe State",
"individual_additional_data": "Additional data here"
}'
```
### Node.js
```javascript
const response = await fetch("https://sandbox.payme.io/api/sellers//individuals", {
method: "POST",
headers: {
"Content-Type": "application/json",
"PayMe-Signature": "",
"PayMe-Merchant-Key": "",
},
body: JSON.stringify({
"individual_first_name": "John",
"individual_first_name_en": "John",
"individual_last_name": "Doe",
"individual_last_name_en": "Doe",
"individual_national_id": "1234567890",
"individual_social_id": "987654321",
"individual_social_id_issued": "2022-01-01",
"individual_social_id_country": "US",
"individual_birthdate": "1990-01-01",
"individual_gender": "Male",
"individual_email": "johndoe@example.com",
"individual_phone": "1234567890",
"individual_bank": "PayMe Bank",
"individual_bank_account": "9876543210",
"individual_bank_account_branch": "Main Branch",
"individual_bank_account_number_foreign": "1234567890",
"individual_bank_routing_number_foreign": "ABCDEFG12345",
"individual_iban": "US00 ABCD 1234 5678 90",
"individual_is_active": true,
"individual_block_reason": "No reason",
"individual_account_status": "Active",
"individual_address_street": "123 PayMe St.",
"individual_address_street_intl": "123 PayMe St.",
"individual_address_street_number": "123",
"individual_address_zip": "12345",
"individual_address_city": "PayMe City",
"individual_address_city_intl": "PayMe City",
"individual_address_country": "US",
"individual_address_state": "PayMe State",
"individual_additional_data": "Additional data here"
}),
});
console.log(await response.text());
```
### Python
```python
import requests
response = requests.post(
"https://sandbox.payme.io/api/sellers//individuals",
headers={
"PayMe-Signature": "",
"PayMe-Merchant-Key": "",
},
json={
"individual_first_name": "John",
"individual_first_name_en": "John",
"individual_last_name": "Doe",
"individual_last_name_en": "Doe",
"individual_national_id": "1234567890",
"individual_social_id": "987654321",
"individual_social_id_issued": "2022-01-01",
"individual_social_id_country": "US",
"individual_birthdate": "1990-01-01",
"individual_gender": "Male",
"individual_email": "johndoe@example.com",
"individual_phone": "1234567890",
"individual_bank": "PayMe Bank",
"individual_bank_account": "9876543210",
"individual_bank_account_branch": "Main Branch",
"individual_bank_account_number_foreign": "1234567890",
"individual_bank_routing_number_foreign": "ABCDEFG12345",
"individual_iban": "US00 ABCD 1234 5678 90",
"individual_is_active": True,
"individual_block_reason": "No reason",
"individual_account_status": "Active",
"individual_address_street": "123 PayMe St.",
"individual_address_street_intl": "123 PayMe St.",
"individual_address_street_number": "123",
"individual_address_zip": "12345",
"individual_address_city": "PayMe City",
"individual_address_city_intl": "PayMe City",
"individual_address_country": "US",
"individual_address_state": "PayMe State",
"individual_additional_data": "Additional data here",
},
)
print(response.text)
```
### PHP
```php
/individuals');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Content-Type: application/json',
'PayMe-Signature: ',
'PayMe-Merchant-Key: ',
],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;
```
## Responses
### 200 — OK (success)
- [Update Individual](https://docs-staging.payme.io/payments/merchants-management/post-sellers-mpl-key-individuals-2): POST /sellers/{mpl_key}/individuals/{individual_key} — Update Individual
# Update Individual
- Sandbox: `POST https://sandbox.payme.io/api/sellers/{mpl_key}/individuals/{individual_key}`
- Production: `POST https://live.payme.io/api/sellers/{mpl_key}/individuals/{individual_key}`
## Credentials
No credentials are documented for this endpoint.
## Overview
Using this method, you will be able to update an existing individual under your company.
When creating an individual, you will need to set it's roles based on the following list:
Role | Enum
-- | --
Owner | 1
Signatory | 2
Director | 4
Executive | 8
Back Office | 16
## Parameters
| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `mpl_key` | path | string | yes | |
| `individual_key` | path | string | yes | |
## Request body
Content type: `application/json`
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `first_name` | string | no | Individual's first name in the company's local language. |
| `first_name_en` | string | no | Individual's first name in English. |
| `last_name` | string | no | Individual's last name in the company's local language. |
| `last_name_en` | string | no | Individual's last name in english. |
| `national_id` | string | no | Individual's national ID. |
| `social_id` | string | no | Individual's national ID (Will be deprecated). |
| `social_id_issued` | string | no | Individual's Social ID issuing date. |
| `social_id_country` | string | no | Individual's Social ID issuing country. |
| `birthdate` | string | no | The birthdate of the individual. |
| `gender` | string | no | The gender of the individual. |
| `email` | string | no | The email address of the individual. Must be in an email address format. |
| `phone` | string | no | The phone number of the individual. |
| `bank` | string | no | The bank code of the invdividual. |
| `bank_account` | string | no | The bank account number of the invdividual. |
| `bank_account_branch` | string | no | The bank account branch of the invdividual. |
| `bank_account_number_foreign` | string | no | The foreign bank account number of the individual. |
| `bank_routing_number_foreign` | string | no | The foreign bank account routing number of the individual. |
| `iban` | string | no | The individual's bank account IBAN. |
| `is_active` | boolean | no | The indicator whether the individual is a part of the company or not. |
| `block_reason` | string | no | The block reason of the individual from accessing PayMe's platform and data. |
| `account_status` | string | no | The individual's account status. |
| `address_street` | string | no | The street address of the individual. |
| `address_street_intl` | string | no | The international street address of the individual. |
| `address_street_number` | string | no | The street address number of the individual. |
| `address_zip` | string | no | The street address ZIP code of the individual. |
| `address_city` | string | no | The street address city of the individual. |
| `address_city_intl` | string | no | The international street address city of the individual. |
| `address_country` | string | no | The street address country of the individual. |
| `address_state` | string | no | The street address state of the individual. |
| `additional_data` | string | no | Any additional data that needs to be stored under the individual in a JSON format. |
| `role` | array | no | 1 => "Owner", 2 => "Signatory", 4 => "Director", 8 => "Executive", 16 => "Back Office", |
| `is_primary` | boolean | no | Setting the primary flag under the company whether the individual is the primary of the company. |
| `ownership_percentage` | string | no | Example: "20.5" |
| `individual_business_title` | string | no | The business title of the individual. |
### Request example
```json
{
"individual_first_name": "John",
"individual_first_name_en": "John",
"individual_last_name": "Doe",
"individual_last_name_en": "Doe",
"individual_national_id": "1234567890",
"individual_social_id": "987654321",
"individual_social_id_issued": "2022-01-01",
"individual_social_id_country": "US",
"individual_birthdate": "1990-01-01",
"individual_gender": "Male",
"individual_email": "johndoe@example.com",
"individual_phone": "1234567890",
"individual_bank": "PayMe Bank",
"individual_bank_account": "9876543210",
"individual_bank_account_branch": "Main Branch",
"individual_bank_account_number_foreign": "1234567890",
"individual_bank_routing_number_foreign": "ABCDEFG12345",
"individual_iban": "US00 ABCD 1234 5678 90",
"individual_is_active": true,
"individual_block_reason": "No reason",
"individual_account_status": "Active",
"individual_address_street": "123 PayMe St.",
"individual_address_street_intl": "123 PayMe St.",
"individual_address_street_number": "123",
"individual_address_zip": "12345",
"individual_address_city": "PayMe City",
"individual_address_city_intl": "PayMe City",
"individual_address_country": "US",
"individual_address_state": "PayMe State",
"individual_additional_data": "Additional data here"
}
```
## Code samples
### curl
```bash
curl -X POST 'https://sandbox.payme.io/api/sellers//individuals/' \
-H 'Content-Type: application/json' \
--data-raw '{
"individual_first_name": "John",
"individual_first_name_en": "John",
"individual_last_name": "Doe",
"individual_last_name_en": "Doe",
"individual_national_id": "1234567890",
"individual_social_id": "987654321",
"individual_social_id_issued": "2022-01-01",
"individual_social_id_country": "US",
"individual_birthdate": "1990-01-01",
"individual_gender": "Male",
"individual_email": "johndoe@example.com",
"individual_phone": "1234567890",
"individual_bank": "PayMe Bank",
"individual_bank_account": "9876543210",
"individual_bank_account_branch": "Main Branch",
"individual_bank_account_number_foreign": "1234567890",
"individual_bank_routing_number_foreign": "ABCDEFG12345",
"individual_iban": "US00 ABCD 1234 5678 90",
"individual_is_active": true,
"individual_block_reason": "No reason",
"individual_account_status": "Active",
"individual_address_street": "123 PayMe St.",
"individual_address_street_intl": "123 PayMe St.",
"individual_address_street_number": "123",
"individual_address_zip": "12345",
"individual_address_city": "PayMe City",
"individual_address_city_intl": "PayMe City",
"individual_address_country": "US",
"individual_address_state": "PayMe State",
"individual_additional_data": "Additional data here"
}'
```
### Node.js
```javascript
const response = await fetch("https://sandbox.payme.io/api/sellers//individuals/", {
method: "POST",
headers: {
"Content-Type": "application/json",
},
body: JSON.stringify({
"individual_first_name": "John",
"individual_first_name_en": "John",
"individual_last_name": "Doe",
"individual_last_name_en": "Doe",
"individual_national_id": "1234567890",
"individual_social_id": "987654321",
"individual_social_id_issued": "2022-01-01",
"individual_social_id_country": "US",
"individual_birthdate": "1990-01-01",
"individual_gender": "Male",
"individual_email": "johndoe@example.com",
"individual_phone": "1234567890",
"individual_bank": "PayMe Bank",
"individual_bank_account": "9876543210",
"individual_bank_account_branch": "Main Branch",
"individual_bank_account_number_foreign": "1234567890",
"individual_bank_routing_number_foreign": "ABCDEFG12345",
"individual_iban": "US00 ABCD 1234 5678 90",
"individual_is_active": true,
"individual_block_reason": "No reason",
"individual_account_status": "Active",
"individual_address_street": "123 PayMe St.",
"individual_address_street_intl": "123 PayMe St.",
"individual_address_street_number": "123",
"individual_address_zip": "12345",
"individual_address_city": "PayMe City",
"individual_address_city_intl": "PayMe City",
"individual_address_country": "US",
"individual_address_state": "PayMe State",
"individual_additional_data": "Additional data here"
}),
});
console.log(await response.text());
```
### Python
```python
import requests
response = requests.post(
"https://sandbox.payme.io/api/sellers//individuals/",
json={
"individual_first_name": "John",
"individual_first_name_en": "John",
"individual_last_name": "Doe",
"individual_last_name_en": "Doe",
"individual_national_id": "1234567890",
"individual_social_id": "987654321",
"individual_social_id_issued": "2022-01-01",
"individual_social_id_country": "US",
"individual_birthdate": "1990-01-01",
"individual_gender": "Male",
"individual_email": "johndoe@example.com",
"individual_phone": "1234567890",
"individual_bank": "PayMe Bank",
"individual_bank_account": "9876543210",
"individual_bank_account_branch": "Main Branch",
"individual_bank_account_number_foreign": "1234567890",
"individual_bank_routing_number_foreign": "ABCDEFG12345",
"individual_iban": "US00 ABCD 1234 5678 90",
"individual_is_active": True,
"individual_block_reason": "No reason",
"individual_account_status": "Active",
"individual_address_street": "123 PayMe St.",
"individual_address_street_intl": "123 PayMe St.",
"individual_address_street_number": "123",
"individual_address_zip": "12345",
"individual_address_city": "PayMe City",
"individual_address_city_intl": "PayMe City",
"individual_address_country": "US",
"individual_address_state": "PayMe State",
"individual_additional_data": "Additional data here",
},
)
print(response.text)
```
### PHP
```php
/individuals/');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;
```
## Responses
### 200 — OK (success)
- [Get-Individuals by Company ID](https://docs-staging.payme.io/payments/merchants-management/get-sellers-mpl-key-individuals): GET /sellers/{mpl_key}/individuals — Get-Individuals by Company ID
# Get-Individuals by Company ID
- Sandbox: `GET https://sandbox.payme.io/api/sellers/{mpl_key}/individuals`
- Production: `GET https://live.payme.io/api/sellers/{mpl_key}/individuals`
## Credentials
- Header `PayMe-Signature` (API key)
This route will help you receive all of the data regarding the individuals
## Parameters
| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `PayMe-Signature` | header | string | no | Example: sk_test__123ASD |
| `mpl_key` | path | string | yes | |
## Request body
Content type: `application/json`
## Code samples
### curl
```bash
curl -X GET 'https://sandbox.payme.io/api/sellers//individuals' \
-H 'Content-Type: application/json' \
-H 'PayMe-Signature: ' \
--data-raw '{}'
```
### Node.js
```javascript
const response = await fetch("https://sandbox.payme.io/api/sellers//individuals", {
method: "GET",
headers: {
"Content-Type": "application/json",
"PayMe-Signature": "",
},
body: JSON.stringify({}),
});
console.log(await response.text());
```
### Python
```python
import requests
response = requests.get(
"https://sandbox.payme.io/api/sellers//individuals",
headers={
"PayMe-Signature": "",
},
json={},
)
print(response.text)
```
### PHP
```php
/individuals');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Content-Type: application/json',
'PayMe-Signature: ',
],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;
```
## Responses
### 200 — OK (success)
| Field | Type | Description |
| --- | --- | --- |
| `status_code` | integer | |
| `page` | integer | |
| `items_per_page` | integer | |
| `items_total` | integer | |
| `items` | array | |
| `items[].guid` | string | |
| `items[].first_name` | string | |
| `items[].last_name` | string | |
| `items[].social_id` | string | |
| `items[].email` | string | |
| `items[].national_id` | string | |
| `items[].role` | array | |
| `items[].is_primary` | boolean | |
| `items[].ownership_percentage` | string | |
| `items[].business_title` | string | |
| `items[].first_name_international` | string | |
| `items[].last_name_international` | string | |
| `items[].social_id_issued` | integer | |
| `items[].national_id_country` | string | |
| `items[].birthdate` | integer | |
| `items[].gender` | integer | |
| `items[].phone_number` | string | |
| `items[].email_address` | string | |
| `items[].bank` | string | |
| `items[].bank_account_branch` | string | |
| `items[].bank_account_number` | string | |
| `items[].bank_routing_number_foreign` | string | |
| `items[].bank_iban` | string | |
| `items[].address_street_name` | string | |
| `items[].address_street_international` | string | |
| `items[].address_street_number` | string | |
| `items[].address_zip_code` | string | |
| `items[].address_city_name` | string | |
| `items[].address_city_international` | string | |
| `items[].address_state_name` | string | |
| `items[].address_country_name` | string | |
```json
{
"status_code": 0,
"page": 1,
"items_per_page": 500,
"items_total": 1,
"items": [
{
"guid": "INDV1693-14592531-QZKL0HO9-PO6QZBDN",
"first_name": "Ohad",
"last_name": "Dabush",
"social_id": "301105052",
"email": null,
"national_id": null,
"role": [
"Owner",
"Signatory",
"Director",
"Executive",
"Back Office"
],
"is_primary": true,
"ownership_percentage": null,
"business_title": null,
"first_name_international": "",
"last_name_international": "",
"social_id_issued": 1508907600,
"national_id_country": null,
"birthdate": 562140000,
"gender": 0,
"phone_number": null,
"email_address": null,
"bank": null,
"bank_account_branch": null,
"bank_account_number": null,
"bank_routing_number_foreign": null,
"bank_iban": null,
"address_street_name": null,
"address_street_international": null,
"address_street_number": null,
"address_zip_code": null,
"address_city_name": null,
"address_city_international": null,
"address_state_name": null,
"address_country_name": null
}
]
}
```
- [Get Partner Data](https://docs-staging.payme.io/payments/merchants-management/get-partners): GET /partners — Get Partner Data
# Get Partner Data
- Sandbox: `GET https://sandbox.payme.io/api/partners`
- Production: `GET https://live.payme.io/api/partners`
## Credentials
- Header `PayMe-Partner-Key` (API key)
This API endpoint is dedicated to providing the information regarding the Partner entity.
cUrl command (Paste to Postman Command line / import):
```
curl --location 'https://sandbox.payme.io/api/partners' \
--header 'Content-Type: application/json' \
--header 'PayMe-Partner-Key: ' \
--data ''
```
## Parameters
| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `PayMe-Partner-Key` | header | string | yes | Your partner client key |
## Request body
Content type: `application/json`
## Code samples
### curl
```bash
curl -X GET 'https://sandbox.payme.io/api/partners' \
-H 'Content-Type: application/json' \
-H 'PayMe-Partner-Key: ' \
--data-raw '{}'
```
### Node.js
```javascript
const response = await fetch("https://sandbox.payme.io/api/partners", {
method: "GET",
headers: {
"Content-Type": "application/json",
"PayMe-Partner-Key": "",
},
body: JSON.stringify({}),
});
console.log(await response.text());
```
### Python
```python
import requests
response = requests.get(
"https://sandbox.payme.io/api/partners",
headers={
"PayMe-Partner-Key": "",
},
json={},
)
print(response.text)
```
### PHP
```php
'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Content-Type: application/json',
'PayMe-Partner-Key: ',
],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;
```
## Responses
### 200 — OK (success)
| Field | Type | Description |
| --- | --- | --- |
| `status_code` | integer | |
| `page` | integer | |
| `items_per_page` | integer | |
| `items_total` | integer | |
| `items` | array | |
| `items[].display_name` | string | |
| `items[].description` | string | |
| `items[].created_at` | string | |
| `items[].activity_type` | string | |
| `items[].main_seller_payme_id` | string | |
| `items[].defaults` | object | |
| `items[].defaults.timezone` | string | |
| `items[].defaults.default_creation_plan` | string | |
| `items[].defaults.allow_foreign_cards` | boolean | |
| `items[].defaults.currencies` | array | |
| `items[].defaults.processing_limit` | integer | |
| `items[].defaults.market_fee_display_on_top` | boolean | |
| `items[].defaults.withdrawal_plan` | integer | |
| `items[].defaults.withdrawal_date` | integer | |
| `items[].technical` | object | |
| `items[].technical.callback_url` | string | |
| `items[].technical.return_url` | string | |
| `items[].technical.dashboard_url` | string | |
```json
{
"status_code": 0,
"page": 1,
"items_per_page": 1,
"items_total": 1,
"items": [
{
"display_name": "YYY",
"description": null,
"created_at": "2023-08-28 12:02:31",
"activity_type": "One Off",
"main_seller_payme_id": "MPL00012-00012EXM-EXAMPLE0-EXAMPLE2",
"defaults": {
"timezone": null,
"default_creation_plan": "VPLN1580-718683JV-G2PZHZQW-END7P7WI",
"allow_foreign_cards": true,
"currencies": [
"ILS"
],
"processing_limit": 5000000,
"market_fee_display_on_top": false,
"withdrawal_plan": 3,
"withdrawal_date": 1
},
"technical": {
"callback_url": "",
"return_url": "",
"dashboard_url": "https://yyy.payme.io"
}
}
]
}
```
- [GET Mids](https://docs-staging.payme.io/payments/merchants-management/get-sellers-mpl-key-mids): GET /sellers/{mpl_key}/mids — GET Mids
# GET Mids
- Sandbox: `GET https://sandbox.payme.io/api/sellers/{mpl_key}/mids`
- Production: `GET https://live.payme.io/api/sellers/{mpl_key}/mids`
## Credentials
- Header `PayMe-Partner-Key` (API key) and Header `PayMe-Merchant-Key` (API key) and Header `PayMe-Signature` (API key)
Curl Command (Copy to postman command line):
```
curl --location 'https://env.payme.io/api/sellers/MPL90010-90010EXM-EXAMPLE0-EXAMPLE9/mids' \
--header 'PayMe-Partner-Key: isracard-***********' \
--header 'PayMe-Merchant-Key: MPL90099-90099EXM-********-********' \
--header 'PayMe-Signature: sk_test_'
```
## Parameters
| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `mpl_key` | path | string | yes | |
| `PayMe-Partner-Key` | header | string | yes | Your partner client key |
| `PayMe-Merchant-Key` | header | string | yes | Your merchant key (MPL) |
| `PayMe-Signature` | header | string | yes | The signature value PayMe gives you for this endpoint |
## Request body
Content type: `application/json`
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `status_code` | integer | no | |
| `page` | integer | no | |
| `items_total` | integer | no | |
| `items_per_page` | integer | no | |
| `items` | array | no | |
| `items[].guid` | string | no | |
| `items[].classification` | string | no | |
| `items[].type` | string | no | |
| `items[].is_paid_directly` | boolean | no | |
| `items[].acquirer` | string | no | |
| `items[].discounter` | string | no | |
| `items[].allowed_payment_methods` | array | no | |
| `items[].max_installments` | integer | no | |
| `items[].allowed_brands` | array | no | |
| `items[].min_processing` | integer | no | |
| `items[].max_processing` | integer | no | |
| `items[].is_active` | boolean | no | |
| `items[].is_relation_active` | boolean | no | |
### Request example
```json
{
"status_code": 0,
"page": 1,
"items_total": 16,
"items_per_page": 16,
"items": [
{
"guid": "MID16925-12688EFB-LYQNLFYC-EPL65KAW",
"classification": "Original",
"type": "Processing",
"is_paid_directly": false,
"acquirer": "Isracard",
"discounter": "Isracard",
"allowed_payment_methods": [
"credit-card",
"bit"
],
"max_installments": 12,
"allowed_brands": [
"PrivateLabel",
"JCB",
"AmericanExpress",
"Visa",
"Mastercard",
"Isracard"
],
"min_processing": 1,
"max_processing": 50000,
"is_active": false,
"is_relation_active": false
},
{
"guid": "MID16925-12737PDV-GUCYB07Z-8ATPZRLN",
"classification": "Original",
"type": "Processing",
"is_paid_directly": false,
"acquirer": "Isracard",
"discounter": "PayMe",
"allowed_payment_methods": [
"credit-card",
"bit"
],
"max_installments": 12,
"allowed_brands": [
"PrivateLabel",
"JCB",
"AmericanExpress",
"Visa",
"Mastercard",
"Isracard"
],
"min_processing": 1,
"max_processing": 5,
"is_active": true,
"is_relation_active": false
},
{
"guid": "MID16925-12671ODU-Q5XPUVIU-GFCBIEXG",
"classification": "Original",
"type": "Processing",
"is_paid_directly": false,
"acquirer": "Isracard",
"discounter": "PayMe",
"allowed_payment_methods": [
"credit-card",
"bit",
"pos",
"il-direct-debit"
],
"max_installments": 36,
"allowed_brands": [
"PrivateLabel",
"AmericanExpress",
"Visa",
"Mastercard",
"Isracard"
],
"min_processing": 0.1,
"max_processing": 300000,
"is_active": true,
"is_relation_active": false
},
{
"guid": "MID16925-12766V5P-JRK34MPH-HTV3OIKJ",
"classification": "Original",
"type": "None",
"is_paid_directly": true,
"acquirer": "Isracard",
"discounter": null,
"allowed_payment_methods": [
"credit-card",
"bit"
],
"max_installments": 12,
"allowed_brands": [
"PrivateLabel",
"JCB",
"AmericanExpress",
"Visa",
"Mastercard",
"Isracard"
],
"min_processing": 0,
"max_processing": 0,
"is_active": true,
"is_relation_active": false
},
{
"guid": "MID16925-12771UVB-WY2LD0TL-UIN5KKWZ",
"classification": "Shadow",
"type": "Processing",
"is_paid_directly": false,
"acquirer": "Isracard",
"discounter": "Tzameret",
"allowed_payment_methods": [
"credit-card",
"bit"
],
"max_installments": 12,
"allowed_brands": [
"PrivateLabel",
"JCB",
"AmericanExpress",
"Visa",
"Mastercard",
"Isracard"
],
"min_processing": 1,
"max_processing": 5,
"is_active": true,
"is_relation_active": false
},
{
"guid": "MID16925-12790Q47-VJRQBUI8-9YDY2TXM",
"classification": "Original",
"type": "None",
"is_paid_directly": true,
"acquirer": "Isracard",
"discounter": null,
"allowed_payment_methods": [
"credit-card",
"bit"
],
"max_installments": 12,
"allowed_brands": [],
"min_processing": 0,
"max_processing": 0,
"is_active": true,
"is_relation_active": false
},
{
"guid": "MID16925-12693JTW-LJIU7PA0-JBPI9BLW",
"classification": "Original",
"type": "Processing",
"is_paid_directly": false,
"acquirer": "Isracard",
"discounter": "PayMe",
"allowed_payment_methods": [
"credit-card",
"bit"
],
"max_installments": 12,
"allowed_brands": [
"PrivateLabel",
"JCB",
"AmericanExpress",
"Visa",
"Mastercard",
"Isracard"
],
"min_processing": 1,
"max_processing": 50000,
"is_active": true,
"is_relation_active": false
},
{
"guid": "MID16925-12954TZC-FC8KXQC7-YWJHSUKM",
"classification": "Original",
"type": "Processing",
"is_paid_directly": false,
"acquirer": "Isracard",
"discounter": "PayMe",
"allowed_payment_methods": [
"credit-card",
"bit",
"apple-pay",
"pos"
],
"max_installments": 12,
"allowed_brands": [
"PrivateLabel",
"JCB",
"AmericanExpress",
"Visa",
"Mastercard",
"Isracard"
],
"min_processing": 1,
"max_processing": 50000,
"is_active": true,
"is_relation_active": true
},
{
"guid": "MID16925-1268967W-XGOTTDQ0-PENRUMM1",
"classification": "Original",
"type": "Processing",
"is_paid_directly": false,
"acquirer": "Cal",
"discounter": "PayMe",
"allowed_payment_methods": [
"credit-card",
"bit",
"pos"
],
"max_installments": 36,
"allowed_brands": [
"PrivateLabel",
"Diners",
"Visa",
"Mastercard",
"Discover",
"Isracard"
],
"min_processing": 1,
"max_processing": 50000,
"is_active": true,
"is_relation_active": true
},
{
"guid": "MID16925-12807BVI-JFKNE4H1-EKSZTLV7",
"classification": "Original",
"type": "None",
"is_paid_directly": true,
"acquirer": "PayPal",
"discounter": null,
"allowed_payment_methods": [
"paypal"
],
"max_installments": 12,
"allowed_brands": [],
"min_processing": 0,
"max_processing": 0,
"is_active": true,
"is_relation_active": true
},
{
"guid": "MID16925-12862HFU-LGWZBGBC-LDL9VGYC",
"classification": "Original",
"type": "None",
"is_paid_directly": true,
"acquirer": "PayPal",
"discounter": null,
"allowed_payment_methods": [
"paypal"
],
"max_installments": 12,
"allowed_brands": [
"PrivateLabel",
"Diners",
"JCB",
"AmericanExpress",
"Visa",
"Mastercard",
"Discover",
"UnionPay",
"Isracard"
],
"min_processing": 0,
"max_processing": 0,
"is_active": true,
"is_relation_active": false
},
{
"guid": "MID16925-13002M1Z-FH67BK2Q-HHPKCXAL",
"classification": "Original",
"type": "Processing",
"is_paid_directly": false,
"acquirer": "Cal",
"discounter": "PayMe",
"allowed_payment_methods": [
"credit-card",
"bit"
],
"max_installments": 12,
"allowed_brands": [
"PrivateLabel",
"Diners",
"Visa",
"Mastercard",
"Discover",
"Isracard"
],
"min_processing": 5,
"max_processing": 50000,
"is_active": false,
"is_relation_active": false
},
{
"guid": "MID16925-13017KT2-TMCZZ1DB-D05SI93Y",
"classification": "Original",
"type": "None",
"is_paid_directly": true,
"acquirer": "Max",
"discounter": null,
"allowed_payment_methods": [
"credit-card",
"bit"
],
"max_installments": 12,
"allowed_brands": [
"Visa"
],
"min_processing": 0,
"max_processing": 0,
"is_active": true,
"is_relation_active": false
},
{
"guid": "MID16925-12674IGG-CMNOTGUP-E1XQQ8H8",
"classification": "Original",
"type": "Processing",
"is_paid_directly": false,
"acquirer": "Isracard",
"discounter": "PayMe",
"allowed_payment_methods": [
"credit-card",
"bit",
"apple-pay"
],
"max_installments": 12,
"allowed_brands": [
"PrivateLabel",
"JCB",
"AmericanExpress",
"Visa",
"Mastercard",
"Isracard"
],
"min_processing": 1,
"max_processing": 50000,
"is_active": true,
"is_relation_active": false
},
{
"guid": "MID16925-13050DDN-0NIDIVSH-MBBYBTGV",
"classification": "Original",
"type": "Processing",
"is_paid_directly": true,
"acquirer": "Payrix",
"discounter": null,
"allowed_payment_methods": [
"credit-card",
"echeck",
"apple-pay"
],
"max_installments": 0,
"allowed_brands": [
"PrivateLabel",
"Diners",
"JCB",
"AmericanExpress",
"Visa",
"Mastercard",
"Discover",
"UnionPay",
"Isracard"
],
"min_processing": 1,
"max_processing": 21474836.47,
"is_active": true,
"is_relation_active": false
},
{
"guid": "MID16925-13053CLI-ZG3TBVJC-56WVDNPS",
"classification": "Original",
"type": "Processing",
"is_paid_directly": true,
"acquirer": "Stripe",
"discounter": null,
"allowed_payment_methods": [
"credit-card"
],
"max_installments": 0,
"allowed_brands": [
"PrivateLabel",
"Diners",
"JCB",
"AmericanExpress",
"Visa",
"Mastercard",
"Discover",
"UnionPay",
"Isracard"
],
"min_processing": 1,
"max_processing": 200000,
"is_active": true,
"is_relation_active": false
}
]
}
```
## Code samples
### curl
```bash
curl -X GET 'https://sandbox.payme.io/api/sellers//mids' \
-H 'Content-Type: application/json' \
-H 'PayMe-Partner-Key: ' \
-H 'PayMe-Merchant-Key: ' \
-H 'PayMe-Signature: ' \
--data-raw '{
"status_code": 0,
"page": 1,
"items_total": 16,
"items_per_page": 16,
"items": [
{
"guid": "MID16925-12688EFB-LYQNLFYC-EPL65KAW",
"classification": "Original",
"type": "Processing",
"is_paid_directly": false,
"acquirer": "Isracard",
"discounter": "Isracard",
"allowed_payment_methods": [
"credit-card",
"bit"
],
"max_installments": 12,
"allowed_brands": [
"PrivateLabel",
"JCB",
"AmericanExpress",
"Visa",
"Mastercard",
"Isracard"
],
"min_processing": 1,
"max_processing": 50000,
"is_active": false,
"is_relation_active": false
},
{
"guid": "MID16925-12737PDV-GUCYB07Z-8ATPZRLN",
"classification": "Original",
"type": "Processing",
"is_paid_directly": false,
"acquirer": "Isracard",
"discounter": "PayMe",
"allowed_payment_methods": [
"credit-card",
"bit"
],
"max_installments": 12,
"allowed_brands": [
"PrivateLabel",
"JCB",
"AmericanExpress",
"Visa",
"Mastercard",
"Isracard"
],
"min_processing": 1,
"max_processing": 5,
"is_active": true,
"is_relation_active": false
},
{
"guid": "MID16925-12671ODU-Q5XPUVIU-GFCBIEXG",
"classification": "Original",
"type": "Processing",
"is_paid_directly": false,
"acquirer": "Isracard",
"discounter": "PayMe",
"allowed_payment_methods": [
"credit-card",
"bit",
"pos",
"il-direct-debit"
],
"max_installments": 36,
"allowed_brands": [
"PrivateLabel",
"AmericanExpress",
"Visa",
"Mastercard",
"Isracard"
],
"min_processing": 0.1,
"max_processing": 300000,
"is_active": true,
"is_relation_active": false
},
{
"guid": "MID16925-12766V5P-JRK34MPH-HTV3OIKJ",
"classification": "Original",
"type": "None",
"is_paid_directly": true,
"acquirer": "Isracard",
"discounter": null,
"allowed_payment_methods": [
"credit-card",
"bit"
],
"max_installments": 12,
"allowed_brands": [
"PrivateLabel",
"JCB",
"AmericanExpress",
"Visa",
"Mastercard",
"Isracard"
],
"min_processing": 0,
"max_processing": 0,
"is_active": true,
"is_relation_active": false
},
{
"guid": "MID16925-12771UVB-WY2LD0TL-UIN5KKWZ",
"classification": "Shadow",
"type": "Processing",
"is_paid_directly": false,
"acquirer": "Isracard",
"discounter": "Tzameret",
"allowed_payment_methods": [
"credit-card",
"bit"
],
"max_installments": 12,
"allowed_brands": [
"PrivateLabel",
"JCB",
"AmericanExpress",
"Visa",
"Mastercard",
"Isracard"
],
"min_processing": 1,
"max_processing": 5,
"is_active": true,
"is_relation_active": false
},
{
"guid": "MID16925-12790Q47-VJRQBUI8-9YDY2TXM",
"classification": "Original",
"type": "None",
"is_paid_directly": true,
"acquirer": "Isracard",
"discounter": null,
"allowed_payment_methods": [
"credit-card",
"bit"
],
"max_installments": 12,
"allowed_brands": [],
"min_processing": 0,
"max_processing": 0,
"is_active": true,
"is_relation_active": false
},
{
"guid": "MID16925-12693JTW-LJIU7PA0-JBPI9BLW",
"classification": "Original",
"type": "Processing",
"is_paid_directly": false,
"acquirer": "Isracard",
"discounter": "PayMe",
"allowed_payment_methods": [
"credit-card",
"bit"
],
"max_installments": 12,
"allowed_brands": [
"PrivateLabel",
"JCB",
"AmericanExpress",
"Visa",
"Mastercard",
"Isracard"
],
"min_processing": 1,
"max_processing": 50000,
"is_active": true,
"is_relation_active": false
},
{
"guid": "MID16925-12954TZC-FC8KXQC7-YWJHSUKM",
"classification": "Original",
"type": "Processing",
"is_paid_directly": false,
"acquirer": "Isracard",
"discounter": "PayMe",
"allowed_payment_methods": [
"credit-card",
"bit",
"apple-pay",
"pos"
],
"max_installments": 12,
"allowed_brands": [
"PrivateLabel",
"JCB",
"AmericanExpress",
"Visa",
"Mastercard",
"Isracard"
],
"min_processing": 1,
"max_processing": 50000,
"is_active": true,
"is_relation_active": true
},
{
"guid": "MID16925-1268967W-XGOTTDQ0-PENRUMM1",
"classification": "Original",
"type": "Processing",
"is_paid_directly": false,
"acquirer": "Cal",
"discounter": "PayMe",
"allowed_payment_methods": [
"credit-card",
"bit",
"pos"
],
"max_installments": 36,
"allowed_brands": [
"PrivateLabel",
"Diners",
"Visa",
"Mastercard",
"Discover",
"Isracard"
],
"min_processing": 1,
"max_processing": 50000,
"is_active": true,
"is_relation_active": true
},
{
"guid": "MID16925-12807BVI-JFKNE4H1-EKSZTLV7",
"classification": "Original",
"type": "None",
"is_paid_directly": true,
"acquirer": "PayPal",
"discounter": null,
"allowed_payment_methods": [
"paypal"
],
"max_installments": 12,
"allowed_brands": [],
"min_processing": 0,
"max_processing": 0,
"is_active": true,
"is_relation_active": true
},
{
"guid": "MID16925-12862HFU-LGWZBGBC-LDL9VGYC",
"classification": "Original",
"type": "None",
"is_paid_directly": true,
"acquirer": "PayPal",
"discounter": null,
"allowed_payment_methods": [
"paypal"
],
"max_installments": 12,
"allowed_brands": [
"PrivateLabel",
"Diners",
"JCB",
"AmericanExpress",
"Visa",
"Mastercard",
"Discover",
"UnionPay",
"Isracard"
],
"min_processing": 0,
"max_processing": 0,
"is_active": true,
"is_relation_active": false
},
{
"guid": "MID16925-13002M1Z-FH67BK2Q-HHPKCXAL",
"classification": "Original",
"type": "Processing",
"is_paid_directly": false,
"acquirer": "Cal",
"discounter": "PayMe",
"allowed_payment_methods": [
"credit-card",
"bit"
],
"max_installments": 12,
"allowed_brands": [
"PrivateLabel",
"Diners",
"Visa",
"Mastercard",
"Discover",
"Isracard"
],
"min_processing": 5,
"max_processing": 50000,
"is_active": false,
"is_relation_active": false
},
{
"guid": "MID16925-13017KT2-TMCZZ1DB-D05SI93Y",
"classification": "Original",
"type": "None",
"is_paid_directly": true,
"acquirer": "Max",
"discounter": null,
"allowed_payment_methods": [
"credit-card",
"bit"
],
"max_installments": 12,
"allowed_brands": [
"Visa"
],
"min_processing": 0,
"max_processing": 0,
"is_active": true,
"is_relation_active": false
},
{
"guid": "MID16925-12674IGG-CMNOTGUP-E1XQQ8H8",
"classification": "Original",
"type": "Processing",
"is_paid_directly": false,
"acquirer": "Isracard",
"discounter": "PayMe",
"allowed_payment_methods": [
"credit-card",
"bit",
"apple-pay"
],
"max_installments": 12,
"allowed_brands": [
"PrivateLabel",
"JCB",
"AmericanExpress",
"Visa",
"Mastercard",
"Isracard"
],
"min_processing": 1,
"max_processing": 50000,
"is_active": true,
"is_relation_active": false
},
{
"guid": "MID16925-13050DDN-0NIDIVSH-MBBYBTGV",
"classification": "Original",
"type": "Processing",
"is_paid_directly": true,
"acquirer": "Payrix",
"discounter": null,
"allowed_payment_methods": [
"credit-card",
"echeck",
"apple-pay"
],
"max_installments": 0,
"allowed_brands": [
"PrivateLabel",
"Diners",
"JCB",
"AmericanExpress",
"Visa",
"Mastercard",
"Discover",
"UnionPay",
"Isracard"
],
"min_processing": 1,
"max_processing": 21474836.47,
"is_active": true,
"is_relation_active": false
},
{
"guid": "MID16925-13053CLI-ZG3TBVJC-56WVDNPS",
"classification": "Original",
"type": "Processing",
"is_paid_directly": true,
"acquirer": "Stripe",
"discounter": null,
"allowed_payment_methods": [
"credit-card"
],
"max_installments": 0,
"allowed_brands": [
"PrivateLabel",
"Diners",
"JCB",
"AmericanExpress",
"Visa",
"Mastercard",
"Discover",
"UnionPay",
"Isracard"
],
"min_processing": 1,
"max_processing": 200000,
"is_active": true,
"is_relation_active": false
}
]
}'
```
### Node.js
```javascript
const response = await fetch("https://sandbox.payme.io/api/sellers//mids", {
method: "GET",
headers: {
"Content-Type": "application/json",
"PayMe-Partner-Key": "",
"PayMe-Merchant-Key": "",
"PayMe-Signature": "",
},
body: JSON.stringify({
"status_code": 0,
"page": 1,
"items_total": 16,
"items_per_page": 16,
"items": [
{
"guid": "MID16925-12688EFB-LYQNLFYC-EPL65KAW",
"classification": "Original",
"type": "Processing",
"is_paid_directly": false,
"acquirer": "Isracard",
"discounter": "Isracard",
"allowed_payment_methods": [
"credit-card",
"bit"
],
"max_installments": 12,
"allowed_brands": [
"PrivateLabel",
"JCB",
"AmericanExpress",
"Visa",
"Mastercard",
"Isracard"
],
"min_processing": 1,
"max_processing": 50000,
"is_active": false,
"is_relation_active": false
},
{
"guid": "MID16925-12737PDV-GUCYB07Z-8ATPZRLN",
"classification": "Original",
"type": "Processing",
"is_paid_directly": false,
"acquirer": "Isracard",
"discounter": "PayMe",
"allowed_payment_methods": [
"credit-card",
"bit"
],
"max_installments": 12,
"allowed_brands": [
"PrivateLabel",
"JCB",
"AmericanExpress",
"Visa",
"Mastercard",
"Isracard"
],
"min_processing": 1,
"max_processing": 5,
"is_active": true,
"is_relation_active": false
},
{
"guid": "MID16925-12671ODU-Q5XPUVIU-GFCBIEXG",
"classification": "Original",
"type": "Processing",
"is_paid_directly": false,
"acquirer": "Isracard",
"discounter": "PayMe",
"allowed_payment_methods": [
"credit-card",
"bit",
"pos",
"il-direct-debit"
],
"max_installments": 36,
"allowed_brands": [
"PrivateLabel",
"AmericanExpress",
"Visa",
"Mastercard",
"Isracard"
],
"min_processing": 0.1,
"max_processing": 300000,
"is_active": true,
"is_relation_active": false
},
{
"guid": "MID16925-12766V5P-JRK34MPH-HTV3OIKJ",
"classification": "Original",
"type": "None",
"is_paid_directly": true,
"acquirer": "Isracard",
"discounter": null,
"allowed_payment_methods": [
"credit-card",
"bit"
],
"max_installments": 12,
"allowed_brands": [
"PrivateLabel",
"JCB",
"AmericanExpress",
"Visa",
"Mastercard",
"Isracard"
],
"min_processing": 0,
"max_processing": 0,
"is_active": true,
"is_relation_active": false
},
{
"guid": "MID16925-12771UVB-WY2LD0TL-UIN5KKWZ",
"classification": "Shadow",
"type": "Processing",
"is_paid_directly": false,
"acquirer": "Isracard",
"discounter": "Tzameret",
"allowed_payment_methods": [
"credit-card",
"bit"
],
"max_installments": 12,
"allowed_brands": [
"PrivateLabel",
"JCB",
"AmericanExpress",
"Visa",
"Mastercard",
"Isracard"
],
"min_processing": 1,
"max_processing": 5,
"is_active": true,
"is_relation_active": false
},
{
"guid": "MID16925-12790Q47-VJRQBUI8-9YDY2TXM",
"classification": "Original",
"type": "None",
"is_paid_directly": true,
"acquirer": "Isracard",
"discounter": null,
"allowed_payment_methods": [
"credit-card",
"bit"
],
"max_installments": 12,
"allowed_brands": [],
"min_processing": 0,
"max_processing": 0,
"is_active": true,
"is_relation_active": false
},
{
"guid": "MID16925-12693JTW-LJIU7PA0-JBPI9BLW",
"classification": "Original",
"type": "Processing",
"is_paid_directly": false,
"acquirer": "Isracard",
"discounter": "PayMe",
"allowed_payment_methods": [
"credit-card",
"bit"
],
"max_installments": 12,
"allowed_brands": [
"PrivateLabel",
"JCB",
"AmericanExpress",
"Visa",
"Mastercard",
"Isracard"
],
"min_processing": 1,
"max_processing": 50000,
"is_active": true,
"is_relation_active": false
},
{
"guid": "MID16925-12954TZC-FC8KXQC7-YWJHSUKM",
"classification": "Original",
"type": "Processing",
"is_paid_directly": false,
"acquirer": "Isracard",
"discounter": "PayMe",
"allowed_payment_methods": [
"credit-card",
"bit",
"apple-pay",
"pos"
],
"max_installments": 12,
"allowed_brands": [
"PrivateLabel",
"JCB",
"AmericanExpress",
"Visa",
"Mastercard",
"Isracard"
],
"min_processing": 1,
"max_processing": 50000,
"is_active": true,
"is_relation_active": true
},
{
"guid": "MID16925-1268967W-XGOTTDQ0-PENRUMM1",
"classification": "Original",
"type": "Processing",
"is_paid_directly": false,
"acquirer": "Cal",
"discounter": "PayMe",
"allowed_payment_methods": [
"credit-card",
"bit",
"pos"
],
"max_installments": 36,
"allowed_brands": [
"PrivateLabel",
"Diners",
"Visa",
"Mastercard",
"Discover",
"Isracard"
],
"min_processing": 1,
"max_processing": 50000,
"is_active": true,
"is_relation_active": true
},
{
"guid": "MID16925-12807BVI-JFKNE4H1-EKSZTLV7",
"classification": "Original",
"type": "None",
"is_paid_directly": true,
"acquirer": "PayPal",
"discounter": null,
"allowed_payment_methods": [
"paypal"
],
"max_installments": 12,
"allowed_brands": [],
"min_processing": 0,
"max_processing": 0,
"is_active": true,
"is_relation_active": true
},
{
"guid": "MID16925-12862HFU-LGWZBGBC-LDL9VGYC",
"classification": "Original",
"type": "None",
"is_paid_directly": true,
"acquirer": "PayPal",
"discounter": null,
"allowed_payment_methods": [
"paypal"
],
"max_installments": 12,
"allowed_brands": [
"PrivateLabel",
"Diners",
"JCB",
"AmericanExpress",
"Visa",
"Mastercard",
"Discover",
"UnionPay",
"Isracard"
],
"min_processing": 0,
"max_processing": 0,
"is_active": true,
"is_relation_active": false
},
{
"guid": "MID16925-13002M1Z-FH67BK2Q-HHPKCXAL",
"classification": "Original",
"type": "Processing",
"is_paid_directly": false,
"acquirer": "Cal",
"discounter": "PayMe",
"allowed_payment_methods": [
"credit-card",
"bit"
],
"max_installments": 12,
"allowed_brands": [
"PrivateLabel",
"Diners",
"Visa",
"Mastercard",
"Discover",
"Isracard"
],
"min_processing": 5,
"max_processing": 50000,
"is_active": false,
"is_relation_active": false
},
{
"guid": "MID16925-13017KT2-TMCZZ1DB-D05SI93Y",
"classification": "Original",
"type": "None",
"is_paid_directly": true,
"acquirer": "Max",
"discounter": null,
"allowed_payment_methods": [
"credit-card",
"bit"
],
"max_installments": 12,
"allowed_brands": [
"Visa"
],
"min_processing": 0,
"max_processing": 0,
"is_active": true,
"is_relation_active": false
},
{
"guid": "MID16925-12674IGG-CMNOTGUP-E1XQQ8H8",
"classification": "Original",
"type": "Processing",
"is_paid_directly": false,
"acquirer": "Isracard",
"discounter": "PayMe",
"allowed_payment_methods": [
"credit-card",
"bit",
"apple-pay"
],
"max_installments": 12,
"allowed_brands": [
"PrivateLabel",
"JCB",
"AmericanExpress",
"Visa",
"Mastercard",
"Isracard"
],
"min_processing": 1,
"max_processing": 50000,
"is_active": true,
"is_relation_active": false
},
{
"guid": "MID16925-13050DDN-0NIDIVSH-MBBYBTGV",
"classification": "Original",
"type": "Processing",
"is_paid_directly": true,
"acquirer": "Payrix",
"discounter": null,
"allowed_payment_methods": [
"credit-card",
"echeck",
"apple-pay"
],
"max_installments": 0,
"allowed_brands": [
"PrivateLabel",
"Diners",
"JCB",
"AmericanExpress",
"Visa",
"Mastercard",
"Discover",
"UnionPay",
"Isracard"
],
"min_processing": 1,
"max_processing": 21474836.47,
"is_active": true,
"is_relation_active": false
},
{
"guid": "MID16925-13053CLI-ZG3TBVJC-56WVDNPS",
"classification": "Original",
"type": "Processing",
"is_paid_directly": true,
"acquirer": "Stripe",
"discounter": null,
"allowed_payment_methods": [
"credit-card"
],
"max_installments": 0,
"allowed_brands": [
"PrivateLabel",
"Diners",
"JCB",
"AmericanExpress",
"Visa",
"Mastercard",
"Discover",
"UnionPay",
"Isracard"
],
"min_processing": 1,
"max_processing": 200000,
"is_active": true,
"is_relation_active": false
}
]
}),
});
console.log(await response.text());
```
### Python
```python
import requests
response = requests.get(
"https://sandbox.payme.io/api/sellers//mids",
headers={
"PayMe-Partner-Key": "",
"PayMe-Merchant-Key": "",
"PayMe-Signature": "",
},
json={
"status_code": 0,
"page": 1,
"items_total": 16,
"items_per_page": 16,
"items": [
{
"guid": "MID16925-12688EFB-LYQNLFYC-EPL65KAW",
"classification": "Original",
"type": "Processing",
"is_paid_directly": False,
"acquirer": "Isracard",
"discounter": "Isracard",
"allowed_payment_methods": [
"credit-card",
"bit",
],
"max_installments": 12,
"allowed_brands": [
"PrivateLabel",
"JCB",
"AmericanExpress",
"Visa",
"Mastercard",
"Isracard",
],
"min_processing": 1,
"max_processing": 50000,
"is_active": False,
"is_relation_active": False,
},
{
"guid": "MID16925-12737PDV-GUCYB07Z-8ATPZRLN",
"classification": "Original",
"type": "Processing",
"is_paid_directly": False,
"acquirer": "Isracard",
"discounter": "PayMe",
"allowed_payment_methods": [
"credit-card",
"bit",
],
"max_installments": 12,
"allowed_brands": [
"PrivateLabel",
"JCB",
"AmericanExpress",
"Visa",
"Mastercard",
"Isracard",
],
"min_processing": 1,
"max_processing": 5,
"is_active": True,
"is_relation_active": False,
},
{
"guid": "MID16925-12671ODU-Q5XPUVIU-GFCBIEXG",
"classification": "Original",
"type": "Processing",
"is_paid_directly": False,
"acquirer": "Isracard",
"discounter": "PayMe",
"allowed_payment_methods": [
"credit-card",
"bit",
"pos",
"il-direct-debit",
],
"max_installments": 36,
"allowed_brands": [
"PrivateLabel",
"AmericanExpress",
"Visa",
"Mastercard",
"Isracard",
],
"min_processing": 0.1,
"max_processing": 300000,
"is_active": True,
"is_relation_active": False,
},
{
"guid": "MID16925-12766V5P-JRK34MPH-HTV3OIKJ",
"classification": "Original",
"type": "None",
"is_paid_directly": True,
"acquirer": "Isracard",
"discounter": None,
"allowed_payment_methods": [
"credit-card",
"bit",
],
"max_installments": 12,
"allowed_brands": [
"PrivateLabel",
"JCB",
"AmericanExpress",
"Visa",
"Mastercard",
"Isracard",
],
"min_processing": 0,
"max_processing": 0,
"is_active": True,
"is_relation_active": False,
},
{
"guid": "MID16925-12771UVB-WY2LD0TL-UIN5KKWZ",
"classification": "Shadow",
"type": "Processing",
"is_paid_directly": False,
"acquirer": "Isracard",
"discounter": "Tzameret",
"allowed_payment_methods": [
"credit-card",
"bit",
],
"max_installments": 12,
"allowed_brands": [
"PrivateLabel",
"JCB",
"AmericanExpress",
"Visa",
"Mastercard",
"Isracard",
],
"min_processing": 1,
"max_processing": 5,
"is_active": True,
"is_relation_active": False,
},
{
"guid": "MID16925-12790Q47-VJRQBUI8-9YDY2TXM",
"classification": "Original",
"type": "None",
"is_paid_directly": True,
"acquirer": "Isracard",
"discounter": None,
"allowed_payment_methods": [
"credit-card",
"bit",
],
"max_installments": 12,
"allowed_brands": [],
"min_processing": 0,
"max_processing": 0,
"is_active": True,
"is_relation_active": False,
},
{
"guid": "MID16925-12693JTW-LJIU7PA0-JBPI9BLW",
"classification": "Original",
"type": "Processing",
"is_paid_directly": False,
"acquirer": "Isracard",
"discounter": "PayMe",
"allowed_payment_methods": [
"credit-card",
"bit",
],
"max_installments": 12,
"allowed_brands": [
"PrivateLabel",
"JCB",
"AmericanExpress",
"Visa",
"Mastercard",
"Isracard",
],
"min_processing": 1,
"max_processing": 50000,
"is_active": True,
"is_relation_active": False,
},
{
"guid": "MID16925-12954TZC-FC8KXQC7-YWJHSUKM",
"classification": "Original",
"type": "Processing",
"is_paid_directly": False,
"acquirer": "Isracard",
"discounter": "PayMe",
"allowed_payment_methods": [
"credit-card",
"bit",
"apple-pay",
"pos",
],
"max_installments": 12,
"allowed_brands": [
"PrivateLabel",
"JCB",
"AmericanExpress",
"Visa",
"Mastercard",
"Isracard",
],
"min_processing": 1,
"max_processing": 50000,
"is_active": True,
"is_relation_active": True,
},
{
"guid": "MID16925-1268967W-XGOTTDQ0-PENRUMM1",
"classification": "Original",
"type": "Processing",
"is_paid_directly": False,
"acquirer": "Cal",
"discounter": "PayMe",
"allowed_payment_methods": [
"credit-card",
"bit",
"pos",
],
"max_installments": 36,
"allowed_brands": [
"PrivateLabel",
"Diners",
"Visa",
"Mastercard",
"Discover",
"Isracard",
],
"min_processing": 1,
"max_processing": 50000,
"is_active": True,
"is_relation_active": True,
},
{
"guid": "MID16925-12807BVI-JFKNE4H1-EKSZTLV7",
"classification": "Original",
"type": "None",
"is_paid_directly": True,
"acquirer": "PayPal",
"discounter": None,
"allowed_payment_methods": [
"paypal",
],
"max_installments": 12,
"allowed_brands": [],
"min_processing": 0,
"max_processing": 0,
"is_active": True,
"is_relation_active": True,
},
{
"guid": "MID16925-12862HFU-LGWZBGBC-LDL9VGYC",
"classification": "Original",
"type": "None",
"is_paid_directly": True,
"acquirer": "PayPal",
"discounter": None,
"allowed_payment_methods": [
"paypal",
],
"max_installments": 12,
"allowed_brands": [
"PrivateLabel",
"Diners",
"JCB",
"AmericanExpress",
"Visa",
"Mastercard",
"Discover",
"UnionPay",
"Isracard",
],
"min_processing": 0,
"max_processing": 0,
"is_active": True,
"is_relation_active": False,
},
{
"guid": "MID16925-13002M1Z-FH67BK2Q-HHPKCXAL",
"classification": "Original",
"type": "Processing",
"is_paid_directly": False,
"acquirer": "Cal",
"discounter": "PayMe",
"allowed_payment_methods": [
"credit-card",
"bit",
],
"max_installments": 12,
"allowed_brands": [
"PrivateLabel",
"Diners",
"Visa",
"Mastercard",
"Discover",
"Isracard",
],
"min_processing": 5,
"max_processing": 50000,
"is_active": False,
"is_relation_active": False,
},
{
"guid": "MID16925-13017KT2-TMCZZ1DB-D05SI93Y",
"classification": "Original",
"type": "None",
"is_paid_directly": True,
"acquirer": "Max",
"discounter": None,
"allowed_payment_methods": [
"credit-card",
"bit",
],
"max_installments": 12,
"allowed_brands": [
"Visa",
],
"min_processing": 0,
"max_processing": 0,
"is_active": True,
"is_relation_active": False,
},
{
"guid": "MID16925-12674IGG-CMNOTGUP-E1XQQ8H8",
"classification": "Original",
"type": "Processing",
"is_paid_directly": False,
"acquirer": "Isracard",
"discounter": "PayMe",
"allowed_payment_methods": [
"credit-card",
"bit",
"apple-pay",
],
"max_installments": 12,
"allowed_brands": [
"PrivateLabel",
"JCB",
"AmericanExpress",
"Visa",
"Mastercard",
"Isracard",
],
"min_processing": 1,
"max_processing": 50000,
"is_active": True,
"is_relation_active": False,
},
{
"guid": "MID16925-13050DDN-0NIDIVSH-MBBYBTGV",
"classification": "Original",
"type": "Processing",
"is_paid_directly": True,
"acquirer": "Payrix",
"discounter": None,
"allowed_payment_methods": [
"credit-card",
"echeck",
"apple-pay",
],
"max_installments": 0,
"allowed_brands": [
"PrivateLabel",
"Diners",
"JCB",
"AmericanExpress",
"Visa",
"Mastercard",
"Discover",
"UnionPay",
"Isracard",
],
"min_processing": 1,
"max_processing": 21474836.47,
"is_active": True,
"is_relation_active": False,
},
{
"guid": "MID16925-13053CLI-ZG3TBVJC-56WVDNPS",
"classification": "Original",
"type": "Processing",
"is_paid_directly": True,
"acquirer": "Stripe",
"discounter": None,
"allowed_payment_methods": [
"credit-card",
],
"max_installments": 0,
"allowed_brands": [
"PrivateLabel",
"Diners",
"JCB",
"AmericanExpress",
"Visa",
"Mastercard",
"Discover",
"UnionPay",
"Isracard",
],
"min_processing": 1,
"max_processing": 200000,
"is_active": True,
"is_relation_active": False,
},
],
},
)
print(response.text)
```
### PHP
```php
/mids');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Content-Type: application/json',
'PayMe-Partner-Key: ',
'PayMe-Merchant-Key: ',
'PayMe-Signature: ',
],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;
```
## Responses
### 200 — OK (success)
- [Business Fields](https://docs-staging.payme.io/payments/merchants-management/get-business-fields): GET /business-fields — Business Fields
# Business Fields
- Sandbox: `GET https://sandbox.payme.io/api/business-fields`
- Production: `GET https://live.payme.io/api/business-fields`
## Credentials
- Header `PayMe-Partner-Key` (API key)
- Query parameter `seller_payme_id` (optional): Your seller ID (MPL), as an alternative to PayMe-Partner-Key.
## Overview
Returns the list of business fields (the seller's line of business), for example when creating a seller. Each field has a numeric `code`, an international (English) name and a local name.
To get a single field, add its code to the path: `GET /business-fields/{code}`.
## Authentication
Send your own partner key (`payme_client_key`) in the `PayMe-Partner-Key` header. A seller can send its `seller_payme_id` instead. Without either, the call fails with error `1` (`status_additional_info`: `payme_client_key`).
## Response structure
- `status_code`: `0` on success.
- `page`, `items_per_page`, `items_total`: paging information.
- `language`: the language of `name_local`.
- `items`: the business fields, keyed by position; each has `code`, `name_intl` and `name_local`.
## Parameters
| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `PayMe-Partner-Key` | header | string | no | Your partner key (payme_client_key). Required unless you send seller_payme_id. |
| `seller_payme_id` | query | string | no | Your seller ID (MPL), as an alternative to PayMe-Partner-Key. |
| `sort_by` | query | string | no | Field to sort by, for example name_local. Default code. |
| `sort_direction` | query | string | no | desc for descending; any other value sorts ascending. |
| `language` | query | string | no | Language of name_local (he, en, es, ru or ar). Default Hebrew. |
| `allow_children` | query | boolean | no | Also return child business fields. |
## Code samples
### curl
```bash
curl -X GET 'https://sandbox.payme.io/api/business-fields?seller_payme_id=' \
-H 'PayMe-Partner-Key: '
```
### Node.js
```javascript
const response = await fetch("https://sandbox.payme.io/api/business-fields?seller_payme_id=", {
method: "GET",
headers: {
"PayMe-Partner-Key": "",
},
});
console.log(await response.text());
```
### Python
```python
import requests
response = requests.get(
"https://sandbox.payme.io/api/business-fields?seller_payme_id=",
headers={
"PayMe-Partner-Key": "",
},
)
print(response.text)
```
### PHP
```php
');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'PayMe-Partner-Key: ',
],
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;
```
## Responses
### default — Default (error)
| Field | Type | Description |
| --- | --- | --- |
| `status_code` | integer | |
| `page` | integer | |
| `items_per_page` | integer | |
| `items_total` | integer | |
| `language` | string | |
| `items` | object | |
| `items.244` | object | |
| `items.244.code` | integer | |
| `items.244.name_intl` | string | |
| `items.244.name_local` | string | |
```json
{
"status_code": 0,
"page": 1,
"items_per_page": 245,
"items_total": 245,
"language": "he",
"items": {
"244": {
"code": 10565,
"name_intl": "Shutters",
"name_local": "תריסים"
}
}
}
```
## Buyers Management
- [Get Customer Details](https://docs-staging.payme.io/payments/buyers-management/get-buyers-guid): GET /buyers/{buyer_guid} — Get Customer Details
# Get Customer Details
- Sandbox: `GET https://sandbox.payme.io/api/buyers/{buyer_guid}`
- Production: `GET https://live.payme.io/api/buyers/{buyer_guid}`
## Credentials
- Header `PayMe-Merchant-Key` (API key)
## Overview
You can access and fetch your buyer's details using this API endpoint.
Your API request structure should look as follows:
```
https://.payme.io/api/buyers/{buyer_guid}
```
The buyer guid is the unique ID fetched from either:
1. Capture Buyer Token API endpoint.
2. Tokens API endpoint.
### Authentication
You'll need to authenticate your request using the unique seller ID.
### Data
You'll be able to get the following data:
1. Card mask
2. Card brand
3. Card expiry date
4. Customer details
### Limitations
1. If you are sending a token (uuid) and not a buyer key you won't get the parameter `buyer_key` in your response.
## Parameters
| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `PayMe-Merchant-Key` | header | string | yes | Your unique seller UUID. |
| `buyer_guid` | path | string | yes | |
## Code samples
### curl
```bash
curl -X GET 'https://sandbox.payme.io/api/buyers/' \
-H 'PayMe-Merchant-Key: '
```
### Node.js
```javascript
const response = await fetch("https://sandbox.payme.io/api/buyers/", {
method: "GET",
headers: {
"PayMe-Merchant-Key": "",
},
});
console.log(await response.text());
```
### Python
```python
import requests
response = requests.get(
"https://sandbox.payme.io/api/buyers/",
headers={
"PayMe-Merchant-Key": "",
},
)
print(response.text)
```
### PHP
```php
');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'PayMe-Merchant-Key: ',
],
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;
```
## Responses
### 200 — OK (success)
| Field | Type | Description |
| --- | --- | --- |
| `uuid` | string | Buyer uuid |
| `customer` | object | Customer's details |
| `customer.name` | string | Customer's name |
| `customer.email` | string | Customer's email |
| `customer.phone` | string | Customer's phone |
| `customer.social_id` | string | Customer's ID |
| `payment` | object | |
| `payment.display` | string | The payment method number |
| `payment.expiry` | string | Buyer's card exp (MMYY). |
| `payment.brand` | string | Buyer's card brand. |
| `payment.club` | string | The credit card club |
| `payment.type` | string | Type of credit card |
| `payment.organization` | string | The credit card organization |
| `payment.origin_country` | string | The credit card country |
| `buyer_key` | string | Buyer key |
```json
{
"uuid": "6ac45306-1755-45e4-8b74-f6de3ea2239b",
"customer": {
"name": "Ran Tester",
"email": "TestTest@paymeservice.com",
"phone": "05222222",
"social_id": "123456789"
},
"payment": {
"display": "411111******1111",
"expiry": "0322",
"brand": "Visa",
"club": "",
"type": "Credit",
"organization": "",
"origin_country": "US"
},
"buyer_key": "BUYER162-6264904Y-TIHEKYED-4QMCI837"
}
```
## Generate a Sale with 3D Secure
- [Generate Sale with 3D Secure](https://docs-staging.payme.io/payments/generate-a-sale-with-3d-secure/post-generate-sale-generate-a-sale-with-3d-secure): How to call POST /generate-sale for Generate a Sale with 3D Secure.
# Generate Sale with 3D Secure
This is a variant of [POST /generate-sale — Generate Payment](https://docs-staging.payme.io/payments/hosted-payment-page/post-generate-sale); the request and responses below are the ones documented for Generate a Sale with 3D Secure.
- Sandbox: `POST https://sandbox.payme.io/api/generate-sale`
- Production: `POST https://live.payme.io/api/generate-sale`
## Credentials
- Request body field `seller_payme_id` (required): Our unique seller ID
## Overview
In order to process sales with the 3D secure activated, please follow the next steps:
1. Make sure the service is enabeled for your partner account on PayMe's system.
2. Use [`generate-sale`](https://docs-staging.payme.io/payments/direct-api/post-pay-sale) to send the request.
3. If you want to set specific rules for 3D secure initiation process, make sure you reach out to your onboarding manager and have them in place before inititating the transaction.
#### Create a sale with Dynamic 3DS
This option requires signup in advanced to the 3DS service.
As part of `generate-sale` command, you can add the following object to the request:
```json
"services": [
{
"name": "3DSecure",
"settings": {
"active": false
}
}
]
```
## Redirecting When the Authentication Failed
If the user has failed on the authentication step (When a challenge is presented - 6 digit OTP that is sent to the card holder), a redirect will be initiated sending the user to PayMe's Hosted Payment Page for an additional try to input another credit card.
If you would like to avoid such cases and redirect the card-holder back to your own payment page, please include an additional parameter in your sale generating request (`generate-sale`) which is `cancel_url`.
Parameter Name | Type | Example
--|--|--
`cancel_url` | `URL` | `https://payme.io`
## Parameters
This endpoint takes no path, query or header parameters.
## Request body
Content type: `application/json`
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `seller_payme_id` | string | yes | Our unique seller ID |
| `sale_price` | number | yes | Sale final price. For example, if the price is 50.75 (max 2 decimal points) the value that needs to be sent is 5075. Note that the minimum value is 500 |
| `currency` | string | yes | Sale currency. [3-letter ISO 4217 name](https://en.wikipedia.org/wiki/ISO_4217). |
| `product_name` | string | yes | Short name and description of the product/service. This text will be shown in the invoice as well, if the seller has enabled the invoices module in his account panel. Limited to 500 characters |
| `transaction_id` | string | no | Merchant's unique sale ID for correlation with us |
| `installments` | string | yes | Amount of installments for the sale. For additional information see Note 1 below |
| `market_fee` | number | no | A decimal between 0.00 and 60.00 representing the percent of the sale price that is collected for the marketplace (includes VAT). This fee is added on top of our fees and transferred to the marketplace once a month. Default value is the market fee of the Seller, as set upon Seller creation |
| `sale_send_notifcation` | boolean | no | Flag to send email and/or SMS notifications |
| `sale_callback_url` | string | no | Callback response to your page regarding call to our API. Default value is taken from the Merchant's settings. Note that you may not send a "localhost" URL as value |
| `sale_email` | string | no | In case sale send notification is true provide the address to send email notification |
| `sale_return_url` | string | no | We will redirect the IFRAME and the buyer to this URL upon payment success. Default value is taken from the Merchant's settings |
| `sale_mobile` | string | no | In case sale send notification is true, provide the phone number to send SMS notification, if the seller has enabled the SMS module in his account panel |
| `sale_name` | string | no | The name that will be displayed when sending a notification |
| `capture_buyer` | string | no | Flag for requesting the buyer's token for this payment (0 - do not capture token, 1 - capture token). For additional information see Tokens explanation below |
| `buyer_key` | string | no | Buyer key for an instant-payment with the token. This key is received through the use of capture_buyer. Note that this attribute cannot co-exist with the capture_buyer parameter in the same request |
| `buyer_perform_validation` | boolean | no | Flag for performing an online validation of the card with the Issuer. Default value is true |
| `sale_payment_method` | string | no | Flag for performing an online validation of the card with the Issuer. Default value is true |
| `layout` | string | no | IFRAME payment page layout. Optional attribute which may be used with "bit" sale_payment_method. Available layouts are: dynamic, qr-sms. Default value is dynamic |
| `language` | string | no | Changes the language of the payment IFRAME to English, as well as the error messages. Default value is Hebrew (he) |
| `services` | object | no | |
### Request example
No example is documented; this template is generated from the fields — replace the placeholder values.
```json
{
"seller_payme_id": "",
"sale_price": 0,
"currency": "",
"product_name": "",
"transaction_id": "",
"installments": "",
"market_fee": 0,
"sale_send_notifcation": false,
"sale_callback_url": "",
"sale_email": "",
"sale_return_url": "",
"sale_mobile": "",
"sale_name": "",
"capture_buyer": "",
"buyer_key": "",
"buyer_perform_validation": false,
"sale_payment_method": "",
"layout": "",
"language": "",
"services": {}
}
```
## Code samples
### curl
```bash
curl -X POST 'https://sandbox.payme.io/api/generate-sale' \
-H 'Content-Type: application/json' \
--data-raw '{
"seller_payme_id": "",
"sale_price": 0,
"currency": "",
"product_name": "",
"installments": ""
}'
```
### Node.js
```javascript
const response = await fetch("https://sandbox.payme.io/api/generate-sale", {
method: "POST",
headers: {
"Content-Type": "application/json",
},
body: JSON.stringify({
"seller_payme_id": "",
"sale_price": 0,
"currency": "",
"product_name": "",
"installments": ""
}),
});
console.log(await response.text());
```
### Python
```python
import requests
response = requests.post(
"https://sandbox.payme.io/api/generate-sale",
json={
"seller_payme_id": "",
"sale_price": 0,
"currency": "",
"product_name": "",
"installments": "",
},
)
print(response.text)
```
### PHP
```php
",
"sale_price": 0,
"currency": "",
"product_name": "",
"installments": ""
}
BODY;
$ch = curl_init('https://sandbox.payme.io/api/generate-sale');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;
```
## Responses
### 200 — Sale Created Successfully (success)
| Field | Type | Description |
| --- | --- | --- |
| `status_code` | number | Status of the request (0 - success, 1 - error) |
| `sale_url` | string | The URL of the IFRAME secured payment form to display to the buyer |
| `payme_sale_id` | string | Our unique sale ID |
| `payme_sale_code` | number | Our unique sale code (for display purposes only) |
| `price` | number | Sale final price. For example, if the price is 50.75 (max 2 decimal points) the value that needs to be sent is 5075 |
| `transaction_id` | string | Merchant's unique sale ID for correlation with us |
| `currency` | string | Sale currency. [3-letter ISO 4217 name](https://en.wikipedia.org/wiki/ISO_4217). |
```json
{
"status_code": 0,
"sale_url": "https://preprod.paymeservice.com/sale/generate/XXXXXXXX-XXXXXXXX-XXXXXXXX-XXXXXXXX",
"payme_sale_id": "XXXXXXXX-XXXXXXXX-XXXXXXXX-XXXXXXXX",
"payme_sale_code": 12345678,
"price": 10000,
"transaction_id": "12345",
"currency": "USD"
}
```
### 500 — Missing Required Information (error)
| Field | Type | Description |
| --- | --- | --- |
| `status_code` | number | |
| `status_error_details` | string | |
| `status_additional_info` | string | |
| `status_error_code` | number | |
```json
{
"status_code": 1,
"status_error_details": "קישור משתמש לא נמצא",
"status_additional_info": null,
"status_error_code": 251
}
```
## Standalone 3D Secure service
- [Initialize 3DSecure Request](https://docs-staging.payme.io/payments/standalone-3d-secure-service/post-initialize-3dsecure-request): POST /sales/payme_sale_id/3ds — Initialize 3DSecure Request
# Initialize 3DSecure Request
- Sandbox: `POST https://sandbox.payme.io/api/sales/payme_sale_id/3ds`
- Production: `POST https://live.payme.io/api/sales/payme_sale_id/3ds`
## Credentials
- Header `PayMe-Public-Key` (API key)
This end-point is used for our MPI / 3D secure as-a-service funtionality.
If you wish to process transactions with a different gateway but wish to use PayMe's MPI capability - this end-point can be used to get 3DS values required for processing a 3DS sale.
Please follow the instructions that can be found [Hosted Fields JSAPI Guide](/marketplaces-and-platforms/integrations/hosted-fields-jsapi-guide#3ds-integration-using-js-api).
In order to the 3DS service, you'll need to implement our library in your checkout page and collect the user data, then send it to us as a part of the `sales/{payme_sale_id}/3ds` request.
The parameter that needs to be sent is the string you receive from the library after initiating the data collection action:
Paramter|Example|Comments
---|---|---
`meta_data_jwt` | `eyJ0eXAiOiJKV1QiLCJh.......dyfwpbA` | The JWT string received from the library.
## Parameters
| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `PayMe-Public-Key` | header | string | no | Merchant's public key. |
## Request body
Content type: `application/json`
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `payment` | object | no | |
| `payment.method` | string | yes | Payment method for 3DSecure. 3DSecure is a Credit Card module, thus is the only available method |
| `payment.card_number` | string | yes | The card number to make authenticated payment uppon. |
| `payment.card_expiry` | string | yes | Card Expiry date. Format: mmyy |
| `customer` | object | yes | |
| `customer.name` | string | yes | Card holder name. |
| `customer.email` | string | yes | Card holder email. |
| `customer.phone` | string | yes | Card holder mobile phone number. |
| `customer.zip_code` | string | yes | Card holder address zip code. |
| `customer.social_id` | string | yes | Card holder social id / national id. |
| `meta_data_jwt` | string | yes | The user data collected from the browser. Must be encrypted by PayMe's service. |
### Request example
```json
{
"payment": {
"method": "credit-card",
"card_number": "4111111111111111",
"card_expiry": "1221"
},
"customer": {
"name": "developer test",
"email": "test@paymeservice.com",
"phone": "0500000006",
"zip_code": "857393485",
"social_id": "123456782"
}
}
```
## Code samples
### curl
```bash
curl -X POST 'https://sandbox.payme.io/api/sales/payme_sale_id/3ds' \
-H 'Content-Type: application/json' \
-H 'PayMe-Public-Key: ' \
--data-raw '{
"payment": {
"method": "credit-card",
"card_number": "4111111111111111",
"card_expiry": "1221"
},
"customer": {
"name": "developer test",
"email": "test@paymeservice.com",
"phone": "0500000006",
"zip_code": "857393485",
"social_id": "123456782"
}
}'
```
### Node.js
```javascript
const response = await fetch("https://sandbox.payme.io/api/sales/payme_sale_id/3ds", {
method: "POST",
headers: {
"Content-Type": "application/json",
"PayMe-Public-Key": "",
},
body: JSON.stringify({
"payment": {
"method": "credit-card",
"card_number": "4111111111111111",
"card_expiry": "1221"
},
"customer": {
"name": "developer test",
"email": "test@paymeservice.com",
"phone": "0500000006",
"zip_code": "857393485",
"social_id": "123456782"
}
}),
});
console.log(await response.text());
```
### Python
```python
import requests
response = requests.post(
"https://sandbox.payme.io/api/sales/payme_sale_id/3ds",
headers={
"PayMe-Public-Key": "",
},
json={
"payment": {
"method": "credit-card",
"card_number": "4111111111111111",
"card_expiry": "1221",
},
"customer": {
"name": "developer test",
"email": "test@paymeservice.com",
"phone": "0500000006",
"zip_code": "857393485",
"social_id": "123456782",
},
},
)
print(response.text)
```
### PHP
```php
'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Content-Type: application/json',
'PayMe-Public-Key: ',
],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;
```
## Responses
### 200 — OK (success)
| Field | Type | Description |
| --- | --- | --- |
| `status_code` | number | Status of the request (0 - success-redirect, 1 - error) |
| `status_message` | string | A message you may show to the buyer |
| `redirect_url` | string | The URL we should redirect (GET method) to the user. |
```json
{
"status_code": 5,
"status_message": "Generating validation page, please wait",
"redirect_url": "https://preprod.paymeservice.com/3ds/redirect/SALE1587-486438YT-JLHBOZLR-AJJTULHT?pa=eJxdU9tu4jAQfUfqP1h5T%252Bw4V5BxRZeulpWC2C5V1b55nVmIlAt1kgL79WuTBpL6yXPmjOfMxez%252BVOToA1SdVeXcch1iIShllWblbm49b7%252FbsXXP7yZsu1cAy98gWwV8ghBLoK7FDlCWzi047Lw0FmEsXZumgW%252F7f1PPFj5MbRrQOAyI60EElgnUoZvFE7x3d219Juc6t0MZ7s3enYCSe1E2PaAhId8fVmvuB0Hkewx%252Fmjd%252FAWq15EEU0CgMwsilrn63A68kxEpRAF%252BgBuoG9UkYvqADlqzaslFn7kUhw70x8Lcq5%252FumOdQzjI%252FHo5PVSkihUnuXV39E7siqYNiQ%252Bnrw14LYpjVAPUp7ylKe%252FHvI19uf%252BVuR%252BG8vr%252Bf1cuUn9PGYbH%252FNGTaMQUAqGuCUUEIC4iE3mnnTGdVlX%252FABTxSmBv74%252FIRcQhxCdP86aEA6GEWLDtYsQxpCw%252Fa0Sul9OfNpFOv%252B9NaAAadDVYKO0mKu96FwqCVfwgfaqCptZYPWegJat4FvtGv3vjaLffsxKk%252FKRo%252FZd8fHLMnFMRaW6VlS1%252B2UZbfBMty%252FqhP2y2omd1l5PmF49B3uJv8Blq7hOg%253D%253D&url=https%253A%252F%252Fwww.3dsecurempi.com%252FTDS%252FAUT%253FAction%253DAuthenticate&track=BUYER158-7473169I-GRHJVHIH-VBT25PLM%7CTRAN1588-5275735M-BYGTDXRQ-ZPZT4XRE&pay=0"
}
```
### 500 — Internal Server Error (error)
| Field | Type | Description |
| --- | --- | --- |
| `status_code` | number | |
| `status_error_details` | string | Error message to the client |
| `status_additional_info` | string | Additional error information ` |
| `status_error_code` | number | Our unique error code |
```json
{
"status_code": 1,
"status_error_details": "Invalid credit card expiry",
"status_additional_info": "1221f",
"status_error_code": 356
}
```
- [Resolve Secured Hash](https://docs-staging.payme.io/payments/standalone-3d-secure-service/get-sales-payme-sale-id-3ds-hash): GET /sales/payme_sale_id/3ds/hash — Resolve Secured Hash
# Resolve Secured Hash
- Sandbox: `GET https://sandbox.payme.io/api/sales/payme_sale_id/3ds/hash`
- Production: `GET https://live.payme.io/api/sales/payme_sale_id/3ds/hash`
## Credentials
- Header `PayMe-Merchant-Key` (API key)
This end-point is used for our MPI / 3D secure as-a-service funtionality.
You can use this endpoint in order to resolve the secured hash sent from PayMe.
## Parameters
| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `PayMe-Merchant-Key` | header | string | no | The MPL of the seller. |
## Request body
Content type: `application/json`
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `status_code` | number | yes | Status of the action (0 - success) |
| `xid` | string | no | The XID generated by the credit card issuer |
| `eci` | string | no | The ECI generated by the credit card issuer |
| `cavv` | string | no | The CAVV generated by the credit card issuer |
| `payme_sale_id` | string | no | PayMe unique sale ID |
### Request example
```json
{
"status_code": 0,
"xid": "NjZjYzUyZDJmMDQ0NDEzN2FiNGE=",
"eci": "05",
"cavv": "AAACBDaFQCAjBBUAJ4VAAAAAAAA=",
"payme_sale_id": "SALE1587-486438YT-JLHBOZLR-AJJTULHT"
}
```
## Code samples
### curl
```bash
curl -X GET 'https://sandbox.payme.io/api/sales/payme_sale_id/3ds/hash' \
-H 'Content-Type: application/json' \
-H 'PayMe-Merchant-Key: ' \
--data-raw '{
"status_code": 0,
"xid": "NjZjYzUyZDJmMDQ0NDEzN2FiNGE=",
"eci": "05",
"cavv": "AAACBDaFQCAjBBUAJ4VAAAAAAAA=",
"payme_sale_id": "SALE1587-486438YT-JLHBOZLR-AJJTULHT"
}'
```
### Node.js
```javascript
const response = await fetch("https://sandbox.payme.io/api/sales/payme_sale_id/3ds/hash", {
method: "GET",
headers: {
"Content-Type": "application/json",
"PayMe-Merchant-Key": "",
},
body: JSON.stringify({
"status_code": 0,
"xid": "NjZjYzUyZDJmMDQ0NDEzN2FiNGE=",
"eci": "05",
"cavv": "AAACBDaFQCAjBBUAJ4VAAAAAAAA=",
"payme_sale_id": "SALE1587-486438YT-JLHBOZLR-AJJTULHT"
}),
});
console.log(await response.text());
```
### Python
```python
import requests
response = requests.get(
"https://sandbox.payme.io/api/sales/payme_sale_id/3ds/hash",
headers={
"PayMe-Merchant-Key": "",
},
json={
"status_code": 0,
"xid": "NjZjYzUyZDJmMDQ0NDEzN2FiNGE=",
"eci": "05",
"cavv": "AAACBDaFQCAjBBUAJ4VAAAAAAAA=",
"payme_sale_id": "SALE1587-486438YT-JLHBOZLR-AJJTULHT",
},
)
print(response.text)
```
### PHP
```php
'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Content-Type: application/json',
'PayMe-Merchant-Key: ',
],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;
```
## Responses
### 200 — OK (success)
| Field | Type | Description |
| --- | --- | --- |
| `status_code` | number | Status of the action (0 - success, 1 - failure) |
| `payme_sale_id` | string | PayMe unique sale ID |
```json
{
"status_code": 1,
"status": "N",
"payme_sale_id": "SALE1587-486438YT-JLHBOZLR-AJJTULHT"
}
```
### 400 — Bad Request (error)
| Field | Type | Description |
| --- | --- | --- |
| `status_code` | number | Status of the request (1 - failure) |
| `status_error_details` | string | Error message |
| `status_additional_info` | string | Additional error information |
| `status_error_code` | number | Our unique error code |
```json
{
"status_code": 1,
"status_error_details": "Validation error",
"status_additional_info": "eyJpdiI6Ilp...",
"status_error_code": 20
}
```
## Invoices
- [Create Document](https://docs-staging.payme.io/payments/invoices/post-create-invoice): POST /documents — Create Document
# Create Document
- Sandbox: `POST https://sandbox.payme.io/api/documents`
- Production: `POST https://live.payme.io/api/documents`
## Credentials
No credentials are documented for this endpoint.
## Overview
You can use our Invoices API to generate different documents to serve your business needs.
#### Document types
The documents you can generate can be found in the following guide - [Document Types](/marketplaces-and-platforms/lists-statuses/document-types).
## Parameters
This endpoint takes no path, query or header parameters.
## Request body
Content type: `application/json`
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `doc_type` | number | yes | The documents you can generate can be found in the following guide - [Document Types](/marketplaces-and-platforms/lists-statuses/document-types). |
| `buyer_name` | string | yes | Buyer's full name |
| `due_date` | string | no | Payment due date |
| `pay_date` | string | no | The date the payment was completed (relevant for doc_type |
| `doc_date` | string | no | Document creation date |
| `currency` | string | yes | The currency of the document |
| `doc_title` | string | no | The title of the document (header) |
| `doc_comments` | string | no | Document description |
| `exchange_rate` | number | no | Currency exchange rate |
| `vat_rate` | number | no | The VAT (Value Added Tax) rate applied |
| `total_excluding_vat` | number | no | Total amount before VAT applied |
| `discount` | number | no | The discount rate (percentage) applied to the document |
| `total_sum_after_discount` | number | no | Total amount with discount rate included |
| `total_sum_after_discount - copy` | number | no | Total amount with discount rate included |
| `total_sum_including_vat` | number | no | Total amount including VAT |
| `total_paid` | number | no | Total amount paid in this document |
| `total_vat` | number | no | Total VAT paid |
| `language` | string | no | Document language |
| `items` | array | no | |
| `items[].description` | string | yes | Description for item #1 |
| `items[].unit_price` | number | yes | The price per unit (1 item) `unit_price` or `unit_price_with_vat` is required. |
| `items[].vat_exempt` | boolean | no | VAT exempt for the document |
| `items[].quantity` | number | no | Item #1 quantity |
| `items[].unit_price_with_vat` | number | no | Unit (item) price including VAT |
| `items[].currency` | string | no | Currency for item #1 Sale currency. [3-letter ISO 4217 name](https://en.wikipedia.org/wiki/ISO_4217). |
| `items[].exchange_rate` | number | no | Exchange rate for the document |
| `total_paid_including_vat` | number | no | Total amount paid including VAT |
| `cheques` | array | no | The amount paid using a Cheque |
| `cheques[].sum` | number | yes | The amount paid using Cheque |
| `cheques[].date` | string | no | Cheque deposit date |
| `cheques[].bank` | number | no | The bank number - You can check the [list of banks](/marketplaces-and-platforms/lists-statuses/banks-in-israel) for your convenience. |
| `cheques[].branch` | number | no | The bank branch number |
| `cheques[].account` | string | no | The bank account number |
| `cheques[].number` | string | no | The Cheque number |
| `cash` | object | yes | The cash method object |
| `cash.sum` | number | yes | The total amount paid using Cash |
| `bank_transfer` | object | yes | The bank transfer object |
| `bank_transfer.sum` | number | yes | Total amount paid using a bank transfer |
| `bank_transfer.date` | string | no | The date the bank transfer was received |
| `bank_transfer.account` | string | no | The bank account number |
| `paypal` | object | no | The PayPal method object |
| `paypal.sum` | number | yes | Total amount paid using Paypal |
| `paypal.date` | string | yes | The date of when the payment was completed |
| `paypal.transaction_id` | string | no | The external transaction ID (received from Paypal) |
| `paypal.buyer_name` | string | no | The buyer's name |
| `credit_card` | object | no | The credit card object |
| `credit_card.sum` | number | yes | Total amount paid using a credit card |
| `credit_card.installments` | number | no | The number of installments for the payment (1 min, 36 max) |
| `credit_card.first_payment` | number | no | The amount paid in the 1st installment |
| `credit_card.buyer_key` | string | no | If the invoice is paid using a token, buyer key is required |
| `credit_card.number` | string | no | If paid without a token, card number is required |
| `credit_card.type` | string | no | Card brand |
| `credit_card.cvv` | string | no | Card's CVV (3-number code at the back of the card) |
| `credit_card.expiry` | string | no | Expiry date of the card (MMYY) |
| `credit_card.buyer_social_id` | string | no | Buyer's social ID number |
| `credit_card.buyer_name` | string | no | Buyer's full name |
| `credit_card.auth_number` | string | no | Authorization number of the payment |
### Request example
```json
{
"doc_type": 400,
"buyer_name": "John Doe",
"due_date": "2021-08-16T00:00:00.000Z",
"pay_date": "2021-04-16T00:00:00.000Z",
"doc_date": "2021-05-25 00:00:00",
"currency": "ILS",
"doc_title": "Invoice for John Doe",
"doc_comments": "Some description about the invoice",
"exchange_rate": 1,
"vat_rate": 0.17,
"total_excluding_vat": 123,
"discount": 0,
"total_sum_after_discount": 123,
"total_sum_including_vat": 140,
"total_paid": 140,
"total_vat": 17,
"total_paid_including_vat": 140,
"language": "he",
"items": [
{
"description": "Test Item 1",
"unit_price": 100,
"vat_exempt": false,
"quantity": 1,
"unit_price_with_vat": 117,
"currency": "ILS",
"exchange_rate": 1
},
{
"description": "Test Item 2",
"unit_price": 23,
"vat_exempt": true,
"quantity": 1,
"currency": "ILS"
}
],
"cheques": [
{
"sum": 10,
"date": "2021-05-16T00:00:00.000Z",
"bank": 6,
"branch": 22,
"account": "123456",
"number": "0014555"
},
{
"sum": 13,
"date": "2021-06-16T00:00:00.000Z",
"bank": 6,
"branch": 22,
"account": "123456",
"number": "0014555"
}
],
"cash": {
"sum": 25
},
"bank_transfer": {
"sum": 25,
"date": "2021-05-16T00:00:00.000Z",
"account": "123456"
},
"paypal": {
"sum": 25,
"date": "2021-05-16T00:00:00.000Z",
"transaction_id": "123456",
"buyer_name": "John Doe"
},
"credit_card": {
"sum": 25,
"installments": 1,
"first_payment": 50,
"buyer_key": "123456789",
"number": "4580458045804580",
"type": "Visa",
"cvv": "123",
"expiry": "0323",
"buyer_social_id": "05001234",
"buyer_name": "John Doe",
"auth_number": "123123123"
}
}
```
## Code samples
### curl
```bash
curl -X POST 'https://sandbox.payme.io/api/documents' \
-H 'Content-Type: application/json' \
--data-raw '{
"doc_type": 400,
"buyer_name": "John Doe",
"due_date": "2021-08-16T00:00:00.000Z",
"pay_date": "2021-04-16T00:00:00.000Z",
"doc_date": "2021-05-25 00:00:00",
"currency": "ILS",
"doc_title": "Invoice for John Doe",
"doc_comments": "Some description about the invoice",
"exchange_rate": 1,
"vat_rate": 0.17,
"total_excluding_vat": 123,
"discount": 0,
"total_sum_after_discount": 123,
"total_sum_including_vat": 140,
"total_paid": 140,
"total_vat": 17,
"total_paid_including_vat": 140,
"language": "he",
"items": [
{
"description": "Test Item 1",
"unit_price": 100,
"vat_exempt": false,
"quantity": 1,
"unit_price_with_vat": 117,
"currency": "ILS",
"exchange_rate": 1
},
{
"description": "Test Item 2",
"unit_price": 23,
"vat_exempt": true,
"quantity": 1,
"currency": "ILS"
}
],
"cheques": [
{
"sum": 10,
"date": "2021-05-16T00:00:00.000Z",
"bank": 6,
"branch": 22,
"account": "123456",
"number": "0014555"
},
{
"sum": 13,
"date": "2021-06-16T00:00:00.000Z",
"bank": 6,
"branch": 22,
"account": "123456",
"number": "0014555"
}
],
"cash": {
"sum": 25
},
"bank_transfer": {
"sum": 25,
"date": "2021-05-16T00:00:00.000Z",
"account": "123456"
},
"paypal": {
"sum": 25,
"date": "2021-05-16T00:00:00.000Z",
"transaction_id": "123456",
"buyer_name": "John Doe"
},
"credit_card": {
"sum": 25,
"installments": 1,
"first_payment": 50,
"buyer_key": "123456789",
"number": "4580458045804580",
"type": "Visa",
"cvv": "123",
"expiry": "0323",
"buyer_social_id": "05001234",
"buyer_name": "John Doe",
"auth_number": "123123123"
}
}'
```
### Node.js
```javascript
const response = await fetch("https://sandbox.payme.io/api/documents", {
method: "POST",
headers: {
"Content-Type": "application/json",
},
body: JSON.stringify({
"doc_type": 400,
"buyer_name": "John Doe",
"due_date": "2021-08-16T00:00:00.000Z",
"pay_date": "2021-04-16T00:00:00.000Z",
"doc_date": "2021-05-25 00:00:00",
"currency": "ILS",
"doc_title": "Invoice for John Doe",
"doc_comments": "Some description about the invoice",
"exchange_rate": 1,
"vat_rate": 0.17,
"total_excluding_vat": 123,
"discount": 0,
"total_sum_after_discount": 123,
"total_sum_including_vat": 140,
"total_paid": 140,
"total_vat": 17,
"total_paid_including_vat": 140,
"language": "he",
"items": [
{
"description": "Test Item 1",
"unit_price": 100,
"vat_exempt": false,
"quantity": 1,
"unit_price_with_vat": 117,
"currency": "ILS",
"exchange_rate": 1
},
{
"description": "Test Item 2",
"unit_price": 23,
"vat_exempt": true,
"quantity": 1,
"currency": "ILS"
}
],
"cheques": [
{
"sum": 10,
"date": "2021-05-16T00:00:00.000Z",
"bank": 6,
"branch": 22,
"account": "123456",
"number": "0014555"
},
{
"sum": 13,
"date": "2021-06-16T00:00:00.000Z",
"bank": 6,
"branch": 22,
"account": "123456",
"number": "0014555"
}
],
"cash": {
"sum": 25
},
"bank_transfer": {
"sum": 25,
"date": "2021-05-16T00:00:00.000Z",
"account": "123456"
},
"paypal": {
"sum": 25,
"date": "2021-05-16T00:00:00.000Z",
"transaction_id": "123456",
"buyer_name": "John Doe"
},
"credit_card": {
"sum": 25,
"installments": 1,
"first_payment": 50,
"buyer_key": "123456789",
"number": "4580458045804580",
"type": "Visa",
"cvv": "123",
"expiry": "0323",
"buyer_social_id": "05001234",
"buyer_name": "John Doe",
"auth_number": "123123123"
}
}),
});
console.log(await response.text());
```
### Python
```python
import requests
response = requests.post(
"https://sandbox.payme.io/api/documents",
json={
"doc_type": 400,
"buyer_name": "John Doe",
"due_date": "2021-08-16T00:00:00.000Z",
"pay_date": "2021-04-16T00:00:00.000Z",
"doc_date": "2021-05-25 00:00:00",
"currency": "ILS",
"doc_title": "Invoice for John Doe",
"doc_comments": "Some description about the invoice",
"exchange_rate": 1,
"vat_rate": 0.17,
"total_excluding_vat": 123,
"discount": 0,
"total_sum_after_discount": 123,
"total_sum_including_vat": 140,
"total_paid": 140,
"total_vat": 17,
"total_paid_including_vat": 140,
"language": "he",
"items": [
{
"description": "Test Item 1",
"unit_price": 100,
"vat_exempt": False,
"quantity": 1,
"unit_price_with_vat": 117,
"currency": "ILS",
"exchange_rate": 1,
},
{
"description": "Test Item 2",
"unit_price": 23,
"vat_exempt": True,
"quantity": 1,
"currency": "ILS",
},
],
"cheques": [
{
"sum": 10,
"date": "2021-05-16T00:00:00.000Z",
"bank": 6,
"branch": 22,
"account": "123456",
"number": "0014555",
},
{
"sum": 13,
"date": "2021-06-16T00:00:00.000Z",
"bank": 6,
"branch": 22,
"account": "123456",
"number": "0014555",
},
],
"cash": {
"sum": 25,
},
"bank_transfer": {
"sum": 25,
"date": "2021-05-16T00:00:00.000Z",
"account": "123456",
},
"paypal": {
"sum": 25,
"date": "2021-05-16T00:00:00.000Z",
"transaction_id": "123456",
"buyer_name": "John Doe",
},
"credit_card": {
"sum": 25,
"installments": 1,
"first_payment": 50,
"buyer_key": "123456789",
"number": "4580458045804580",
"type": "Visa",
"cvv": "123",
"expiry": "0323",
"buyer_social_id": "05001234",
"buyer_name": "John Doe",
"auth_number": "123123123",
},
},
)
print(response.text)
```
### PHP
```php
'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;
```
## Responses
### 200 — OK (success)
| Field | Type | Description |
| --- | --- | --- |
| `status_code` | number | Status of the request (0 - success, 1 - error) |
| `doc_type` | string | The documents you can generate can be found in the following guide - [Document Types](/marketplaces-and-platforms/lists-statuses/document-types). |
| `language` | string | Changes the language of the payment IFRAME to English, as well as the error messages. Default value is Hebrew (he) |
| `due_date` | string | The date on which a seller expects to receive payment from a buyer |
| `pay_date` | string | Payment date |
| `doc_date` | string | The date of document creation |
| `currency` | string | Sale currency. [3-letter ISO 4217 name](https://en.wikipedia.org/wiki/ISO_4217). |
| `vat_rate` | number | The VAT (Value Added Tax) rate applied. |
| `discount` | number | The discount rate (percentage) applied to the document |
| `total_vat` | number | Total VAT paid |
| `doc_title` | string | The title of the document (header) |
| `buyer_name` | string | The buyer's name |
| `total_paid` | number | Total amount paid in this document |
| `doc_comments` | string | Document description |
| `exchange_rate` | number | Currency exchange rate |
| `total_excluding_vat` | number | Total amount before VAT applied |
| `total_sum_including_vat` | number | Total amount including VAT |
| `total_sum_after_discount` | number | Total amount with discount rate included |
| `total_paid_including_vat` | number | Total amount paid including VAT |
| `cash` | object | The cash method object |
| `cash.sum` | number | The total amount paid using Cash |
| `cheques` | array | The amount paid using a Cheque |
| `cheques[].sum` | number | The amount paid using Cheque |
| `cheques[].date` | string | Cheque deposit date |
| `cheques[].bank` | number | The bank number - You can check the [list of banks](/marketplaces-and-platforms/lists-statuses/banks-in-israel) for your convenience. |
| `cheques[].branch` | number | The bank branch number |
| `cheques[].account` | string | The bank account number |
| `cheques[].number` | string | The Cheque number |
| `bank_transfer` | object | The bank transfer object |
| `bank_transfer.sum` | number | Total amount paid using a bank transfer |
| `bank_transfer.date` | string | The date the bank transfer was received |
| `bank_transfer.account` | string | The bank account number |
| `credit_card` | object | The credit card object |
| `credit_card.sum` | number | Total amount paid using a credit card |
| `credit_card.installments` | number | The number of installments for the payment (1 min, 36 max) |
| `credit_card.first_payment` | number | The amount paid in the 1st installment |
| `credit_card.number` | string | If paid without a token, card number is required |
| `credit_card.type` | string | Card brand |
| `credit_card.cvv` | string | Card's CVV (3-number code at the back of the card) |
| `credit_card.buyer_social_id` | string | Buyer's social ID number |
| `credit_card.buyer_name` | string | Buyer's full name |
| `credit_card.auth_number` | string | Authorization number of the payment |
| `credit_card.expiry` | string | Expiry date of the card (MMYY) |
| `paypal` | object | The PayPal method object |
| `paypal.sum` | number | Total amount paid using Paypal |
| `paypal.date` | string | The date of when the payment was completed |
| `paypal.transaction_id` | string | The external transaction ID (received from Paypal) |
| `paypal.buyer_name` | string | The buyer's name |
| `items` | array | |
| `items[].quantity` | number | Item #1 quantity |
| `items[].description` | string | Description for item #1 |
| `items[].unit_price` | number | The price per unit (1 item) |
| `items[].vat_exempt` | boolean | VAT exempt for the document |
| `items[].currency` | string | Currency for item #1 Sale currency. [3-letter ISO 4217 name](https://en.wikipedia.org/wiki/ISO_4217). |
| `items[].unit_price_with_vat` | number | Unit (item) price including VAT |
| `items[].exchange_rate` | number | Exchange rate for the document |
| `doc_id` | string | Document ID number |
| `doc_url` | string | Document URL |
```json
{
"status_code": 0,
"doc_type": "400",
"language": "he",
"due_date": "2021-08-16T00:00:00.000Z",
"pay_date": "2021-04-16T00:00:00.000Z",
"doc_date": "2021-05-25 00:00:00",
"currency": "ILS",
"vat_rate": 0.17,
"discount": 0,
"total_vat": 17,
"doc_title": "Invoice for John Doe",
"buyer_name": "John Doe",
"total_paid": 140,
"doc_comments": "Some description about the invoice",
"exchange_rate": 1,
"total_excluding_vat": 123,
"total_sum_including_vat": 140,
"total_sum_after_discount": 123,
"total_paid_including_vat": 140,
"cash": {
"sum": 25
},
"cheques": [
{
"sum": 10,
"date": "2021-05-16T00:00:00.000Z",
"bank": 6,
"branch": 22,
"account": "123456",
"number": "0014555"
},
{
"sum": 13,
"date": "2021-06-16T00:00:00.000Z",
"bank": 6,
"branch": 22,
"account": "123456",
"number": "0014555"
}
],
"bank_transfer": {
"sum": 25,
"date": "2021-05-16T00:00:00.000Z",
"account": "123456"
},
"credit_card": {
"sum": 0,
"installments": 1,
"first_payment": 50,
"number": "4580458045804580",
"type": "Visa",
"cvv": "123",
"buyer_social_id": "05001234",
"buyer_name": "John Doe",
"auth_number": "123123123",
"expiry": "323"
},
"paypal": {
"sum": 50,
"date": "2021-05-16T00:00:00.000Z",
"transaction_id": "123456",
"buyer_name": "John Doe"
},
"items": [
{
"quantity": 1,
"description": "Test Item 1",
"unit_price": 100,
"vat_exempt": false,
"currency": "ILS",
"unit_price_with_vat": 117,
"exchange_rate": 1
},
{
"quantity": 1,
"description": "Test Item 2",
"unit_price": 23,
"vat_exempt": true,
"currency": "ILS"
}
],
"doc_id": "fa397fce-aee6-4c6d-ae9c-273ae1e3a317",
"doc_url": "https://invoice-staging.paymeservice.com/documents/fa397fce-aee6-4c6d-ae9c-273ae1e3a317"
}
```
### 400 — Bad Request (error)
| Field | Type | Description |
| --- | --- | --- |
| `status_code` | number | |
| `status_error_details` | string | |
| `status_additional_info` | object | |
| `status_additional_info.doc_type` | array | |
| `status_additional_info.items` | array | |
| `status_additional_info.buyer_name` | array | |
| `status_error_code` | number | |
```json
{
"status_code": 1,
"status_error_details": "The given data was invalid.",
"status_additional_info": {
"doc_type": [
"The doc type field is required."
],
"items": [
"The items field is required."
],
"buyer_name": [
"The buyer name field is required."
]
},
"status_error_code": 20
}
```
- [Get Generated Document By ID](https://docs-staging.payme.io/payments/invoices/show-generated-document-by-id): GET /documents/document_id — Get Generated Document By ID
# Get Generated Document By ID
- Sandbox: `GET https://sandbox.payme.io/api/documents/document_id`
- Production: `GET https://live.payme.io/api/documents/document_id`
## Credentials
- Header `PayMe-Merchant-Key` (API key)
## Overview
In order to query for existing documents, you will need to use the following endpoint and parameters:
Environment | URL
---|---
`Sandbox`| `https://sandbox.payme.io/api/documents?page=0&limit=5&field=createdAt&sort=desc`
`Production` | `https://live.payme.io/api/documents?page=0&limit=5&field=createdAt&sort=desc`
##### Header
Parameter | Description
---|---
`PayMe-Merchant-Key` | Seller's MPL `DEMOMPL-DEMOMPL-DEMOMPL-DEMOMPL-`
### Request Example:
Item | Description | Example
---|---|---
URL | `https://sandbox.payme.io/api/documents/{document_ID}` | `INV12321*****`
Header| `seller_payme_id` | `MPLDEMO-MPLDEMO-MPLDEMO-MPLDEMO`
## Parameters
| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `PayMe-Merchant-Key` | header | string | yes | |
## Code samples
### curl
```bash
curl -X GET 'https://sandbox.payme.io/api/documents/document_id' \
-H 'PayMe-Merchant-Key: '
```
### Node.js
```javascript
const response = await fetch("https://sandbox.payme.io/api/documents/document_id", {
method: "GET",
headers: {
"PayMe-Merchant-Key": "",
},
});
console.log(await response.text());
```
### Python
```python
import requests
response = requests.get(
"https://sandbox.payme.io/api/documents/document_id",
headers={
"PayMe-Merchant-Key": "",
},
)
print(response.text)
```
### PHP
```php
'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'PayMe-Merchant-Key: ',
],
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;
```
## Responses
No responses are documented for this endpoint.
- [Show Generated Document By ID](https://docs-staging.payme.io/payments/invoices/show-generated-document-by-id-2): GET /show-documents/document_id — Show Generated Document By ID
# Show Generated Document By ID
- Sandbox: `GET https://sandbox.payme.io/api/show-documents/document_id`
- Production: `GET https://live.payme.io/api/show-documents/document_id`
## Credentials
- Header `PayMe-Merchant-Key` (API key)
## Overview
In order to query for existing documents, you will need to use the following endpoint and parameters:
Environment | URL
---|---
`Staging`| `https://sandbox.paymes.io/api/documents?page=0&limit=5&field=createdAt&sort=desc`
`Production` | `https://live.paymes.io/api/documents?page=0&limit=5&field=createdAt&sort=desc`
##### Header
Parameter | Description
---|---
`PayMe-Merchant-Key` | Seller's MPL `DEMOMPL-DEMOMPL-DEMOMPL-DEMOMPL-`
### Request Example:
Item | Description | Example
---|---|---
URL | `https://sandbox.payme.io/api/show-documents/{document_ID}` | `INV12321*****`
Header| `seller_payme_id` | `MPLDEMO-MPLDEMO-MPLDEMO-MPLDEMO`
## Parameters
| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `PayMe-Merchant-Key` | header | string | yes | |
## Code samples
### curl
```bash
curl -X GET 'https://sandbox.payme.io/api/show-documents/document_id' \
-H 'PayMe-Merchant-Key: '
```
### Node.js
```javascript
const response = await fetch("https://sandbox.payme.io/api/show-documents/document_id", {
method: "GET",
headers: {
"PayMe-Merchant-Key": "",
},
});
console.log(await response.text());
```
### Python
```python
import requests
response = requests.get(
"https://sandbox.payme.io/api/show-documents/document_id",
headers={
"PayMe-Merchant-Key": "",
},
)
print(response.text)
```
### PHP
```php
'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'PayMe-Merchant-Key: ',
],
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;
```
## Responses
No responses are documented for this endpoint.
- [Query Existing Documents](https://docs-staging.payme.io/payments/invoices/get-documents): GET /documents — Query Existing Documents
# Query Existing Documents
- Sandbox: `GET https://sandbox.payme.io/api/documents`
- Production: `GET https://live.payme.io/api/documents`
## Credentials
- Header `PayMe-Merchant-Key` (API key)
## Overview
In order to query for existing documents, you will need to use the following endpoint and parameters:
Environment | URL
---|---
`Sandbox`| `https://sandbox.payme.io/api/documents?page=0&limit=5&field=createdAt&sort=desc`
`Production` | `https://live.payme.io/api/documents?page=0&limit=5&field=createdAt&sort=desc`
##### Header
Parameter | Description
---|---
`PayMe-Merchant-Key` | Seller's MPL `MPL00006-00006EXM-EXAMPLE0-EXAMPLE6`
## Parameters
| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `page` | query | number | no | How many pages should be included in the query |
| `limit` | query | number | no | How many documents per extraction |
| `field` | query | string | no | The dates the query is for |
| `sort` | query | string | no | The order of documents |
| `PayMe-Merchant-Key` | header | string | no | |
## Code samples
### curl
```bash
curl -X GET 'https://sandbox.payme.io/api/documents' \
-H 'PayMe-Merchant-Key: '
```
### Node.js
```javascript
const response = await fetch("https://sandbox.payme.io/api/documents", {
method: "GET",
headers: {
"PayMe-Merchant-Key": "",
},
});
console.log(await response.text());
```
### Python
```python
import requests
response = requests.get(
"https://sandbox.payme.io/api/documents",
headers={
"PayMe-Merchant-Key": "",
},
)
print(response.text)
```
### PHP
```php
'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'PayMe-Merchant-Key: ',
],
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;
```
## Responses
No responses are documented for this endpoint.
## Query APIs
- [List Sales](https://docs-staging.payme.io/payments/query-apis/post-get-sales): POST /get-sales — List Sales
# List Sales
- Sandbox: `POST https://sandbox.payme.io/api/get-sales`
- Production: `POST https://live.payme.io/api/get-sales`
## Credentials
- Request body field `payme_client_key` (optional): PayMe partner key. Only partners (platforms managing many sellers) have one; a merchant authenticates with seller_payme_id alone. Can also be sent in the PayMe-Partner-Key header.
- Request body field `seller_payme_id` (optional): Our unique seller ID (MPL). If you are a partner, you can use multiple seller_payme_id attributes to retreive data for these specific sellers
## Overview
You can retreive data on different sales processed by your sellers using this endpoint.
#### Query pagination (more than 500 results)
If you are sending a query and expect to receive more than 500 results, make sure you use this function of Query Pagination.
```json
{
"seller_payme_id": "MPL1DEMO-XXXXXXXX-XXXXXXXX-XXXXXXXX",
...
"page_size": 100, // Max allowed page size is 500
"page": 1
}
```
## Parameters
This endpoint takes no path, query or header parameters.
## Request body
Content type: `application/json`
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `payme_client_key` | string | no | PayMe partner key. Only partners (platforms managing many sellers) have one; a merchant authenticates with seller_payme_id alone. Can also be sent in the PayMe-Partner-Key header. |
| `seller_payme_id` | string | no | Our unique seller ID (MPL). If you are a partner, you can use multiple seller_payme_id attributes to retreive data for these specific sellers |
| `seller_id` | string | no | Merchant's unique seller ID for correlation with us |
| `sale_payme_code` | string | no | Our unique sale code |
| `sale_payme_id` | string | no | Our unique sale ID |
| `transaction_id` | string | no | Your own order ID, as sent to generate-sale. It is not unique, so the call can return several sales. |
| `sale_created` | string | no | Exact creation date and time for which to retrieve sales. ISO-8601 formatted |
| `sale_created_min` | string | no | Earliest creation date and time for which to retrieve sales. ISO-8601 formatted |
| `sale_created_max` | string | no | Latest date and time for which to retrieve sales. ISO-8601 formatted |
| `sale_status` | string | no | Sale status. All statuses are available [Sale Statuses](/marketplaces-and-platforms/lists-statuses/sale-statuses). For multiple statuses use array format like` ["initial","validated"]` |
| `sale_price` | number | no | Sale final price. For example, if the price is 50.75 (max 2 decimal points) the value that needs to be sent is 5075 |
| `sale_currency` | string | no | Sale currency. [3-letter ISO 4217 name](https://en.wikipedia.org/wiki/ISO_4217). |
| `sale_auth_number` | string | no | Sale authorization number from the credit company |
| `buyer_card_mask` | string | no | Buyer's credit card mask |
| `buyer_card_last_four_digits` | string | no | Buyer's credit card last four digits |
| `buyer_email` | string | no | Buyer's eMail address |
| `buyer_name` | string | no | Buyer's full name |
| `buyer_phone` | string | no | Buyer's phone number |
| `buyer_social_id` | string | no | Buyer's social id (For Israeli sellers only) |
| `buyer_card_is_foreign` | boolean | no | Is the buyer's credit card foreign |
### Request example
```json
{
"payme_client_key": "XXXXXXXX",
"transaction_id": "12345"
}
```
## Code samples
### curl
```bash
curl -X POST 'https://sandbox.payme.io/api/get-sales' \
-H 'Content-Type: application/json' \
--data-raw '{
"payme_client_key": "XXXXXXXX",
"transaction_id": "12345"
}'
```
### Node.js
```javascript
const response = await fetch("https://sandbox.payme.io/api/get-sales", {
method: "POST",
headers: {
"Content-Type": "application/json",
},
body: JSON.stringify({
"payme_client_key": "XXXXXXXX",
"transaction_id": "12345"
}),
});
console.log(await response.text());
```
### Python
```python
import requests
response = requests.post(
"https://sandbox.payme.io/api/get-sales",
json={
"payme_client_key": "XXXXXXXX",
"transaction_id": "12345",
},
)
print(response.text)
```
### PHP
```php
'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;
```
## Responses
### 200 — OK (success)
| Field | Type | Description |
| --- | --- | --- |
| `items_count` | number | Number of items |
| `items` | array | |
| `items[].seller_payme_id` | string | Our unique seller ID |
| `items[].seller_id` | string | Merchant's unique seller ID for correlation with us |
| `items[].sale_payme_id` | string | Our unique sale ID |
| `items[].sale_payme_code` | string | Our unique sale code |
| `items[].transaction_id` | string | Your own order ID, as you sent it to generate-sale. It is not unique: several sales can share it. |
| `items[].sale_created` | string | Exact creation date and time for which to retrieve sales. ISO-8601 formatted |
| `items[].sale_status` | string | Sale status. All available Sale statuses |
| `items[].sale_currency` | string | Currency the transaction was processed in |
| `items[].sale_price` | number | Sale final price. For example, if the price is 50.75 (max 2 decimal points) the value that needs to be sent is 5075 |
| `items[].sale_price_after_fees` | number | Sale amount including fees |
| `items[].sale_description` | string | What was the goods/services the buyer paid for |
| `items[].sale_installments` | number | Number of installments used for the purchase` |
| `items[].sale_vat` | string | VAT added to the sale |
| `items[].sale_paid_date` | string | The date the sale was paid |
| `items[].sale_auth_number` | string | Sale authorization number from the credit company |
| `items[].sale_release_date` | string | The expected date the funds will be available in the seller's balance |
| `items[].sale_fees` | object | |
| `items[].sale_fees.sale_processing_fee` | string | Total processing fee |
| `items[].sale_fees.sale_processing_charge` | string | Processing charge |
| `items[].sale_fees.sale_discount_fee` | string | Discount fee |
| `items[].sale_fees.sale_rapid_settlement_fee` | string | Rapid settlement fee |
| `items[].sale_fees.sale_market_fee` | string | Sale's market fee |
| `items[].sale_buyer_details` | object | |
| `items[].sale_buyer_details.buyer_card_mask` | string | Buyer's credit card mask |
| `items[].sale_buyer_details.buyer_card_expiry` | string | Expiration date |
| `items[].sale_buyer_details.buyer_card_brand` | string | Card brand |
| `items[].sale_buyer_details.buyer_card_is_foreign` | boolean | Card is foreign or domestic 'true' for foreign, 'false' for domestic. |
| `items[].sale_buyer_details.buyer_name` | string | Buyer's first and last name |
| `items[].sale_buyer_details.buyer_email` | string | Buyer's email |
| `items[].sale_buyer_details.buyer_phone` | string | Buyer's phone |
| `items[].sale_buyer_details.buyer_social_id` | string | Buyer's social ID |
| `items[].sale_invoices` | array | Invoice generated unique ID |
| `status_code` | number | 0 for Sucessful requests, 1 for Failed requests |
```json
{
"items_count": 1,
"items": [
{
"seller_payme_id": "XXXXXXXX-XXXXXXXX-XXXXXXXX-XXXXXXXX",
"seller_id": "12345",
"sale_payme_id": "XXXXXXXX-XXXXXXXX-XXXXXXXX-XXXXXXXX",
"sale_payme_code": "12345678",
"transaction_id": "12345",
"sale_created": "2016-01-01 15:15:15",
"sale_status": "completed",
"sale_currency": "USD",
"sale_price": 10000,
"sale_price_after_fees": 8970,
"sale_description": "A duck",
"sale_installments": 1,
"sale_vat": "0.17",
"sale_paid_date": "2016-01-01 15:16:15",
"sale_auth_number": "01A2B3C",
"sale_release_date": "2016-01-08 15:15:15",
"sale_error_code": "",
"sale_error_text": "",
"sale_fees": {
"sale_processing_fee": "3.50",
"sale_processing_charge": "1.20",
"sale_discount_fee": "0.50",
"sale_rapid_settlement_fee": "0.30",
"sale_market_fee": "0.00"
},
"sale_buyer_details": {
"buyer_card_mask": "458045******4580",
"buyer_card_expiry": "1022",
"buyer_card_brand": "Visa",
"buyer_card_is_foreign": true,
"buyer_name": "First Last",
"buyer_email": "buyer@example.com",
"buyer_phone": "0500000001",
"buyer_social_id": "000000001"
},
"sale_invoices": []
}
],
"status_code": 0
}
```
### 500 — Internal Server Error (error)
| Field | Type | Description |
| --- | --- | --- |
| `status_code` | number | |
| `status_error_details` | string | |
| `status_additional_info` | string | |
| `status_error_code` | number | |
```json
{
"status_code": 1,
"status_error_details": "שירות לא נמצא",
"status_additional_info": "payme_client_key",
"status_error_code": 200
}
```
- [Reporting & Data](https://docs-staging.payme.io/payments/query-apis/reporting-data): Access preconfigured reports to gain insight into essential activities, such as sales, transactions, subscriptions, and balance adjustments.
# Reporting and Data
Access preconfigured reports to gain insight into essential activities, such as sales, transactions, subscriptions, and balance adjustments.
Our queries APIs enable you to perform various actions related to obtaining data on:
API| Description
---|---
**get-sellers**| Extract data about your sellers
**get-sales** | Extract data on different sales your sellers completed
**get-transactions**| Extract data on transactions your sellers completed
**get-subscriptions**|Extract data on different subscriptions that are currently active/inactive
**get-withdrawals**|Extract data on specific withdrawals yoursellers requested.
- [List Transactions](https://docs-staging.payme.io/payments/query-apis/post-get-transactions): POST /get-transactions — List Transactions
# List Transactions
- Sandbox: `POST https://sandbox.payme.io/api/get-transactions`
- Production: `POST https://live.payme.io/api/get-transactions`
## Credentials
- Request body field `seller_payme_id` (required): Our unique seller ID (MPL). If you are a partner, you can use multiple seller_payme_id attributes to retreive data for these specific sellers. In this case you need to send also payme_client_key.
## Overview
You can retreive data on different transactions processed by your sellers using this endpoint.
#### Filtering
In order to filter by transaction type, use the following method:
Parameter name|Description
---|---
`transaction_status` | The applicable transaction statuses.
You can find the transaction statuses in the following guide - [Transaction Statuses](/marketplaces-and-platforms/lists-statuses/transaction-statuses).
#### Query pagination (more than 500 results)
If you are sending a query and expect to receive more than 500 results, make sure you use this function of Query Pagination.
```json
{
"seller_payme_id": "MPL1DEMO-XXXXXXXX-XXXXXXXX-XXXXXXXX",
...
"page_size": 100, // Max allowed page size is 500
"page": 1
}
```
## Parameters
This endpoint takes no path, query or header parameters.
## Request body
Content type: `application/json`
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `seller_payme_id` | string | yes | Our unique seller ID (MPL). If you are a partner, you can use multiple seller_payme_id attributes to retreive data for these specific sellers. In this case you need to send also payme_client_key. |
| `transaction_type` | number | no | Transaction type can be found [Transaction Types](/marketplaces-and-platforms/lists-statuses/transaction-types) |
| `transaction_status` | string | no | All transaction statuses can be found [Transaction Statuses](/marketplaces-and-platforms/lists-statuses/transaction-statuses) |
| `sale_status` | string | no | Sale Status can be found [Sale Statuses](/marketplaces-and-platforms/lists-statuses/sale-statuses) Example: `completed` |
| `sale_currency` | string | no | Sale currency. [3-letter ISO 4217 name](https://en.wikipedia.org/wiki/ISO_4217). Example: `ILS` |
| `sale_payment_method` | string | no | Sale Payment Method (for the list see [Payment Methods](/payments/direct-api/available-payment-methods)) Example: `credit-card` |
| `transaction_created_min` | string | no | Earliest creation date and time for which to retrieve transactions. ISO-8601 formatted |
| `transaction_created_max` | string | no | Latest date and time for which to retrieve transactions. ISO-8601 formatted |
| `transaction_created_at` | string | no | Transaction creation date and time for which to retrieve transactions. ISO-8601 formatted |
| `transaction_id` | string | no | Merchant's unique sale ID for correlation with us |
| `payme_transaction_id` | string | no | PayMe's unique transaction ID |
| `transaction_price` | number | no | The transaction price amount in cents |
| `sale_price` | number | no | The sale price amount in cents |
| `sale_auth_number` | string | no | Sale authorization number from the credit company |
| `buyer_card_mask` | string | no | Buyer's credit card mask |
| `buyer_name` | string | no | Buyer's full name |
| `buyer_phone` | string | no | Buyer's phone |
| `buyer_social_id` | string | no | Buyer's social ID |
| `buyer_card_is_foreign` | boolean | no | Indicates if the card is foreign |
| `buyer_card_last_four_digits` | string | no | Buyer's credit card last four digits |
| `sale_is_3ds` | boolean | no | In case the sale is with 3DS |
| `transaction_is_matched` | boolean | no | Indicates if the transaction is correlated. |
### Request example
```json
{
"seller_payme_id": "MPL90007-90007EXM-EXAMPLE0-EXAMPLE9",
"transaction_type": 1,
"transaction_status": "chargeback-refund",
"sale_status": [
"chargeback"
],
"sale_currency": [
"ILS"
],
"sale_payment_method": [
"credit-card"
],
"time": [
"2021-08-05"
]
}
```
## Code samples
### curl
```bash
curl -X POST 'https://sandbox.payme.io/api/get-transactions' \
-H 'Content-Type: application/json' \
--data-raw '{
"seller_payme_id": "MPL90007-90007EXM-EXAMPLE0-EXAMPLE9",
"transaction_type": 1,
"transaction_status": "chargeback-refund",
"sale_status": [
"chargeback"
],
"sale_currency": [
"ILS"
],
"sale_payment_method": [
"credit-card"
],
"time": [
"2021-08-05"
]
}'
```
### Node.js
```javascript
const response = await fetch("https://sandbox.payme.io/api/get-transactions", {
method: "POST",
headers: {
"Content-Type": "application/json",
},
body: JSON.stringify({
"seller_payme_id": "MPL90007-90007EXM-EXAMPLE0-EXAMPLE9",
"transaction_type": 1,
"transaction_status": "chargeback-refund",
"sale_status": [
"chargeback"
],
"sale_currency": [
"ILS"
],
"sale_payment_method": [
"credit-card"
],
"time": [
"2021-08-05"
]
}),
});
console.log(await response.text());
```
### Python
```python
import requests
response = requests.post(
"https://sandbox.payme.io/api/get-transactions",
json={
"seller_payme_id": "MPL90007-90007EXM-EXAMPLE0-EXAMPLE9",
"transaction_type": 1,
"transaction_status": "chargeback-refund",
"sale_status": [
"chargeback",
],
"sale_currency": [
"ILS",
],
"sale_payment_method": [
"credit-card",
],
"time": [
"2021-08-05",
],
},
)
print(response.text)
```
### PHP
```php
'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;
```
## Responses
### 200 — OK (success)
| Field | Type | Description |
| --- | --- | --- |
| `seller_payme_id` | string | Our unique seller ID |
| `seller_id` | integer | Merchant's unique seller ID for correlation with us |
| `sale_payme_id` | string | Our unique sale ID |
| `sale_payme_code` | number | Our unique sale code |
| `transaction_id` | string | Merchant's unique sale ID for correlation with us |
| `payme_transaction_id` | string | PayMe's unique transaction ID |
| `transaction_created_at` | string | Exact creation date and time for which to retrieve transaction. ISO-8601 formatted |
| `sale_type` | number | Sale type. All available Sale types can be found [Sale Types](/marketplaces-and-platforms/lists-statuses/sale-types) |
| `sale_status` | string | Sale status. All available Sale statuses can be found [Sale Statuses](/marketplaces-and-platforms/lists-statuses/sale-statuses) |
| `transaction_status` | string | Transaction status. All available transaction statuses can be found [Transaction Statuses](/marketplaces-and-platforms/lists-statuses/transaction-statuses) |
| `transaction_type` | number | Transaction type. All available transaction types can be found [Transaction Types](/marketplaces-and-platforms/lists-statuses/transaction-types) |
| `sale_currency` | string | Currency the transaction was processed in |
| `sale_description` | string | What was the goods/services the buyer paid for |
| `sale_installments` | number | Number of installments used for the purchase` |
| `sale_payment_method` | string | The Payment method used to pay the sale. For all the payment methods see [Available Payment Methods](/payments/direct-api/available-payment-methods). |
| `transaction_price` | number | The price amount |
| `transaction_price_after_fees` | string | Transaction amount including fees |
| `sale_vat` | string | VAT added to the sale |
| `sale_auth_number` | string | Sale authorization number from the credit company |
| `transaction_release_date` | string | The expected date the funds will be available in the seller's balance |
| `transaction_voucher` | string | PayMe's transaction voucher |
| `transaction_reference_number` | string | Transaction reference number received from gateway. |
| `transaction_action` | string | The action that was taken on the transaction. Possible values: Authorize, Tokenize, Detokenize, Debit, Capture, Refund, PartialRefund, Chargeback, ChargebackRefund, Void, PartialVoid, PartialChargeback, PartialChargebackRefund |
| `transaction_first_payment` | number | Transaction first payment amount, or total amount if there are no installements. |
| `transaction_periodical_payment` | number | Transaction periodical payment amount in case of installements. |
| `transaction_arn` | string | Acquirer Reference Numbers |
| `transaction_acquirer` | string | Transaction acquirer |
| `transaction_discounter` | string | Transaction discounter entity |
| `transaction_error_code` | number | In case of failure, the transaction error code. If transaction was successful error code will be 20000. |
| `transaction_error_text` | string | The error code description. |
| `transaction_is_matched` | boolean | Indicates if the transaction is correlated. |
| `transaction_match_statuses` | array | If transaction is matched, indicates the relevant matched statuses. |
| `transaction_is_canceled` | boolean | Indicates if the transaction was canceled before transmitted. |
| `sale_is_3ds` | boolean | In case the sale is with 3DS |
| `sale_fees` | object | |
| `sale_fees.sale_processing_fee` | string | Processing fee |
| `sale_fees.sale_processing_fee_total` | number | Total processing fee |
| `sale_fees.sale_processing_charge` | string | Processing charge |
| `sale_fees.sale_discount_fee` | string | Discount fee |
| `sale_fees.sale_discount_fee_total` | number | Total Discount fee |
| `sale_fees.sale_rapid_settlement_fee` | string | Rapid settlement fee |
| `sale_fees.sale_rapid_settlement_fee_total` | number | Total Rapid settlement fee |
| `sale_fees.sale_annual_interest_rate` | string | The annual interest rate (precentage) of the rapid and discount settlements |
| `sale_fees.sale_market_fee` | string | Sale's market fee |
| `sale_fees.sale_market_fee_total` | number | Total sale's market fee |
| `sale_buyer_details` | object | |
| `sale_buyer_details.buyer_card_mask` | string | Buyer's credit card mask |
| `sale_buyer_details.buyer_card_expiry` | string | Expiration date |
| `sale_buyer_details.buyer_card_brand` | string | Card brand |
| `sale_buyer_details.buyer_card_is_foreign` | boolean | Indicates if the card is foreign |
| `sale_buyer_details.buyer_name` | string | Buyer's full name |
| `sale_buyer_details.buyer_email` | string | Buyer's email |
| `sale_buyer_details.buyer_phone` | string | Buyer's phone |
| `sale_buyer_details.buyer_social_id` | string | Buyer's social ID |
| `transaction_invoice_url` | string | Link to the invoice |
| `transaction_invoice_doc_number` | string | The invoice number. |
```json
{
"seller_payme_id": "MPL00008-00008EXM-EXAMPLE0-EXAMPLE8",
"seller_id": null,
"sale_payme_id": "SALE1499-869577YG-Y2QXJ6PK-INXR2FAE",
"sale_payme_code": 115498,
"transaction_id": "",
"payme_transaction_id": "TRAN1499-869602B9-7QIUNKHI-F0SL1AOV",
"transaction_created_at": "2017-07-12 17:26:42",
"sale_type": 1,
"sale_status": "completed",
"transaction_status": "validated",
"transaction_type": 1,
"sale_currency": "ILS",
"sale_description": "produt",
"sale_installments": 5,
"sale_payment_method": "credit-card",
"transaction_price": 9000,
"transaction_price_after_fees": "8617",
"sale_vat": "0.17",
"sale_auth_number": "2154577",
"transaction_release_date": "2017-08-01 06:00:00",
"transaction_voucher": "10784",
"transaction_reference_number": null,
"transaction_acquirer": null,
"transaction_discounter": null,
"transaction_error_code": "20000",
"transaction_error_text": "Permitted transaction",
"transaction_is_matched": false,
"transaction_match_statuses": [],
"sale_is_3ds": false,
"sale_fees": {
"sale_processing_fee": "2.50",
"sale_processing_fee_total": 225,
"sale_processing_charge": "1.20",
"sale_discount_fee": "0.00",
"sale_discount_fee_total": 0,
"sale_rapid_settlement_fee": "0.00",
"sale_rapid_settlement_fee_total": 0,
"sale_yearly_interest_fee": null,
"sale_market_fee": "0.00",
"sale_market_fee_total": 0
},
"sale_buyer_details": {
"buyer_card_mask": "458000******0000",
"buyer_card_expiry": "0521",
"buyer_card_brand": 0,
"buyer_card_is_foreign": false,
"buyer_name": "Adam Kogan",
"buyer_email": "user4@example.com",
"buyer_phone": "0500000004",
"buyer_social_id": "310048889"
},
"transaction_invoice_url": null
}
```
### 500 — Internal Server Error (error)
| Field | Type | Description |
| --- | --- | --- |
| `status_code` | number | |
| `status_error_details` | string | |
| `status_additional_info` | string | |
| `status_error_code` | number | |
```json
{
"status_code": 1,
"status_error_details": "Please verify that the JSON provided is valid",
"status_additional_info": null,
"status_error_code": 901
}
```
- [List Subscriptions](https://docs-staging.payme.io/payments/query-apis/post-get-subscriptions): POST /get-subscriptions — List Subscriptions
# List Subscriptions
- Sandbox: `POST https://sandbox.payme.io/api/get-subscriptions`
- Production: `POST https://live.payme.io/api/get-subscriptions`
## Credentials
- Request body field `payme_client_key` (required): PayMe Partner Key
- Request body field `seller_payme_id` (optional): Our unique seller ID (MPL). If you are a partner, you can use multiple seller_payme_id attributes to retreive data for these specific sellers
## Overview
You can retreive data on subscriptions processed by your sellers using this endpoint.
To understand the different use-cases for this API, See Get Subscriptions API guide [here](https://docs.paymeservice.com/docs/payme-public/b3A6MjU2MDk2MjE-get-sales).
#### Subscription Iteration Types
You can find them in the following guide - [Subscription Iteration Types](/marketplaces-and-platforms/lists-statuses/subscription-iteration-types).
#### Subscription Statuses
You can find them in the following guide - [Subscription Statuses](/marketplaces-and-platforms/lists-statuses/subscription-statuses).
#### Query pagination (more than 500 results)
If you are sending a query and expect to receive more than 500 results, make sure you use this function of Query Pagination.
```json
{
"seller_payme_id": "MPL1DEMO-XXXXXXXX-XXXXXXXX-XXXXXXXX",
...
"page_size": 100, // Max allowed page size is 500
"page": 1
}
```
## Parameters
This endpoint takes no path, query or header parameters.
## Request body
Content type: `application/json`
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `payme_client_key` | string | yes | PayMe Partner Key |
| `seller_payme_id` | string | no | Our unique seller ID (MPL). If you are a partner, you can use multiple seller_payme_id attributes to retreive data for these specific sellers |
| `seller_id` | string | no | Merchant's unique seller ID for correlation with us |
| `sub_payme_code` | string | no | Our unique subscription code |
| `sub_payme_id` | string | no | Our unique sub ID |
| `sub_created` | string | no | Exact creation date and time for which to retrieve subscriptions. ISO-8601 formatted |
| `sub_created_min` | string | no | Earliest creation date and time for which to retrieve subscriptions. ISO-8601 formatted |
| `sub_created_max` | string | no | Latest date and time for which to retrieve subscriptions. ISO-8601 formatted |
| `sub_status` | string | no | Subscription status. You can find them in the following guide - [Subscription Statuses](/marketplaces-and-platforms/lists-statuses/subscription-statuses). |
| `sub_iteration_type` | number | no | Subscription type ID. You can find them in the following guide - [Subscription Iteration Types](/marketplaces-and-platforms/lists-statuses/subscription-iteration-types). |
| `sub_price` | number | no | Subscription final price. For example, if the price is 50.75 (max 2 decimal points) the value that needs to be sent is 5075 |
| `sub_currency` | string | no | Sale currency. [3-letter ISO 4217 name](https://en.wikipedia.org/wiki/ISO_4217). |
| `sub_iterations` | number | no | Subscription amount of iterations |
| `sub_start_date` | string | no | Exact start date and time for which to retrieve subscriptions. ISO-8601 formatted |
| `sub_paid` | boolean | no | Was the subscription paid or not |
### Request example
```json
{
"payme_client_key": "XXXXXXXX",
"sub_payme_code": "1234"
}
```
## Code samples
### curl
```bash
curl -X POST 'https://sandbox.payme.io/api/get-subscriptions' \
-H 'Content-Type: application/json' \
--data-raw '{
"payme_client_key": "XXXXXXXX",
"sub_payme_code": "1234"
}'
```
### Node.js
```javascript
const response = await fetch("https://sandbox.payme.io/api/get-subscriptions", {
method: "POST",
headers: {
"Content-Type": "application/json",
},
body: JSON.stringify({
"payme_client_key": "XXXXXXXX",
"sub_payme_code": "1234"
}),
});
console.log(await response.text());
```
### Python
```python
import requests
response = requests.post(
"https://sandbox.payme.io/api/get-subscriptions",
json={
"payme_client_key": "XXXXXXXX",
"sub_payme_code": "1234",
},
)
print(response.text)
```
### PHP
```php
'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;
```
## Responses
### 200 — OK (success)
| Field | Type | Description |
| --- | --- | --- |
| `items_count` | number | Number of subscription |
| `items` | array | |
| `items[].seller_payme_id` | string | Our unique seller ID |
| `items[].seller_id` | string | Merchant's unique seller ID for correlation with us |
| `items[].sub_payme_id` | string | Our unique sub ID |
| `items[].payme_sub_code` | number | Our unique subscription code |
| `items[].sub_created` | string | Exact creation date and time for which to retrieve subscriptions. ISO-8601 formatted |
| `items[].sub_start_date` | string | Exact state date and time for which the subscription will be initiated |
| `items[].sub_status` | string | Subscription status (for more info about the statuses, see table below) |
| `items[].sub_iteration_type` | number | Subscription type ID (for more info about the types, see table [Subscription Iteration Types](/marketplaces-and-platforms/lists-statuses/subscription-iteration-types)) |
| `items[].sub_price` | number | Subscription final price. For example, if the price is 50.75 (max 2 decimal points) the value that needs to be sent is 5075 |
| `items[].sub_description` | string | Brief description about the subscription |
| `items[].sub_iterations` | string | Subscription amount of iterations |
| `items[].sub_iterations_completed` | string | Number of iterations completed |
| `items[].sub_iterations_left` | string | Number of iterations left for the subscription |
| `items[].sub_payment_date` | string | The date the payment is completed for each iteration |
| `items[].sub_error_text` | string | If an error occured, it'll be mentioned in this parameter |
| `items[].sub_currency` | string | Currency of subscription |
| `items[].sub_paid` | boolean | Was the subscription paid |
| `items[].sub_buyer_details` | object | |
| `items[].sub_buyer_details.buyer_card_mask` | string | The first 6 and last 4 digits of the used card for the subscription |
| `items[].sub_buyer_details.buyer_name` | string | Buyer's first and last name |
| `items[].sub_buyer_details.buyer_email` | string | Buyer's email |
| `items[].sub_buyer_details.buyer_phone` | string | Buyer's phone number |
| `items[].sub_buyer_details.buyer_social_id` | string | Buyer's social ID number |
| `status_code` | number | Status of the request (0 - success, 1 - error) |
```json
{
"items_count": 1,
"items": [
{
"seller_payme_id": "XXXXXXXX-XXXXXXXX-XXXXXXXX-XXXXXXXX",
"seller_id": "12345",
"sub_payme_id": "XXXXXXXX-XXXXXXXX-XXXXXXXX-XXXXXXXX",
"sub_payme_code": "1234",
"sub_created": "2016-01-01 15:15:15",
"sub_start_date": "2016-01-10 08:00:00",
"sub_prev_date": null,
"sub_next_date": null,
"sub_status": "2",
"sub_iteration_type": "3",
"sub_price": "10000",
"sub_description": "Monthly Test Subscription",
"sub_iterations": "4",
"sub_iterations_completed": "0",
"sub_iterations_left": "4",
"sub_payment_date": "2016-01-02 10:10:10",
"sub_error_text": "",
"sub_currency": "USD",
"sub_paid": true,
"sub_buyer_details": {
"buyer_card_mask": "458045******4580",
"buyer_name": "First Last",
"buyer_email": "buyer@example.com",
"buyer_phone": "0500000001",
"buyer_social_id": "000000001"
}
}
],
"status_code": 0
}
```
- [List Sellers](https://docs-staging.payme.io/payments/query-apis/post-get-sellers): POST /get-sellers — List Sellers
# List Sellers
- Sandbox: `POST https://sandbox.payme.io/api/get-sellers`
- Production: `POST https://live.payme.io/api/get-sellers`
## Credentials
- Request body field `payme_client_key` (required): PayMe Partner Key
- Request body field `seller_payme_id` (optional): Our unique seller ID (MPL). If you are a partner, you can use multiple seller_payme_id attributes to retreive data for these specific sellers
## Overview
You can retreive data on your sellers using this endpoint.
#### Query pagination (more than 500 results)
If you are sending a query and expect to receive more than 500 results, make sure you use this function of Query Pagination.
```json
{
"seller_payme_id": "MPL1DEMO-XXXXXXXX-XXXXXXXX-XXXXXXXX",
...
"page_size": 100, // Max allowed page size is 500
"page": 1
}
```
## Parameters
This endpoint takes no path, query or header parameters.
## Request body
Content type: `application/json`
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `payme_client_key` | string | yes | PayMe Partner Key |
| `seller_payme_id` | string | no | Our unique seller ID (MPL). If you are a partner, you can use multiple seller_payme_id attributes to retreive data for these specific sellers |
| `seller_created_max` | string | no | Latest date and time for which to retrieve sellers. ISO-8601 formatted |
| `seller_created_min` | string | no | Earliest creation date and time for which to retrieve sellers. ISO-8601 formatted |
| `seller_id` | string | no | Merchant's unique seller ID for correlation with us |
| `seller_first_name` | string | no | |
| `seller_last_name` | string | no | First name of the account owner |
| `seller_social_id` | string | no | Last name of the account owner |
| `seller_email` | string | no | Seller's personal email |
| `seller_phone` | string | no | Seller's personal phone |
| `seller_contact_email` | string | no | Seller's contact email that will be displayed to the buyers |
| `seller_contact_phone` | string | no | Seller's contact phone that will be displayed to the buyers |
| `seller_inc` | string | no | |
| `seller_inc_code` | string | no | Seller's business ID (ח.פ, ע.מ) |
| `selelr_merchant_name` | string | no | Seller's merchant name |
| `market_fee` | number | no | A decimal between 0-30 representing the percent of the sale price that is collected for the marketplace (includes VAT) |
| `seller_active` | boolean | no | Seller's active state |
| `seller_approved` | boolean | no | Seller's approval state |
### Request example
```json
{
"payme_client_key": "XXXXXXXX",
"seller_payme_id": "XXXXXXXX-XXXXXXXX-XXXXXXXX-XXXXXXXX",
"seller_created_min": "2016-01-01 00:00:00",
"seller_created_max": "2016-01-02 00:00:00",
"seller_first_name": "First"
}
```
## Code samples
### curl
```bash
curl -X POST 'https://sandbox.payme.io/api/get-sellers' \
-H 'Content-Type: application/json' \
--data-raw '{
"payme_client_key": "XXXXXXXX",
"seller_payme_id": "XXXXXXXX-XXXXXXXX-XXXXXXXX-XXXXXXXX",
"seller_created_min": "2016-01-01 00:00:00",
"seller_created_max": "2016-01-02 00:00:00",
"seller_first_name": "First"
}'
```
### Node.js
```javascript
const response = await fetch("https://sandbox.payme.io/api/get-sellers", {
method: "POST",
headers: {
"Content-Type": "application/json",
},
body: JSON.stringify({
"payme_client_key": "XXXXXXXX",
"seller_payme_id": "XXXXXXXX-XXXXXXXX-XXXXXXXX-XXXXXXXX",
"seller_created_min": "2016-01-01 00:00:00",
"seller_created_max": "2016-01-02 00:00:00",
"seller_first_name": "First"
}),
});
console.log(await response.text());
```
### Python
```python
import requests
response = requests.post(
"https://sandbox.payme.io/api/get-sellers",
json={
"payme_client_key": "XXXXXXXX",
"seller_payme_id": "XXXXXXXX-XXXXXXXX-XXXXXXXX-XXXXXXXX",
"seller_created_min": "2016-01-01 00:00:00",
"seller_created_max": "2016-01-02 00:00:00",
"seller_first_name": "First",
},
)
print(response.text)
```
### PHP
```php
'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;
```
## Responses
### 200 — OK (success)
| Field | Type | Description |
| --- | --- | --- |
| `items_count` | number | Number of sellers |
| `items` | array | |
| `items[].seller_payme_id` | string | Our unique seller ID (MPL) |
| `items[].seller_id` | string | Merchant's unique seller ID for correlation with us |
| `items[].seller_created` | string | Exact creation date and time for which to retrieve sellers. ISO-8601 formatted |
| `items[].seller_active` | boolean | Seller is Active in the system or not |
| `items[].seller_approved` | boolean | Seller is approved in the system (T/F) |
| `items[].seller_approved_date` | string | The date the seller was approved in the system |
| `items[].seller_is_paid_directly` | boolean | Seller is paid directly by PayMe or by the acquirers. (true is paid by the acquirers) |
| `items[].seller_is_discount` | boolean | Seller has a discount rate |
| `items[].seller_withdrawal_plan` | number | Seller withdrawl plan (see `get-withdrawls` API) |
| `items[].seller_withdrawal_date` | string | |
| `items[].seller_personal_details` | object | |
| `items[].seller_personal_details.seller_first_name` | string | First name of the account owner |
| `items[].seller_personal_details.seller_last_name` | string | Last name of the account owner |
| `items[].seller_personal_details.seller_social_id` | string | Seller's social ID number |
| `items[].seller_personal_details.seller_birthdate` | string | Seller birth date |
| `items[].seller_personal_details.seller_gender` | string | Seller gender (0 - Male, 1 - Female) |
| `items[].seller_personal_details.seller_email` | string | Seller's email address` |
| `items[].seller_personal_details.seller_phone` | string | Seller's phone number |
| `items[].seller_business_details` | object | |
| `items[].seller_business_details.seller_inc` | string | |
| `items[].seller_business_details.seller_inc_code` | string | Seller's business ID (ח.פ, ע.מ) |
| `items[].seller_business_details.seller_merchant_name` | string | Seller's merchant name |
| `items[].seller_business_details.seller_site_url` | string | Seller's website URL` |
| `items[].seller_business_details.seller_description` | string | Seller's business description |
| `items[].seller_business_details.seller_retail_type` | string | Seller retail type |
| `items[].seller_business_details.seller_contact_email` | string | Seller contact email |
| `items[].seller_business_details.seller_contact_phone` | string | Seller's contact phone |
| `items[].seller_business_details.seller_bank_account_code` | string | Seller bank code |
| `items[].seller_business_details.seller_bank_account_branch` | string | Seller's bank branch |
| `items[].seller_business_details.seller_bank_account_number` | string | Seller's bank account number |
| `items[].seller_address` | object | |
| `items[].seller_address.seller_address_city` | string | Seller's city address |
| `items[].seller_address.seller_address_street` | string | Seller's address street |
| `items[].seller_address.seller_address_street_number` | string | Seller's street address number |
| `items[].seller_address.seller_address_country` | string | Seller's country address |
| `items[].seller_fees` | object | |
| `items[].seller_fees.fee_market_fee` | string | Market fee |
| `items[].seller_fees.fee_default_processing_fee` | string | Partner's default processing fees |
| `items[].seller_fees.fee_default_processing_charge` | string | Partner's default processing fees |
| `items[].seller_fees.fee_default_discount_fee` | string | Partner's default discount |
| `items[].seller_fees.fee_foreign_processing_fee` | string | Partner's default foreign cards processing fees |
| `items[].seller_fees.fee_foreign_processing_charge` | string | Partner's default foreign processing charges |
| `items[].seller_fees.fee_forcurr_processing_charge` | string | Partner's default foreign currency charges |
| `items[].seller_currencies` | array | Seller enabled currencies |
| `items[].seller_wallets` | object | |
| `items[].seller_wallets.ILS` | object | |
| `items[].seller_wallets.ILS.wallet_currency` | string | Currency of the seller's wallet |
| `items[].seller_wallets.ILS.wallet_total` | string | Wallet total balance |
| `items[].seller_wallets.ILS.wallet_releasable` | string | The balance available for settlement |
| `items[].seller_wallets.USD` | object | ` |
| `items[].seller_wallets.USD.wallet_currency` | string | Wallet currency |
| `items[].seller_wallets.USD.wallet_total` | string | Wallet total balance |
| `items[].seller_wallets.USD.wallet_releasable` | string | The balance available for settlement |
| `items[].seller_monthly_invoices` | object | |
| `items[].seller_monthly_invoices.1234` | object | |
| `items[].seller_monthly_invoices.1234.invoice_reference` | string | Invoice reference number |
| `items[].seller_monthly_invoices.1234.invoice_created` | string | Invoice creation date |
| `items[].seller_monthly_invoices.1234.invoice_doc_number` | string | Invoice document number |
| `items[].seller_monthly_invoices.1234.invoice_url` | string | Invoice file PDF URL |
| `items[].seller_monthly_invoices.1234.invoice_details_url` | string | Invoice details URL |
| `items[].seller_monthly_invoices.2134` | object | |
| `items[].seller_monthly_invoices.2134.invoice_reference` | string | Invoice reference number |
| `items[].seller_monthly_invoices.2134.invoice_created` | string | Invoice creation date |
| `items[].seller_monthly_invoices.2134.invoice_doc_number` | string | Invoice document number |
| `items[].seller_monthly_invoices.2134.invoice_url` | string | Invoice file PDF URL |
| `items[].seller_monthly_invoices.2134.invoice_details_url` | string | Invoice details URL |
| `status_code` | number | 0 for Sucessful requests, 1 for Failed requests |
```json
{
"items_count": 1,
"items": [
{
"seller_payme_id": "XXXXXXXX-XXXXXXXX-XXXXXXXX-XXXXXXXX",
"seller_id": "12345",
"seller_created": "2016-01-01 15:15:15",
"seller_active": true,
"seller_approved": false,
"seller_approved_date": "2016-02-10 00:00:00",
"seller_is_paid_directly": false,
"seller_is_discount": true,
"seller_withdrawal_plan": 1,
"seller_withdrawal_date": null,
"seller_personal_details": {
"seller_first_name": "First",
"seller_last_name": "Last",
"seller_social_id": "999999999",
"seller_birthdate": "1989-05-06",
"seller_gender": "1",
"seller_email": "personal@example.com",
"seller_phone": "0500000005"
},
"seller_business_details": {
"seller_inc": "2",
"seller_inc_code": "123456",
"seller_merchant_name": "Baby Ducks",
"seller_site_url": "www.babyducks.com",
"seller_description": "We are Baby Ducks",
"seller_retail_type": "1",
"seller_contact_email": "contact@example.com",
"seller_contact_phone": "031234567",
"seller_bank_account_code": "12",
"seller_bank_account_branch": "123",
"seller_bank_account_number": "12345"
},
"seller_address": {
"seller_address_city": "City",
"seller_address_street": "Street",
"seller_address_street_number": "10",
"seller_address_country": "IL"
},
"seller_fees": {
"fee_market_fee": "1.50",
"fee_default_processing_fee": "2.50",
"fee_default_processing_charge": "1.20",
"fee_default_discount_fee": "0.50",
"fee_foreign_processing_fee": "3.50",
"fee_foreign_processing_charge": "1.20",
"fee_forcurr_processing_charge": "0.30"
},
"seller_currencies": [
"ILS",
"USD",
"EUR"
],
"seller_wallets": {
"ILS": {
"wallet_currency": "ILS",
"wallet_total": "10000",
"wallet_releasable": "0"
},
"USD": {
"wallet_currency": "USD",
"wallet_total": "0",
"wallet_releasable": "0"
}
},
"seller_monthly_invoices": {
"1234": {
"invoice_reference": "2015-12",
"invoice_created": "2016-01-01",
"invoice_doc_number": "1234",
"invoice_url": "PDF_FILE_URL.pdf",
"invoice_details_url": "https://preprod.paymeservice.com/system/invoice-details-viewer/XXXXXXXX-XXXXXXXX-XXXXXXXX-XXXXXXXX"
},
"2134": {
"invoice_reference": "2016-01",
"invoice_created": "2016-02-01",
"invoice_doc_number": "2134",
"invoice_url": "PDF_FILE_URL.pdf",
"invoice_details_url": "https://preprod.paymeservice.com/system/invoice-details-viewer/XXXXXXXX-XXXXXXXX-XXXXXXXX-XXXXXXXX"
}
}
}
],
"status_code": 0
}
```
### 500 — Internal Server Error (error)
| Field | Type | Description |
| --- | --- | --- |
| `status_code` | number | |
| `status_error_details` | string | |
| `status_additional_info` | string | |
| `status_error_code` | number | |
```json
{
"status_code": 1,
"status_error_details": "שירות לא נמצא",
"status_additional_info": "payme_client_key",
"status_error_code": 200
}
```
- [List Past Withdrawals](https://docs-staging.payme.io/payments/query-apis/post-get-withdrawals): POST /get-withdrawals — List Past Withdrawals
# List Past Withdrawals
- Sandbox: `POST https://sandbox.payme.io/api/get-withdrawals`
- Production: `POST https://live.payme.io/api/get-withdrawals`
## Credentials
- Request body field `payme_client_key` (required): PayMe Partner Key
- Request body field `seller_payme_id` (optional): Our unique seller ID (MPL). If you are a partner, you can use multiple seller_payme_id attributes to retreive data for these specific sellers
## Overview
You can retreive data on withdrawals requested by your sellers using this endpoint.
#### Query pagination (more than 500 results)
If you are sending a query and expect to receive more than 500 results, make sure you use this function of Query Pagination.
```json
{
"seller_payme_id": "MPL1DEMO-XXXXXXXX-XXXXXXXX-XXXXXXXX",
...
"page_size": 100, // Max allowed page size is 500
"page": 1
}
```
## Parameters
This endpoint takes no path, query or header parameters.
## Request body
Content type: `application/json`
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `payme_client_key` | string | yes | PayMe Partner Key |
| `seller_payme_id` | string | no | Our unique seller ID (MPL). If you are a partner, you can use multiple seller_payme_id attributes to retreive data for these specific sellers |
| `seller_id` | string | no | Merchant's unique seller ID for correlation with us |
| `withdrawal_created` | string | no | Exact creation date and time for which to retrieve withdrawals. ISO-8601 formatted |
| `withdrawal_created_min` | string | no | Earliest creation date and time for which to retrieve withdrawals. ISO-8601 formatted |
| `withdrawal_created_max` | string | no | Latest date and time for which to retrieve withdrawals. ISO-8601 formatted |
| `withdrawal_total` | string | no | Withdrawal total amount. For example, if the amount is 50.75 (max 2 decimal points) the value that recieved is 5075 |
| `withdrawal_currency` | string | no | Withdrawal currency. 3-letter ISO 4217 name |
### Request example
```json
{
"payme_client_key": "XXXXXXXX",
"withdrawal_payme_code": "1234"
}
```
## Code samples
### curl
```bash
curl -X POST 'https://sandbox.payme.io/api/get-withdrawals' \
-H 'Content-Type: application/json' \
--data-raw '{
"payme_client_key": "XXXXXXXX",
"withdrawal_payme_code": "1234"
}'
```
### Node.js
```javascript
const response = await fetch("https://sandbox.payme.io/api/get-withdrawals", {
method: "POST",
headers: {
"Content-Type": "application/json",
},
body: JSON.stringify({
"payme_client_key": "XXXXXXXX",
"withdrawal_payme_code": "1234"
}),
});
console.log(await response.text());
```
### Python
```python
import requests
response = requests.post(
"https://sandbox.payme.io/api/get-withdrawals",
json={
"payme_client_key": "XXXXXXXX",
"withdrawal_payme_code": "1234",
},
)
print(response.text)
```
### PHP
```php
'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;
```
## Responses
### 200 — OK (success)
| Field | Type | Description |
| --- | --- | --- |
| `items_count` | number | |
| `items` | array | |
| `items[].seller_payme_id` | string | Our unique seller ID |
| `items[].withdrawal_payme_code` | number | Unique withdrawl PayMe code |
| `items[].withdrawal_created` | string | Withdrwal creation date |
| `items[].withdrawal_currency` | string | Withdrawal currency. 3-letter ISO 4217 name |
| `items[].withdrawal_total` | number | Withdrawl total amount |
| `items[].withdrawal_description` | string | Withdrawl description |
| `status_code` | number | |
```json
{
"items_count": 1,
"items": [
{
"seller_payme_id": "XXXXXXXX-XXXXXXXX-XXXXXXXX-XXXXXXXX",
"withdrawal_payme_code": 10001,
"withdrawal_created": "2016-01-01 15:15:15",
"withdrawal_currency": "USD",
"withdrawal_total": 600000,
"withdrawal_description": "משיכה לבנק"
}
],
"status_code": 0
}
```
### 500 — Internal Server Error (error)
| Field | Type | Description |
| --- | --- | --- |
| `status_code` | number | |
| `status_error_details` | string | |
| `status_additional_info` | string | |
| `status_error_code` | number | |
```json
{
"status_code": 1,
"status_error_details": "Required parameter is missing",
"status_additional_info": "payme_client_key",
"status_error_code": 1
}
```
- [List Future Withdrawals](https://docs-staging.payme.io/payments/query-apis/get-future-withdrawals): POST /get-future-withdrawals — List Future Withdrawals
# List Future Withdrawals
- Sandbox: `POST https://sandbox.payme.io/api/get-future-withdrawals`
- Production: `POST https://live.payme.io/api/get-future-withdrawals`
## Credentials
- Request body field `seller_payme_id` (required): Our unique seller ID (MPL).
You can retreive data on expected future withdrawals of your sellers using this endpoint.
#### Query pagination (more than 500 results)
If you are sending a query and expect to receive more than 500 results, make sure you use this function of Query Pagination.
```json
{
"seller_payme_id": "MPL1DEMO-XXXXXXXX-XXXXXXXX-XXXXXXXX",
...
"page_size": 100, // Max allowed page size is 500
"page": 1
}
```
## Parameters
This endpoint takes no path, query or header parameters.
## Request body
Content type: `application/json`
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `seller_payme_id` | string | yes | Our unique seller ID (MPL). |
| `currency` | string | no | Sale currency. [3-letter ISO 4217 name](https://en.wikipedia.org/wiki/ISO_4217). |
### Request example
```json
{
"seller_payme_id": "MPL1DEMO-XXXXXXXX-XXXXXXXX-XXXXXXXX",
"currency": "ILS"
}
```
## Code samples
### curl
```bash
curl -X POST 'https://sandbox.payme.io/api/get-future-withdrawals' \
-H 'Content-Type: application/json' \
--data-raw '{
"seller_payme_id": "MPL1DEMO-XXXXXXXX-XXXXXXXX-XXXXXXXX",
"currency": "ILS"
}'
```
### Node.js
```javascript
const response = await fetch("https://sandbox.payme.io/api/get-future-withdrawals", {
method: "POST",
headers: {
"Content-Type": "application/json",
},
body: JSON.stringify({
"seller_payme_id": "MPL1DEMO-XXXXXXXX-XXXXXXXX-XXXXXXXX",
"currency": "ILS"
}),
});
console.log(await response.text());
```
### Python
```python
import requests
response = requests.post(
"https://sandbox.payme.io/api/get-future-withdrawals",
json={
"seller_payme_id": "MPL1DEMO-XXXXXXXX-XXXXXXXX-XXXXXXXX",
"currency": "ILS",
},
)
print(response.text)
```
### PHP
```php
'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;
```
## Responses
### 200 — OK (success)
| Field | Type | Description |
| --- | --- | --- |
| `items_count` | integer | Number of withdrawals |
| `items` | array | |
| `items[].start_time` | integer | Date of the previous withdrawal (epoch) |
| `items[].end_time` | integer | Date of the end of the period of the withdrawal (epoch) |
| `items[].created_at` | string | Timestamp of the withdrawal creation |
| `items[].withdrawable` | integer | Indicates if the fund is withdrawable |
| `items[].source` | integer | Source of the withdrawal |
| `items[].source_text` | string | Source of the withdrawal |
| `items[].card_brand` | integer | Card brand |
| `items[].card_brand_text` | string | Card brand |
| `items[].total` | string | Withdrawal total amount |
| `items[].withdrawal_payme_code` | string | Withdrawal code |
| `status_code` | integer | Status of the request (0 - success, 1 - error) |
```json
{
"items_count": 1,
"items": [
{
"start_time": 1687774500,
"end_time": -1,
"created_at": "2023-06-20 14:00:20",
"withdrawable": 1,
"source": 1,
"source_text": "פאיימי",
"card_brand": 1,
"card_brand_text": "אחר",
"total": "156390",
"withdrawal_payme_code": "withdrawal-code"
}
],
"status_code": 0
}
```
- [Aggregated Wallets Data](https://docs-staging.payme.io/payments/query-apis/get-funds-transfer-aggregated): GET /funds-transfer/aggregated — Aggregated Wallets Data
# Aggregated Wallets Data
- Sandbox: `GET https://sandbox.payme.io/api/funds-transfer/aggregated`
- Production: `GET https://live.payme.io/api/funds-transfer/aggregated`
## Credentials
- Query parameter `seller_payme_id` (optional): The specific MPL to be searched for.
## Overview
Using this method, you can retreive data regarding your wallet or wallets for a certain day.
You'll be able to get the following information:
Value | Description
---|---
`outgoing_amount` | The daily outgoing funds amount.
`outgoing_count`| The daily outgoing transactions count.
`ingoing_amount`| The daily ingoing funds amount.
`ingoing_count`|The daily ingoing transactions count.
`daily_withdrawal_amount`| The daily withdrawal amount.
## Parameters
| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `start_date` | query | string | no | The start date of the query. |
| `end_date` | query | string | no | The end date of the query. |
| `seller_payme_id` | query | string | no | The specific MPL to be searched for. |
## Request body
Content type: `application/json`
## Code samples
### curl
```bash
curl -X GET 'https://sandbox.payme.io/api/funds-transfer/aggregated?seller_payme_id=' \
-H 'Content-Type: application/json' \
--data-raw '{}'
```
### Node.js
```javascript
const response = await fetch("https://sandbox.payme.io/api/funds-transfer/aggregated?seller_payme_id=", {
method: "GET",
headers: {
"Content-Type": "application/json",
},
body: JSON.stringify({}),
});
console.log(await response.text());
```
### Python
```python
import requests
response = requests.get(
"https://sandbox.payme.io/api/funds-transfer/aggregated?seller_payme_id=",
json={},
)
print(response.text)
```
### PHP
```php
');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;
```
## Responses
### 200 — OK (success)
| Field | Type | Description |
| --- | --- | --- |
| `status_code` | integer | |
| `page` | integer | |
| `items_total` | integer | |
| `items_per_page` | integer | |
| `start_date` | string | |
| `end_date` | string | |
| `items` | array | |
| `items[].seller_payme_id` | string | |
| `items[].currency` | string | |
| `items[].date` | string | |
| `items[].outgoing_transaction_count` | integer | |
| `items[].outgoing_transaction_amount` | string | |
| `items[].ingoing_transaction_count` | integer | |
| `items[].ingoing_transaction_amount` | string | |
```json
{
"status_code": 0,
"page": 1,
"items_total": 1,
"items_per_page": 1,
"start_date": "2022-05-18",
"end_date": "2022-05-18",
"items": [
{
"seller_payme_id": "MPL90008-90008EXM-EXAMPLE0-EXAMPLE9",
"currency": "ILS",
"date": "2022-05-18 23:30:10",
"outgoing_transaction_count": 10,
"outgoing_transaction_amount": "10002.12",
"ingoing_transaction_count": 12,
"ingoing_transaction_amount": "20000.12"
}
]
}
```
- [List of available banks](https://docs-staging.payme.io/payments/query-apis/get-banks-country-iso-code): GET /banks/{country_iso_code} — List of available banks
# List of available banks
- Sandbox: `GET https://sandbox.payme.io/api/banks/{country_iso_code}`
- Production: `GET https://live.payme.io/api/banks/{country_iso_code}`
## Credentials
- Header `PayMe-Partner-Key` (API key)
## Overview
This API Endpoint will allow you retreive a list of available banks by filtering your request per country.
## Parameters
| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `PayMe-Partner-Key` | header | string | no | Your PayMe's Partner Secret Key |
| `country_iso_code` | path | string | yes | |
## Code samples
### curl
```bash
curl -X GET 'https://sandbox.payme.io/api/banks/' \
-H 'PayMe-Partner-Key: '
```
### Node.js
```javascript
const response = await fetch("https://sandbox.payme.io/api/banks/", {
method: "GET",
headers: {
"PayMe-Partner-Key": "",
},
});
console.log(await response.text());
```
### Python
```python
import requests
response = requests.get(
"https://sandbox.payme.io/api/banks/",
headers={
"PayMe-Partner-Key": "",
},
)
print(response.text)
```
### PHP
```php
');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'PayMe-Partner-Key: ',
],
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;
```
## Responses
### 200 — OK (success)
| Field | Type | Description |
| --- | --- | --- |
| `status_code` | integer | `status_code` = 0 (success) `status_code` = 1 (failure) |
| `items_count` | integer | The total items count in your response |
| `items_per_page` | integer | The total items count per page in your response |
| `country_code` | string | Find the iso codes [here](https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes) |
| `items` | array | The items object - presenting the list of banks |
| `items[].code` | string | Bank code |
| `items[].local_name` | string | Local bank name |
| `items[].international_name` | string | Internal bank name |
```json
{
"status_code": 0,
"items_count": 0,
"items_per_page": 0,
"country_code": "string",
"items": [
{
"code": "string",
"local_name": "string",
"international_name": "string"
}
]
}
```
- [Wallet to Wallet transfers](https://docs-staging.payme.io/payments/query-apis/get-funds-transfer): GET /funds-transfer — Wallet to Wallet transfers
# Wallet to Wallet transfers
- Sandbox: `GET https://sandbox.payme.io/api/funds-transfer`
- Production: `GET https://live.payme.io/api/funds-transfer`
## Credentials
- Request body field `payme_client_key` (required): PayMe Partner Key.
## Overview
This endpoint enable you to receive data of funds transfers between wallets in PayMe.
## Parameters
This endpoint takes no path, query or header parameters.
## Request body
Content type: `application/json`
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `payme_client_key` | string | yes | PayMe Partner Key. |
| `seller_payme_id_origin` | string | no | The MPL of the seller that their wallet will be used to transfer the funds. |
| `seller_payme_id_destination` | string | no | The MPL of the seller that their wallet will receive the funds. |
| `currency` | string | no | Sale currency. 3-letter ISO 4217 name. |
| `start_date` | string | no | The start date of the query. |
| `end_date` | string | no | The end date of the query. |
### Request example
```json
{
"payme_client_key": "XXXXXXXX",
"seller_payme_id_origin": "MPL1DEMO-XXXXXXXX-XXXXXXXX-XXXXXXXX",
"seller_payme_id_destination": "MPL2DEMO-XXXXXXXX-XXXXXXXX-XXXXXXXX",
"currency": "ILS",
"start_date": "2023-05-04",
"end_date": "2023-05-04"
}
```
## Code samples
### curl
```bash
curl -X GET 'https://sandbox.payme.io/api/funds-transfer' \
-H 'Content-Type: application/json' \
--data-raw '{
"payme_client_key": "XXXXXXXX",
"seller_payme_id_origin": "MPL1DEMO-XXXXXXXX-XXXXXXXX-XXXXXXXX",
"seller_payme_id_destination": "MPL2DEMO-XXXXXXXX-XXXXXXXX-XXXXXXXX",
"currency": "ILS",
"start_date": "2023-05-04",
"end_date": "2023-05-04"
}'
```
### Node.js
```javascript
const response = await fetch("https://sandbox.payme.io/api/funds-transfer", {
method: "GET",
headers: {
"Content-Type": "application/json",
},
body: JSON.stringify({
"payme_client_key": "XXXXXXXX",
"seller_payme_id_origin": "MPL1DEMO-XXXXXXXX-XXXXXXXX-XXXXXXXX",
"seller_payme_id_destination": "MPL2DEMO-XXXXXXXX-XXXXXXXX-XXXXXXXX",
"currency": "ILS",
"start_date": "2023-05-04",
"end_date": "2023-05-04"
}),
});
console.log(await response.text());
```
### Python
```python
import requests
response = requests.get(
"https://sandbox.payme.io/api/funds-transfer",
json={
"payme_client_key": "XXXXXXXX",
"seller_payme_id_origin": "MPL1DEMO-XXXXXXXX-XXXXXXXX-XXXXXXXX",
"seller_payme_id_destination": "MPL2DEMO-XXXXXXXX-XXXXXXXX-XXXXXXXX",
"currency": "ILS",
"start_date": "2023-05-04",
"end_date": "2023-05-04",
},
)
print(response.text)
```
### PHP
```php
'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;
```
## Responses
### 200 — OK (success)
| Field | Type | Description |
| --- | --- | --- |
| `status_code` | integer | Status of the request (0 - success, 1 - error) |
| `page` | integer | Page number |
| `currency` | string | Sale currency. [3-letter ISO 4217 name](https://en.wikipedia.org/wiki/ISO_4217). |
| `start_date` | string | The start date of the query. |
| `end_date` | string | The end date of the query. |
| `items_total` | integer | Count of Wallet to Wallet transactions in the chosen period. |
| `items_per_page` | integer | Count of Wallet to Wallet transactions in the page. |
| `items` | array | Detailed Transactions. |
```json
{
"status_code": 0,
"page": 1,
"currency": "ILS",
"start_date": "2023-05-04",
"end_date": "2023-05-04",
"items_total": 0,
"items_per_page": 0,
"items": []
}
```
- [Withdrawal Correlation](https://docs-staging.payme.io/payments/query-apis/post-credit-match): POST /credit-match — Withdrawal Correlation
# Withdrawal Correlation
- Sandbox: `POST https://sandbox.payme.io/api/credit-match`
- Production: `POST https://live.payme.io/api/credit-match`
## Credentials
- Request body field `seller_payme_id` (required): Your unique PayMe seller identifier.
This endpoint retrieves credit match information for a specific seller and withdrawal.
Request Body:
```json
{
"seller_payme_id": "string", //Your unique seller ID
"withdrawal_payme_code": number //The withdrawal number as received from POST get-withdrawals API endpoint
}
```
Parameters:
- `seller_payme_id` (required): The unique identifier for the seller in the Payme system.
- `withdrawal_payme_code` (required): The Payme code for the specific withdrawal.
Successful Response (HTTP 200):
The response includes detailed information about the withdrawal, seller, and associated transactions.
Error Responses (HTTP 500):
1. Seller not found:
```json
{
"status_code": 1,
"status_error_details": "מוכר לא נמצא",
"status_additional_info": "seller_payme_id",
"status_error_code": 251,
"session": "string"
}
```
2. Withdrawal not found:
```json
{
"status_code": 1,
"status_error_details": "משיכה לא נמצאה",
"status_additional_info": number,
"status_error_code": 906,
"session": "string"
}
```
Notes:
- Ensure that the `seller_payme_id` and `withdrawal_payme_code` are valid before making the request.
## Parameters
This endpoint takes no path, query or header parameters.
## Request body
Content type: `application/json`
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `seller_payme_id` | string | yes | Your unique PayMe seller identifier. |
| `withdrawal_payme_code` | integer | yes | Your unique Withdrawal code. |
### Request example
```json
{
"seller_payme_id": "MPL90006-90006EXM-EXAMPLE0-EXAMPLE9",
"withdrawal_payme_code": 1066726
}
```
## Code samples
### curl
```bash
curl -X POST 'https://sandbox.payme.io/api/credit-match' \
-H 'Content-Type: application/json' \
--data-raw '{
"seller_payme_id": "MPL90006-90006EXM-EXAMPLE0-EXAMPLE9",
"withdrawal_payme_code": 1066726
}'
```
### Node.js
```javascript
const response = await fetch("https://sandbox.payme.io/api/credit-match", {
method: "POST",
headers: {
"Content-Type": "application/json",
},
body: JSON.stringify({
"seller_payme_id": "MPL90006-90006EXM-EXAMPLE0-EXAMPLE9",
"withdrawal_payme_code": 1066726
}),
});
console.log(await response.text());
```
### Python
```python
import requests
response = requests.post(
"https://sandbox.payme.io/api/credit-match",
json={
"seller_payme_id": "MPL90006-90006EXM-EXAMPLE0-EXAMPLE9",
"withdrawal_payme_code": 1066726,
},
)
print(response.text)
```
### PHP
```php
'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;
```
## Responses
### 200 — OK (success)
| Field | Type | Description |
| --- | --- | --- |
| `seller_payme_id` | string | The unique PayMe seller identifier. |
| `seller_id` | string | The external Seller ID, provided by the integrator. |
| `withdrawal_payme_code` | integer | The withdrawal unique code. |
| `withdrawal_created` | string | The date the withdrawal was created in timestamp format. |
| `withdrawal_created_epoch` | integer | The date the withdrawal was created in epoch format. |
| `withdrawal_total` | integer | The withdrawal total in cents (agorot). |
| `withdrawal_currency` | string | The withdrawal currency, 3 letter ISO code. |
| `items_count` | integer | The total count of items assembling the withdrawal. (Transactions and Charges) |
| `items` | array | |
| `items[].credit_vas_id` | string | The VAS identifier that was used to create the charge. |
| `items[].sale_remote_id` | string | The external sale identifier. |
| `items[].tran_id` | integer | The entity unique ID. |
| `items[].tran_type` | string | The entity type ID. |
| `items[].tran_created` | string | The date the entity was created on in timestamp format. |
| `items[].tran_created_epoch` | string | The date the entity was created in Epoch format. |
| `items[].tran_total` | integer | The entity total value, in cents (Agorot) |
| `items[].tran_total_after_deduction` | integer | Total after deduction (will be equal to total by default). |
| `items[].tran_currency` | string | The currency of the entity. |
| `items[].tran_installments` | integer | The installments count of the transaction. |
| `items[].tran_description` | string | The description of the entity. |
| `items[].tran_remote_id` | string | The remote ID given by the integrator. |
| `items[].tran_voucher` | string | The voucher of the transaction. |
| `items[].sale_payme_code` | integer | The unique PayMe sale identifer. |
| `items[].sale_buyer_name` | string | The buyer name of the transaction. |
| `status_code` | integer | Status code. `0` - Successful request. `1` - Failed request. |
| `session` | string | The unique session |
```json
{
"seller_payme_id": "MPL90006-90006EXM-EXAMPLE0-EXAMPLE9",
"seller_id": "il-110110738-1677599477",
"withdrawal_payme_code": 1066726,
"withdrawal_created": "2024-07-28 12:29:40",
"withdrawal_created_epoch": 1722158980,
"withdrawal_total": 285511,
"withdrawal_currency": "ILS",
"items_count": 10,
"items": [
{
"credit_vas_id": "VASL1677-599477XY-YKWVZACW-IWQ3BG6Y",
"sale_remote_id": "rVrUy44C75ZShMORPNGkz9MVK",
"tran_id": 191208278,
"tran_type": "102",
"tran_created": "2024-07-24 21:14:33",
"tran_created_epoch": "1721844873",
"tran_total": -140,
"tran_total_after_deduction": -140,
"tran_currency": "ILS",
"tran_installments": 1,
"tran_description": "עמוד תשלום - סטודיו דוצ׳ה Processing Charge",
"tran_remote_id": "rVrUy44C75ZShMORPNGkz9MVK",
"tran_voucher": "6003289",
"sale_payme_code": 61974223,
"sale_buyer_name": "ליאור צוק"
},
{
"credit_vas_id": "VASL1677-599477HY-GUKISPF6-AHGOSEWS",
"sale_remote_id": "rVrUy44C75ZShMORPNGkz9MVK",
"tran_id": 191208274,
"tran_type": "102",
"tran_created": "2024-07-24 21:14:33",
"tran_created_epoch": "1721844873",
"tran_total": -1578,
"tran_total_after_deduction": -1578,
"tran_currency": "ILS",
"tran_installments": 1,
"tran_description": "עמוד תשלום - סטודיו דוצ׳ה Advancement services",
"tran_remote_id": "rVrUy44C75ZShMORPNGkz9MVK",
"tran_voucher": "6003289",
"sale_payme_code": 61974223,
"sale_buyer_name": "ליאור צוק"
},
{
"credit_vas_id": "VASL1677-599477LB-MLQDCS8F-KTGONSZE",
"sale_remote_id": "rVrUy44C75ZShMORPNGkz9MVK",
"tran_id": 191208270,
"tran_type": "102",
"tran_created": "2024-07-24 21:14:33",
"tran_created_epoch": "1721844873",
"tran_total": -2953,
"tran_total_after_deduction": -2953,
"tran_currency": "ILS",
"tran_installments": 1,
"tran_description": "עמוד תשלום - סטודיו דוצ׳ה Processing Fee",
"tran_remote_id": "rVrUy44C75ZShMORPNGkz9MVK",
"tran_voucher": "6003289",
"sale_payme_code": 61974223,
"sale_buyer_name": "ליאור צוק"
},
{
"credit_vas_id": null,
"sale_remote_id": "rVrUy44C75ZShMORPNGkz9MVK",
"tran_id": 224152597,
"tran_type": "1",
"tran_created": "2024-07-24 21:14:33",
"tran_created_epoch": "1721844873",
"tran_total": 155000,
"tran_total_after_deduction": 155000,
"tran_currency": "ILS",
"tran_installments": 1,
"tran_description": "עמוד תשלום - סטודיו דוצ׳ה ",
"tran_remote_id": "rVrUy44C75ZShMORPNGkz9MVK",
"tran_voucher": "6003289",
"sale_payme_code": 61974223,
"sale_buyer_name": "ליאור צוק"
},
{
"credit_vas_id": "VASL1677-599477LB-MLQDCS8F-KTGONSZE",
"sale_remote_id": "r36GeI5Crm2JORFnXANDmAHpm",
"tran_id": 191334587,
"tran_type": "102",
"tran_created": "2024-07-25 21:15:20",
"tran_created_epoch": "1721931320",
"tran_total": -2667,
"tran_total_after_deduction": -2667,
"tran_currency": "ILS",
"tran_installments": 1,
"tran_description": "עמוד תשלום - סטודיו דוצ׳ה Processing Fee",
"tran_remote_id": "r36GeI5Crm2JORFnXANDmAHpm",
"tran_voucher": "7001937",
"sale_payme_code": 62018574,
"sale_buyer_name": "Ofri Katz"
},
{
"credit_vas_id": null,
"sale_remote_id": "r36GeI5Crm2JORFnXANDmAHpm",
"tran_id": 224212542,
"tran_type": "1",
"tran_created": "2024-07-25 21:15:20",
"tran_created_epoch": "1721931320",
"tran_total": 140000,
"tran_total_after_deduction": 140000,
"tran_currency": "ILS",
"tran_installments": 1,
"tran_description": "עמוד תשלום - סטודיו דוצ׳ה ",
"tran_remote_id": "r36GeI5Crm2JORFnXANDmAHpm",
"tran_voucher": "7001937",
"sale_payme_code": 62018574,
"sale_buyer_name": "Ofri Katz"
},
{
"credit_vas_id": "VASL1677-599477HY-GUKISPF6-AHGOSEWS",
"sale_remote_id": "r36GeI5Crm2JORFnXANDmAHpm",
"tran_id": 191334591,
"tran_type": "102",
"tran_created": "2024-07-25 21:15:21",
"tran_created_epoch": "1721931321",
"tran_total": -1425,
"tran_total_after_deduction": -1425,
"tran_currency": "ILS",
"tran_installments": 1,
"tran_description": "עמוד תשלום - סטודיו דוצ׳ה Advancement services",
"tran_remote_id": "r36GeI5Crm2JORFnXANDmAHpm",
"tran_voucher": "7001937",
"sale_payme_code": 62018574,
"sale_buyer_name": "Ofri Katz"
},
{
"credit_vas_id": "VASL1677-599477XY-YKWVZACW-IWQ3BG6Y",
"sale_remote_id": "r36GeI5Crm2JORFnXANDmAHpm",
"tran_id": 191334595,
"tran_type": "102",
"tran_created": "2024-07-25 21:15:21",
"tran_created_epoch": "1721931321",
"tran_total": -140,
"tran_total_after_deduction": -140,
"tran_currency": "ILS",
"tran_installments": 1,
"tran_description": "עמוד תשלום - סטודיו דוצ׳ה Processing Charge",
"tran_remote_id": "r36GeI5Crm2JORFnXANDmAHpm",
"tran_voucher": "7001937",
"sale_payme_code": 62018574,
"sale_buyer_name": "Ofri Katz"
},
{
"credit_vas_id": "VASL1677-599477Q0-DC5MSVNQ-H7JBRQQZ",
"sale_remote_id": "rZsj2JQB3rVSfeLsVyPEAmH8H",
"tran_id": 191290928,
"tran_type": "102",
"tran_created": "2024-07-25 10:38:05",
"tran_created_epoch": "1721893085",
"tran_total": -293,
"tran_total_after_deduction": -293,
"tran_currency": "ILS",
"tran_installments": 1,
"tran_description": "עמוד תשלום - סטודיו דוצ׳ה שירות 3DSecure",
"tran_remote_id": "rZsj2JQB3rVSfeLsVyPEAmH8H",
"tran_voucher": null,
"sale_payme_code": 62211761,
"sale_buyer_name": ""
},
{
"credit_vas_id": "VASL1677-599477Q0-DC5MSVNQ-H7JBRQQZ",
"sale_remote_id": "rZsj2JQB3rVSfeLsVyPEAmH8H",
"tran_id": 191291080,
"tran_type": "102",
"tran_created": "2024-07-25 10:41:03",
"tran_created_epoch": "1721893263",
"tran_total": -293,
"tran_total_after_deduction": -293,
"tran_currency": "ILS",
"tran_installments": 1,
"tran_description": "עמוד תשלום - סטודיו דוצ׳ה שירות 3DSecure",
"tran_remote_id": "rZsj2JQB3rVSfeLsVyPEAmH8H",
"tran_voucher": null,
"sale_payme_code": 62211926,
"sale_buyer_name": ""
}
],
"status_code": 0,
"session": "FIV3zo4M"
}
```
### 500 — Internal Server Error (error)
| Field | Type | Description |
| --- | --- | --- |
| `status_code` | integer | Status code. `0` - Successful request. `1` - Failed request. |
| `status_error_details` | string | Error description. |
| `status_additional_info` | integer | Error additional information. |
| `status_error_code` | integer | PayMe error code. |
| `session` | string | PayMe session ID. |
```json
{
"status_code": 1,
"status_error_details": "משיכה לא נמצאה",
"status_additional_info": 1066726222,
"status_error_code": 906,
"session": "FhT3aXe7"
}
```
## Get Transaction Statistics
- [Get Transaction Statistics](https://docs-staging.payme.io/payments/get-transaction-statistics/post-get-transaction-statistics): POST /get-transaction-statistics — Get Transaction Statistics
# Get Transaction Statistics
- Sandbox: `POST https://sandbox.payme.io/api/get-transaction-statistics`
- Production: `POST https://live.payme.io/api/get-transaction-statistics`
## Credentials
- Request body field `payme_client_key` (optional): PayMe Partner Key.
This endpoint enable to get transaction average, based on the chosen period (`time_resolution`), transaction's status (pending/validated) and currency.
## Parameters
This endpoint takes no path, query or header parameters.
## Request body
Content type: `application/json`
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `payme_client_key` | string | no | PayMe Partner Key. |
| `time_resolution` | string | no | The selected period. |
| `start_date` | string | no | The start date of the selected period. |
| `end_date` | string | no | The start date of the selected period. |
| `transaction_status` | array | no | Filter the status of the transactions that will take into account in the calculation. For all the transaction statuses see [Transaction Statuses](/marketplaces-and-platforms/lists-statuses/transaction-statuses). Example: pending |
| `sale_currency` | array | no | Sale currency. [3-letter ISO 4217 name](https://en.wikipedia.org/wiki/ISO_4217). Example: ILS |
### Request example
```json
{
"payme_client_key": "XXXXXXXX",
"time_resolution": "day",
"start_date": "YYYY-MM-DD HH:MM:SS",
"end_date": "YYYY-MM-DD HH:MM:SS",
"transaction_status": [
"pending",
"validated"
],
"sale_currency": [
"ILS",
"USD"
]
}
```
## Code samples
### curl
```bash
curl -X POST 'https://sandbox.payme.io/api/get-transaction-statistics' \
-H 'Content-Type: application/json' \
--data-raw '{
"payme_client_key": "XXXXXXXX",
"time_resolution": "day",
"start_date": "YYYY-MM-DD HH:MM:SS",
"end_date": "YYYY-MM-DD HH:MM:SS",
"transaction_status": [
"pending",
"validated"
],
"sale_currency": [
"ILS",
"USD"
]
}'
```
### Node.js
```javascript
const response = await fetch("https://sandbox.payme.io/api/get-transaction-statistics", {
method: "POST",
headers: {
"Content-Type": "application/json",
},
body: JSON.stringify({
"payme_client_key": "XXXXXXXX",
"time_resolution": "day",
"start_date": "YYYY-MM-DD HH:MM:SS",
"end_date": "YYYY-MM-DD HH:MM:SS",
"transaction_status": [
"pending",
"validated"
],
"sale_currency": [
"ILS",
"USD"
]
}),
});
console.log(await response.text());
```
### Python
```python
import requests
response = requests.post(
"https://sandbox.payme.io/api/get-transaction-statistics",
json={
"payme_client_key": "XXXXXXXX",
"time_resolution": "day",
"start_date": "YYYY-MM-DD HH:MM:SS",
"end_date": "YYYY-MM-DD HH:MM:SS",
"transaction_status": [
"pending",
"validated",
],
"sale_currency": [
"ILS",
"USD",
],
},
)
print(response.text)
```
### PHP
```php
'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;
```
## Responses
### 200 — OK (success)
| Field | Type | Description |
| --- | --- | --- |
| `status_code` | integer | Status of the request (0 - success, 1 - error) |
| `start_date` | string | The start date of the selected period. |
| `end_date` | string | The end date of the selected period. |
| `time_resolution` | string | The selected period. |
| `statistics` | object | |
| `statistics.pending` | object | Transaction statistics in the chosen status |
| `statistics.pending.ILS` | array | Transaction statistics in the chosen currency |
| `statistics.pending.ILS[].sum` | integer | |
| `statistics.pending.ILS[].count` | integer | |
| `statistics.pending.ILS[].average` | integer | |
```json
{
"status_code": 0,
"start_date": "YYYY-MM-DD HH:MM:SS",
"end_date": "YYYY-MM-DD HH:MM:SS",
"time_resolution": "day",
"statistics": {
"pending": {
"ILS": [
{
"sum": 0,
"count": 0,
"average": 0
},
{
"sum": 0,
"count": 0,
"average": 0
}
]
}
}
}
```
## Get Transaction Data
- [Get Transaction Data](https://docs-staging.payme.io/payments/get-transaction-data/post-get-transaction-data): POST /get-transaction-data — Get Transaction Data
# Get Transaction Data
- Sandbox: `POST https://sandbox.payme.io/api/get-transaction-data`
- Production: `POST https://live.payme.io/api/get-transaction-data`
## Credentials
- Header `PayMe-Public-Key` (API key)
## Overview
This endpoint enable to get transaction, based on the transaction status, sale status, sale currency and sale payment method.
## Parameters
| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `PayMe-Public-Key` | header | string | no | XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX |
## Request body
Content type: `application/json`
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `transaction_type` | integer | no | Filter the type of the transactions that will be presented. For all the transaction types see [Transaction Types](/marketplaces-and-platforms/lists-statuses/transaction-types). |
| `transaction_status` | string | no | Filter the status of the transactions that will be presented. For all the transaction statuses see [Transaction Statuses](/marketplaces-and-platforms/lists-statuses/transaction-statuses). |
| `sale_status` | array | no | Filter the status of the sales that will be presented. For all the sale statuses see [Sale Statuses](/marketplaces-and-platforms/lists-statuses/sale-statuses). Example: "initial" |
| `sale_currency` | array | no | Sale currency. [3-letter ISO 4217 name](https://en.wikipedia.org/wiki/ISO_4217). Example: "ILS" |
| `sale_payment_method` | array | no | the Payment method used to pay the sale. For all the payment methods see [Available Payment Methods](/payments/direct-api/available-payment-methods). Example: "credit-card" |
### Request example
```json
{
"transaction_type": 1,
"transaction_status": "validated",
"sale_status": [
"completed"
],
"sale_currency": [
"ILS"
],
"sale_payment_method": [
"credit-card"
]
}
```
## Code samples
### curl
```bash
curl -X POST 'https://sandbox.payme.io/api/get-transaction-data' \
-H 'Content-Type: application/json' \
-H 'PayMe-Public-Key: ' \
--data-raw '{
"transaction_type": 1,
"transaction_status": "validated",
"sale_status": [
"completed"
],
"sale_currency": [
"ILS"
],
"sale_payment_method": [
"credit-card"
]
}'
```
### Node.js
```javascript
const response = await fetch("https://sandbox.payme.io/api/get-transaction-data", {
method: "POST",
headers: {
"Content-Type": "application/json",
"PayMe-Public-Key": "",
},
body: JSON.stringify({
"transaction_type": 1,
"transaction_status": "validated",
"sale_status": [
"completed"
],
"sale_currency": [
"ILS"
],
"sale_payment_method": [
"credit-card"
]
}),
});
console.log(await response.text());
```
### Python
```python
import requests
response = requests.post(
"https://sandbox.payme.io/api/get-transaction-data",
headers={
"PayMe-Public-Key": "",
},
json={
"transaction_type": 1,
"transaction_status": "validated",
"sale_status": [
"completed",
],
"sale_currency": [
"ILS",
],
"sale_payment_method": [
"credit-card",
],
},
)
print(response.text)
```
### PHP
```php
'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Content-Type: application/json',
'PayMe-Public-Key: ',
],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;
```
## Responses
### 200 — OK (success)
| Field | Type | Description |
| --- | --- | --- |
| `status_code` | integer | Status of the request (0 - success, 1 - error) |
| `items` | array | The transactions details. |
| `items_count` | integer | Count of the transactions. |
```json
{
"status_code": 0,
"items": [],
"items_count": 0
}
```
## iOS SDK
- [iOS SDK](https://docs-staging.payme.io/payments/ios-sdk/ios-sdk): You can use the PayMe (Isracard Global) iOS SDK to implement payments on iOS devices. The guide covers building and importing the PMLib.framework, initializing the SDK, and integrating the Isracard Global API to pay a sale, pay a subscription, and capture a buyer.
You can use our iOS SDK to implement our solution for iOS devices.
[See the project repository on Bitbucket](https://bitbucket.org/paymeservice/isracard-global-ios-sdk/src)
## Getting Started
### Get the Isracard Global package
Build the framework from sources:
1. Open the Isracard Global project.
2. Build the project.
3. The new framework is generated automatically in the Products directory of `PMLib.xcodeproj`: `PMLib.framework`.
4. Right-click → **Show in Finder** to get the path of the framework.
### Import the Isracard Global SDK framework
1. Open the project that needs to import the framework.
2. Select your project's **Targets → General → Embedded Binaries** (or **Build Phases → Embedded Frameworks**).
3. Press **Add (+)** and go to the path of `PMLib.framework`.
4. Build the project.
## Initialize the SDK
Extend your `Application` and initialize the SDK.
Header file:
```objc
#import
#import
#define SELLERKEY @"/* Your seller_payme_id */"
#define WEBSERVICE [PayMe sharedInstant:SELLERKEY stage:STAGING]
#define CONTANTS [Contants sharedInstant]
@interface Contants : NSObject
+ (id)sharedInstant;
- (void)showHub:(BOOL)isShow;
- (void)showMessage:(NSString *)message;
```
Source file:
```objc
#import "Contants.h"
#import
#import "MBProgressHUD.h"
#import "AppDelegate.h"
static Contants *_contants;
@implementation Contants
+ (id)sharedInstant{
static dispatch_once_t onceToken;
dispatch_once(&onceToken, ^{
_contants = [[Contants alloc]init];
});
return _contants;
}
- (void)showHub:(BOOL)isShow{
if (isShow) {
[MBProgressHUD showHUDAddedTo:APPDELEGATE.window animated:YES];
}else{
[MBProgressHUD hideAllHUDsForView:APPDELEGATE.window animated:YES];
}
}
- (void)showMessage:(NSString *)message{
UIAlertView *alertView = [[UIAlertView alloc]initWithTitle:@"" message:message delegate:nil cancelButtonTitle:@"Ok" otherButtonTitles:nil, nil];
[alertView show];
}
```
## Integrate with the Isracard Global API
Each API request requires appropriate `PayMeRequest` and `TransactionListener` instances.
### Pay Sale
First, generate a sale on your server side (for more details see the `generate-sale` API) and send the `payme_sale_id` to your application. Then you can create a `PaySaleRequest` and fire it:
```objc
PaySaleRequest *request = [[PaySaleRequest alloc] init];
//payme_sale_id - Required - From your server
request.paymeSaleId = /* payme_sale_id */;
//Installments - Required
request.installments = installments;
//ID - Required Only for israeli cards
request.buyerSocialID = buyerSocialID;
//Email - Required
request.buyerEmail = buyerEmail;
//Name - Required
request.buyerName = buyerName;
//Credit Card Number - Required
request.creditCardNumber = creditCardNumber;
//CreditCard CVV - Required
request.creditCardCVV = creditCardCVV;
//Credit Card Expiration - Required
request.creditCardExp = creditCardExp;
[CONTANTS showHub:YES];
[WEBSERVICE paySale:request success:^(PaySaleResponse *responseObject) {
[CONTANTS showHub:NO];
if(responseObject != nil)
{
//Handle success request
}
} failure:^(PayMeError *error) {
[CONTANTS showHub:NO];
if(error != nil)
{
//Handle failed request
}
}];
```
### Pay Subscription
First, generate a subscription on your server (for more details see the `generate-subscription` API) and send the `sub_payme_id` to your application. Then you can create a `PaySubscriptionRequest` and fire it:
```objc
PaySubscriptionRequest *request = [[PaySubscriptionRequest alloc] init];
//Name - Required
request.buyerName = buyerName;
//ID - Required Only for israeli cards
request.buyerSocialId = buyerSocialId;
//Phone
request.buyerPhone = buyerPhone;
//Email - Required
request.buyerEmail = buyerEmail;
//sub_payme_id - Required - From your server
request.subPaymeId = /* sub_payme_id */;
//Credit Card Number - Required
request.creditCardNumber = creditCardNumber;
//CreditCard CVV - Required
request.creditCardCVV = creditCardCVV;
//Credit Card Expiration - Required
request.creditCardExp = creditCardExp;
[CONTANTS showHub:YES];
[WEBSERVICE paySubscription:request success:^(PaySubscriptionResponse *responseObject) {
[CONTANTS showHub:NO];
if(responseObject != nil)
{
//Handle success request
}
} failure:^(PayMeError *error) {
[CONTANTS showHub:NO];
if(error != nil)
{
//Handle failed request
}
}];
```
### Capture Buyer
```objc
CaptureBuyerRequest *request = [[CaptureBuyerRequest alloc] init];
//Name - Required
request.buyerName = buyerName;
//Phone - Required
request.buyerPhone = buyerPhone;
//Email - Required
request.buyerEmail = buyerEmail;
//ID - Required Only for israeli cards
request.buyerSocialId = buyerSocialId;
//SellerID - Required
request.sellerPaymeId = /* Your seller_payme_id */;
//Permanent
request.buyerIsPermanent = buyerIsPermanent;
//Credit Card Number - Required
request.creditCardNumber = creditCardNumber;
//CreditCard CVV - Required
request.creditCardCvv = creditCardCVV;
//Credit Card Expiration - Required
request.creditCardExp = creditCardExp;
[CONTANTS showHub:YES];
[WEBSERVICE captureBuyer:request success:^(CaptureBuyerResponse *responseObject) {
[CONTANTS showHub:NO];
if(responseObject != nil)
{
//Handle success request
}
} failure:^(PayMeError *error) {
//do something
[CONTANTS showHub:NO];
if(error != nil)
{
//Handle failed request
}
}];
```