Payments API reference

API reference for accepting payments with PayMe — sales via hosted payment page, hosted fields or direct API, tokens, subscriptions, refunds and captures, 3D Secure, invoices and point-of-sale. Start with Getting Started for credentials, environments and a first sale.

Getting Started

• Start Here: PayMe's Payments API lets platforms and merchants accept payments via a hosted payment page, hosted fields (JSAPI) or a direct API, with tokenization, subscriptions, refunds and capture, 3D Secure, invoices and POS. Read in order: Authentication, Environments (sandbox.payme.io/api, live.payme.io/api), Test Cards, Quickstart, Callbacks; then Errors and Idempotency & Retries. Requests are JSON, callbacks form-encoded; amounts in minor units (500-4000000); send language en. Other APIs: B2B Payments, Keep, Products & Customers. To build an integration, follow the AI Toolkit.
• 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, B2B Payments and Products & Customers authentication is documented with those APIs.
• Environments: PayMe has two environments: Sandbox at https://sandbox.payme.io/api/ and Production at https://live.payme.io/api/; they are separate accounts and each issues its own keys. sale_url is the environment's host (without /api) plus /sale/generate/<id>; use it exactly as returned. 3D Secure redirect pages are served from paymeservice.com. Browser scripts load from cdn.paymeservice.com (also cdn.payme.io); Hosted Fields uses testMode: true for the sandbox. Test data is on Test Cards and Payment Methods.
• Integration Options: PayMe offers three integration options: the Hosted Payment Page (your server calls generate-sale and the buyer pays on PayMe's sale_url; PayMe carries PCI DSS), Hosted Fields JSAPI (PayMe's card iframes inside your own form; the browser gets a token and your server charges it with generate-sale and buyer_key; your CSP must allow cdn.payme.io and hf.payme.io), and the Direct API (your server sends card details to pay-sale; PCI DSS level 1 required and PayMe must enable it).
• Test Cards and Payment Methods: Use only in the sandbox. Main cards (expiry 12/30, Social ID 008336174): 4557430402053431 CVV 200 (international, one installment), 375516193000090 CVV 0957, 5326105300985846 CVV 658 (local, ILS only). Decline cards such as 4000000000000002 return HTTP 200 with status_code 1 and codes 20004 or 21001-21008. 3D Secure challenges foreign cards, amounts from the account's threshold, or 3 or more installments; challenge test card 4918914107195005 with OTP 555. Also Apple Pay cards, Israeli direct debit, SEPA and BACS accounts and test-seller values.
• 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 partner's default callback URL, if one is set). Any status below 400 counts as delivered; each attempt times out after 5 s; up to 3 attempts within about 90 seconds, 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.
• Callback types reference: Sale callback URL, signed except sale-create: sale-create (opt-in), sale-complete, sale-authorized, sale-failure (per attempt), refund (refunds and voids), sale-chargeback, sale-chargeback-refund, sale-paid, sale-il-direct-debit-update. sub_callback_url, unsigned: sub-create, sub-active, sub-iteration-success, sub-iteration-skipped, sub-failure, sub-pause, sub-cancel, sub-complete. Partner URL, unsigned: seller-create, seller-update, seller-approve, point-of-sale-action-pair-update, point-of-sale-action-authenticate-update, withdrawal-complete, charge-complete. B2B: payment-contract-*.
• 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, capture-sale and other payment calls share a per-seller rate limit, 100 requests per 10 s by default.
• Get API access and go live: from sandbox to production: Launch path for the PayMe Payments API. Keys: seller_payme_id (MPL, server only) and the public key (browser) are on Admin → API & Integration; install the API service if it's missing. Partners also get payme_client_key and a client password. Sandbox: Switch to test account → Create test account; no account: register at paid.co.il (הרשמה). Test on sandbox.payme.io/api; go live on live.payme.io/api with production keys, testMode false, the production Apple Pay domain file, services active (720), public callback URLs (21) and get-sales checks.
• Move your PayMe account to a new website or platform: A PayMe account isn't tied to a website: sales, payouts, services and API keys (MPL and public key, per environment) carry over. Plugin sites (Wix, Shopify and similar): follow the plugin's setup or contact PayMe support. Own site: keys on Admin → API & Integration (install the API service if missing), MPL on the server only, Quickstart, go-live. Errors 200, 251/163, 1, 21, 720. Several sites: send sale_callback_url and sale_return_url on every sale; Apple Pay and Google Pay on your own page are set up per domain. Automations: webhook URL as sale_callback_url, confirm with get-sales.

Hosted Payment Page

• Create a sale (hosted payment page): POST /generate-sale
• Create a multi-method checkout sale: POST /generate-sale

Hosted Fields - JSAPI

