# Start Here Building with an AI agent? Start at https://docs.payme.io/agents.md ## Related - [Authentication](/payments/getting-started/authentication) - [Environments](/payments/getting-started/environments) - [Test Cards and Payment Methods](/payments/getting-started/test-cards-and-payment-methods) - [Quickstart](/payments/getting-started/quickstart) - [Callbacks](/payments/getting-started/callbacks) - [Errors](/payments/getting-started/errors) - [Idempotency and Retries](/payments/getting-started/idempotency-and-retries) - [Integration Options](/payments/getting-started/integration-options) PayMe's Payments API is "designed to allow platforms to offer a full payment solution as part of their product." You `POST` JSON to PayMe's URLs and get JSON replies, so you can use any programming language. ## Building an integration? The [AI Toolkit](/agents) has the whole procedure, for a person or an AI agent: your test account, the rules, each step in order, test cases and reference code, the go-live checklist and an answer for each common error. It starts by helping you choose between integrating as a [partner](/agents/partner/payme-partner-integration) and as a [direct seller](/agents/seller/payme-seller-integration). Start there if you are building, and use the pages here as the reference. ## Read these first Read these five pages, in this order, before you write integration code. | # | Page | What you learn | |---|------|----------------| | 1 | [Authentication](/payments/getting-started/authentication) | Which credential goes where — `seller_payme_id` (MPL), `payme_client_key`, the public key — and how to open a sandbox account and find your keys. | | 2 | [Environments](/payments/getting-started/environments) | Sandbox vs production base URLs, and the hosts you will see in `sale_url`, 3D Secure redirects and browser scripts. | | 3 | [Test Cards and Payment Methods](/payments/getting-started/test-cards-and-payment-methods) | Sandbox test cards (including cards that force each decline), wallet cards, bank accounts and test-seller values. | | 4 | [Quickstart](/payments/getting-started/quickstart) | One complete sale in the sandbox with `curl`: create a sale, pay it, receive the callback, refund it. | | 5 | [Callbacks](/payments/getting-started/callbacks) | How PayMe notifies your server, what the payload contains, and how to handle it. | After those, read [Errors](/payments/getting-started/errors) and [Idempotency and retries](/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 an `application/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. ## What PayMe offers With the Payments API 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](/payments) | 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](/b2b-payments/contracts/overview) | Payment contracts (send a payment or a payment request between businesses) and transfers between wallets. | | [Keep](/keep/partner-authorization/prerequisites) | APIs for PayMe's accounting product: sellers, income documents (invoices, receipts), expenses, tax and VAT. | | [Products and Customers](/products-and-customers/authentication/hosts-authentication-and-errors) | Create, list, update and delete products and customers. | Mobile: open the [Hosted Payment Page](/payments/hosted-payment-page) in a secure in-app browser. Legacy [iOS](/payments/ios-sdk/ios-sdk) and [Android](/payments/android-sdk/android-sdk) SDKs remain available but aren't recommended for new integrations. ## Integration options There are three ways to take a payment: the **Hosted Payment Page** (the buyer pays on PayMe's secure page, `sale_url`, shown as an IFRAME or a redirect), **Hosted Fields (JSAPI)** (payment fields embedded in your page with PayMe's JavaScript library) and the **Direct API** (your server sends card details to PayMe). [Integration Options](/payments/getting-started/integration-options) compares them. ## Payment methods The full list of `sale_payment_method` values, with their codes, is on [Available Payment Methods](/payments/wallets-apms). Use `multi` to let the buyer choose on one checkout page. If `sale_payment_method` is omitted, the sale is created as `credit-card`; `multi` must be sent explicitly. 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: a fixed number from `1` to `12`, or `1NN` (`102`–`112`) to let the buyer choose up to NN, for example `106` for up to 6. Fixed values above 12 are accepted when the sale is created, but the payment fails unless PayMe has enabled more installments on your account. Installments are for card payments only (`credit-card` or `multi`). ## 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`. - PayMe does not convert currencies: each sale is paid out in the currency it was cleared in, so there is no conversion fee. A payout in USD needs a USD bank account on the record. - ILS only: Israeli direct debit, Bit, and any sale with more than one installment. Which currencies each sandbox test card accepts is on [Test Cards and Payment Methods](/payments/getting-started/test-cards-and-payment-methods). ## 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. ## Amounts and limits - 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 a different range for a partner, and it then applies to all of that partner's sellers. Out of range returns error `352`. Token sales (`sale_type` `token` or `seller-token`) are always created with a price of `100`: send any numeric `sale_price` (a missing or non-numeric value returns `352`). Token sales are not range-checked. A partial refund amount (`sale_refund_amount`) must be within the same range. - An authorization (J5) reserves funds for up to 168 hours; capture is allowed once. - Rate limit: `generate-sale`, `pay-sale`, `capture-sale` and several other payment calls share a per-seller limit; over the limit returns HTTP 429. The default values and the full list are under [Rate limits](/payments/getting-started/idempotency-and-retries#rate-limits). PayMe can set different limits for a partner. To request a higher limit, write to ; what to include in the request is listed under [Rate limits](/payments/getting-started/idempotency-and-retries#rate-limits). ## 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. PCI compliant and want to use the direct credit-card API? [Let PayMe know](https://payme.io/contact-us/). - Tokenization reduces the scope of PCI DSS requirements for recurring payments. - 3D Secure is supported, including as a standalone service. ## Contact Our [Status Page](https://status.payme.io/) is available 24/7, you can now subscribe and receive notifications regarding maintenance, issues or general updates to your inbox. - Integration and API questions: . - Help center (merchant dashboard, plugins, account questions): . - General contact form: - Adding Google Pay card networks: `support@payme.io` - Keep API keys come from your Account Manager; see [Keep prerequisites](/keep/partner-authorization/prerequisites). ## Machine-readable docs Every page is available as Markdown by appending `.md` to its URL; each API section publishes one OpenAPI file at `///openapi.json`, and `//openapi.json` returns a 404 that lists them; the site index for AI agents is `/llms.txt`. ## Identifiers | Shape | Field | Meaning | |-------|-------|---------| | `MPL….-….-….-….` | `seller_payme_id` | The seller (merchant) identifier, also called the MPL. It is an identifier that authenticates seller-level calls, not an API key, but treat it as a credential. | | `SALE….` | `payme_sale_id` | Sale ID; `payme_sale_code` is its short numeric form. | | `SUB….` | `sub_payme_id` | Subscription ID; `sub_payme_code` is its short numeric form. | | `BUYER….` | `buyer_key` | Saved-card token. Secret: encrypt it at rest; it replaces the card number. | | `TRAN….` | `payme_transaction_id` | Transaction ID (reporting, withdrawals). | | `VASL….` | `vas_payme_id` | Value-added-service ID. | | free string | `transaction_id`, `subscription_id` | Your own references, echoed back. Not enforced unique. | | `411111******1111` | `buyer_card_mask` | First 6 and last 4 digits of the card. |