# Payments API overview Building with an AI agent? Start at https://docs.payme.io/agents.md ## Related - [Authentication and environments](/payments/getting-started/authentication) - [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) - [Create a sale (hosted payment page)](/payments/hosted-payment-page/post-generate-sale) - [Build your own checkout form with Hosted Fields](/accepting-payments/checkout-and-in-person/hosted-fields-jsapi-guide) - [Go live: from sandbox to production](/accepting-payments/get-started/go-live) - [Move your PayMe account to a new website or platform](/accepting-payments/get-started/move-to-a-new-website) 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. The [Accepting Payments](/accepting-payments) guides take you through the launch and later moves: [Go live: from sandbox to production](/accepting-payments/get-started/go-live), [Move your PayMe account to a new website or platform](/accepting-payments/get-started/move-to-a-new-website), and the [Build your own checkout form with Hosted Fields](/accepting-payments/checkout-and-in-person/hosted-fields-jsapi-guide) for your own checkout form. Building a platform or marketplace? Begin with [Start here: build a platform or marketplace on PayMe](/marketplaces-and-platforms/start-here/how-platforms-work). ## Read these first Read these four pages, in this order, before you write integration code. | # | Page | What you learn | |---|------|----------------| | 1 | [Authentication and environments](/payments/getting-started/authentication) | Which credential goes where — `seller_payme_id` (MPL), `payme_client_key`, the public key — how to open a sandbox account and find your keys, sandbox vs production base URLs, and the hosts you will see in `sale_url`, 3D Secure redirects and browser scripts. | | 2 | [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. | | 3 | [Quickstart](/payments/getting-started/quickstart) | One complete sale in the sandbox with `curl`: create a sale, pay it, receive the callback, refund it. | | 4 | [Callbacks](/payments/getting-started/callbacks) | How PayMe notifies your server, every callback type, 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/getting-started/overview) | Payment contracts (send a payment or a payment request between businesses) and transfers between wallets. | | [Keep](/keep/partner-authorization/overview) | APIs for PayMe's accounting product: sellers, income documents (invoices, receipts), expenses, tax and VAT. | | [Products & Customers](/products-and-customers/getting-started/overview) | 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. They differ in who renders the card form and how much of PCI DSS falls on you. | Option | How it works | Choose it when | Trade-offs | |---|---|---|---| | [Hosted Payment Page](/payments/hosted-payment-page/post-generate-sale) | Your server calls `generate-sale`; the buyer pays on PayMe's page (`sale_url`) in an iframe or a redirect. | You want the fastest integration, every payment method on one page (`multi`), and PayMe to carry PCI DSS. | Limited control over the page design. | | [Hosted Fields (JSAPI)](/accepting-payments/checkout-and-in-person/hosted-fields-jsapi-guide) | PayMe's card inputs (iframes) sit inside your own form; the browser gets a token and your server charges it with `generate-sale` and `buyer_key`. | You want your own checkout design without card data touching your servers. | More front-end work; your Content Security Policy must allow `cdn.payme.io` and `hf.payme.io`. | | [Direct API](/payments/direct-api) | Your server sends card details to `pay-sale`. | You are PCI DSS level 1 compliant and need full control. | You carry PCI DSS compliance; PayMe must enable the API for you. | ## Payment methods The full list of `sale_payment_method` values 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 from 13 to `36` are accepted when the sale is created, but the payment fails unless PayMe has enabled more installments on your account; any other value returns error `351`. More than one installment is for card payments only (`credit-card`, `multi` or `pos`). ## 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. How the limit works 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 authentication and environments](/keep/partner-authorization/authentication). ## 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. |