# Payments

> 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.

## Machine-readable

- [Payments OpenAPI spec](https://docs-staging.payme.io/payments/openapi.json): the OpenAPI document (also as [YAML](https://docs-staging.payme.io/payments/openapi.yaml))
- [Payments tool definitions](https://docs-staging.payme.io/api/v1/projects/payments/api/tools.json): one function-calling tool per endpoint
- [Payments full text](https://docs-staging.payme.io/payments/llms-full.txt): every Payments page in one file
- Markdown: append `.md` to any page URL for that page as Markdown, or request the page URL with `Accept: text/markdown`
- Source: append `.yaml` to an endpoint page URL (a line that reads `METHOD path — summary`) for its source YAML; guide pages have no YAML

## 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.
- [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.
- [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.
- [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/<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](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.
- [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.
- [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.
- [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.

## 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.
- [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.
- [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.
- [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.
- [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)

## Hosted Payment Page

- [Generate Payment](https://docs-staging.payme.io/payments/hosted-payment-page/post-generate-sale): POST /generate-sale — Generate Payment
- [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.

## 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.

## 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.
- [Pay Sale](https://docs-staging.payme.io/payments/direct-api/post-pay-sale): POST /pay-sale — Pay Sale

## 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
- [Pair New Device](https://docs-staging.payme.io/payments/point-of-sale-pos/post-pair): POST /vas/pos/pair — Pair New Device
- [Authenticate New Device](https://docs-staging.payme.io/payments/point-of-sale-pos/post-authenticate): POST /vas/pos/authenticate — Authenticate New Device
- [New POS Payment](https://docs-staging.payme.io/payments/point-of-sale-pos/post-payment): POST /sales — New POS Payment
- [Refund POS Sale](https://docs-staging.payme.io/payments/point-of-sale-pos/put-sales): PUT /sales — Refund POS Sale

## Post Sale Actions

- [Refund Sale](https://docs-staging.payme.io/payments/post-sale-actions/post-refund-sale): POST /refund-sale — Refund Sale
- [Void Sale](https://docs-staging.payme.io/payments/post-sale-actions/void-sale): How to call POST /refund-sale for Post Sale Actions.
- [Capture Sale](https://docs-staging.payme.io/payments/post-sale-actions/post-capture-sale): POST /capture-sale — Capture Sale
- [Cancel Multi Payment Page](https://docs-staging.payme.io/payments/post-sale-actions/post-cancel-template): POST /cancel-template — Cancel Multi Payment Page

## 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.
- [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.

## 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.
- [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.

## 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 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.

## Subscriptions

- [Generate](https://docs-staging.payme.io/payments/subscriptions/post-generate-subscription): POST /generate-subscription — Generate
- [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.
- [Pay](https://docs-staging.payme.io/payments/subscriptions/post-generate-subscription-2): POST /pay-subscription — Pay
- [Cancel](https://docs-staging.payme.io/payments/subscriptions/postcancel-subscription): POST /cancel-subscription — Cancel
- [Pause](https://docs-staging.payme.io/payments/subscriptions/post-pause-subscription): POST /pause-subscription — Pause
- [Resume](https://docs-staging.payme.io/payments/subscriptions/patch-subscriptions-sub-payme-id-resume): PATCH /subscriptions/{sub_payme_id}/resume — Resume
- [Update Price](https://docs-staging.payme.io/payments/subscriptions/patch-subscriptions-sub-id-set-price): PATCH /subscriptions/{sub_id}/set-price — Update Price

## Tokenization

- [Capture Buyer Token](https://docs-staging.payme.io/payments/tokenization/post-capture-buyer-token): POST /capture-buyer-token — Capture Buyer Token
- [Generate Sale with Token](https://docs-staging.payme.io/payments/tokenization/post-generate-sale-tokenization): How to call POST /generate-sale for Tokenization.
- [Get Buyer Key](https://docs-staging.payme.io/payments/tokenization/post-get-buyer-key): POST /get-buyer-key — Get Buyer Key
- [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

## Merchants Management

- [Create Seller](https://docs-staging.payme.io/payments/merchants-management/post-create-seller): POST /create-seller — Create Seller
- [Update Seller](https://docs-staging.payme.io/payments/merchants-management/post-update-seller): POST /update-seller — Update Seller
- [Upload Seller Files](https://docs-staging.payme.io/payments/merchants-management/post-upload-seller-files): POST /upload-seller-files — Upload Seller Files
- [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
- [Withdraw Balance](https://docs-staging.payme.io/payments/merchants-management/post-withdraw-balance): POST /withdraw-balance — Withdraw Balance
- [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
- [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
- [Create Individual](https://docs-staging.payme.io/payments/merchants-management/post-sellers-mpl-key-individuals): POST /sellers/{mpl_key}/individuals — Create Individual
- [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
- [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 Partner Data](https://docs-staging.payme.io/payments/merchants-management/get-partners): GET /partners — Get Partner Data
- [GET Mids](https://docs-staging.payme.io/payments/merchants-management/get-sellers-mpl-key-mids): GET /sellers/{mpl_key}/mids — GET Mids
- [Business Fields](https://docs-staging.payme.io/payments/merchants-management/get-business-fields): GET /business-fields — Business Fields

## Buyers Management

- [Get Customer Details](https://docs-staging.payme.io/payments/buyers-management/get-buyers-guid): GET /buyers/{buyer_guid} — Get Customer Details

## 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.

## 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
- [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

## Invoices

- [Create Document](https://docs-staging.payme.io/payments/invoices/post-create-invoice): POST /documents — Create Document
- [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
- [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
- [Query Existing Documents](https://docs-staging.payme.io/payments/invoices/get-documents): GET /documents — Query Existing Documents

## Query APIs

- [List Sales](https://docs-staging.payme.io/payments/query-apis/post-get-sales): POST /get-sales — List Sales
- [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.
- [List Transactions](https://docs-staging.payme.io/payments/query-apis/post-get-transactions): POST /get-transactions — List Transactions
- [List Subscriptions](https://docs-staging.payme.io/payments/query-apis/post-get-subscriptions): POST /get-subscriptions — List Subscriptions
- [List Sellers](https://docs-staging.payme.io/payments/query-apis/post-get-sellers): POST /get-sellers — List Sellers
- [List Past Withdrawals](https://docs-staging.payme.io/payments/query-apis/post-get-withdrawals): POST /get-withdrawals — List Past Withdrawals
- [List Future Withdrawals](https://docs-staging.payme.io/payments/query-apis/get-future-withdrawals): POST /get-future-withdrawals — List Future Withdrawals
- [Aggregated Wallets Data](https://docs-staging.payme.io/payments/query-apis/get-funds-transfer-aggregated): GET /funds-transfer/aggregated — Aggregated Wallets Data
- [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
- [Wallet to Wallet transfers](https://docs-staging.payme.io/payments/query-apis/get-funds-transfer): GET /funds-transfer — Wallet to Wallet transfers
- [Withdrawal Correlation](https://docs-staging.payme.io/payments/query-apis/post-credit-match): POST /credit-match — Withdrawal Correlation

## 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 Data

- [Get Transaction Data](https://docs-staging.payme.io/payments/get-transaction-data/post-get-transaction-data): POST /get-transaction-data — Get Transaction Data

## 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.