Getting Started

Credentials, environments, a first sale, callbacks, errors and retries

• 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.
• 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.
• 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.
• 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/<id>; 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.
• 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.
• 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.
• 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.
• 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.