• Charge a Hosted Fields token: POST /generate-sale

Direct API

• Pay a sale: POST /pay-sale

iOS SDK

Android SDK

Point of Sale (POS)

• Order POS devices: POST /vas-enable
• Create a POS payment: POST /sales
• Refund a POS sale: PUT /sales/{sale_guid}

Post Sale Actions

• Refund a sale: POST /refund-sale
• Void an authorization: POST /refund-sale
• Capture an authorized sale: POST /capture-sale
• Cancel a multi-payment page: POST /cancel-template

Apple Pay

• Enable Apple Pay for a seller: POST /vas-enable
• Create a Apple Pay sale: POST /generate-sale

Google Pay

• Enable Google Pay for a seller: POST /vas-enable
• Create a Google Pay sale: POST /generate-sale

IL Direct Debit

• Create an Israeli direct debit authorization: POST /generate-sale
• Charge an Israeli direct debit authorization: POST /generate-sale

Tokenization

• Save a card as a token: POST /capture-buyer-token
• Save a card (token sale): POST /generate-sale
• Get the buyer key of a sale or subscription: POST /get-buyer-key
• Create a partner-level token: POST /sellers/{mpl}/tokens

Subscriptions

• Create a subscription: POST /generate-subscription
• Pay a subscription: POST /pay-subscription
• Cancel a subscription: POST /cancel-subscription
• Pause a subscription: POST /pause-subscription
• Resume a subscription: PATCH /subscriptions/{sub_payme_id}/resume
• Update a subscription's price: PATCH /subscriptions/{sub_payme_id}/set-price

Invoices

• Create a document: POST /documents
• Get a document: GET /documents/{document_id}
• List documents: GET /documents

Generate a Sale with 3D Secure

• Create a sale with 3D Secure: POST /generate-sale

Standalone 3D Secure service

• Start 3D Secure authentication: POST /sales/{payme_sale_id}/3ds
• Resolve a 3D Secure hash: GET /sales/{payme_sale_id}/3ds/{hash_3dsecure}

Merchants Management

• Create a seller: POST /create-seller
• Update a seller: POST /update-seller
• Upload seller files: POST /upload-seller-files
• List a seller's services: POST /get-vas-seller
• Withdraw a seller's balance: POST /withdraw-balance
• List a seller's public keys: GET /sellers/{seller_payme_id}/public-keys
• List business fields: GET /business-fields
• Attach a saved card to a seller: POST /add-card-to-seller

Buyers Management

• Get a buyer: GET /buyers/{buyer_guid}

Query APIs

• List sales: POST /get-sales
• List transactions: POST /get-transactions
• List subscriptions: POST /get-subscriptions
• List sellers: POST /get-sellers
• List withdrawals: POST /get-withdrawals
• List future withdrawals: POST /get-future-withdrawals
• List banks: GET /banks/{country_iso_code}

Codes & Statuses

• Sale Types: PayMe sale types: the number returned by queries, the name sent in callbacks, and the sale_type value to send in requests (sale, authorize, token, seller-token, credit, template, multi-capture).
• Sale Statuses: Reference list of sale statuses, from initial and completed to refunded, chargeback and voided, with what each means.
• Understand the sale lifecycle: A sale starts initial. Payment moves it to completed (sale-complete), or authorized for sale_type authorize (sale-authorized). A failed attempt moves it to failed (sale-failure per attempt), but failed isn't final: sale_url stays payable while initial or failed, until sale_expiry_seconds passes (then HTTP 403 and error 367; the status doesn't change). Capture: completed. Void: voided or partial-void. Refund: refunded, or partial-refund (it stays so). Chargeback: chargeback or partial-chargeback; reversal: completed. Confirm with get-sales and send sale_status: initial is hidden by default.
• Transaction Types: Reference list of transaction type numbers, such as Sale, Token, Authorization/Void and Balance.
• Transaction Statuses: Reference list of transaction statuses, from pending and validated to refunds, chargebacks and voids.
• Subscription statuses: Reference list of subscription statuses (sub_status): initial, active, paused, failed, canceled, completed, and failed with a retry pending.
• Subscription iteration types: Reference list of subscription billing intervals (sub_iteration_type): daily, weekly, monthly, yearly and quarterly.
• Bank authorization statuses: Values of authorization_status in the Israeli direct-debit callback, and what each does to the buyer: opened, failed, canceled, moved, reactivated and more.
• Banks in Israel: Israeli bank codes and names, used as seller_bank_code on create-seller and update-seller (unknown code: error 106), with the branch and account-number validation rules (error 165) and the sandbox test bank 54.
• Document types: Values of doc_type for Create a document: work order, delivery note, invoices, invoice receipt, credit invoice, receipts and price offer.