# PayMe API Documentation

> Developer documentation for PayMe, an Israeli payments provider: the Payments API for accepting card, wallet and bank payments through a hosted payment page, hosted fields or a direct API, plus the B2B Payments, Keep accounting and Products & Customers APIs, with sandbox and production environments.

## Start here

- [AI Toolkit](https://docs.payme.io/agents): Everything an AI agent needs to integrate with PayMe: skills, the MCP server, reference code, procedures, checklists, error answers and setup for each tool.
- [Start Here](https://docs.payme.io/payments/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](https://docs.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, B2B Payments and Products & Customers authentication is documented with those APIs.
- [Environments](https://docs.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/; 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.
- [Test Cards and Payment Methods](https://docs.payme.io/payments/getting-started/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](https://docs.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.payme.io/payments/getting-started/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.
- [Errors](https://docs.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.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, capture-sale and other payment calls share a per-seller rate limit, 100 requests per 10 s by default.

## Machine-readable

- [Accepting Payments full text](https://docs.payme.io/accepting-payments/llms-full.txt): every Accepting Payments page in one file
- [Marketplaces & Platforms full text](https://docs.payme.io/marketplaces-and-platforms/llms-full.txt): every Marketplaces & Platforms page in one file
- [Payments — Hosted Payment Page OpenAPI spec](https://docs.payme.io/payments/hosted-payment-page/openapi.json): the section's OpenAPI document (also as [YAML](https://docs.payme.io/payments/hosted-payment-page/openapi.yaml))
- [Payments — Hosted Fields - JSAPI OpenAPI spec](https://docs.payme.io/payments/hosted-fields-jsapi/openapi.json): the section's OpenAPI document (also as [YAML](https://docs.payme.io/payments/hosted-fields-jsapi/openapi.yaml))
- [Payments — Direct API OpenAPI spec](https://docs.payme.io/payments/direct-api/openapi.json): the section's OpenAPI document (also as [YAML](https://docs.payme.io/payments/direct-api/openapi.yaml))
- [Payments — Point of Sale (POS) OpenAPI spec](https://docs.payme.io/payments/point-of-sale-pos/openapi.json): the section's OpenAPI document (also as [YAML](https://docs.payme.io/payments/point-of-sale-pos/openapi.yaml))
- [Payments — Post Sale Actions OpenAPI spec](https://docs.payme.io/payments/post-sale-actions/openapi.json): the section's OpenAPI document (also as [YAML](https://docs.payme.io/payments/post-sale-actions/openapi.yaml))
- [Payments — Apple Pay OpenAPI spec](https://docs.payme.io/payments/apple-pay/openapi.json): the section's OpenAPI document (also as [YAML](https://docs.payme.io/payments/apple-pay/openapi.yaml))
- [Payments — Google Pay OpenAPI spec](https://docs.payme.io/payments/google-pay/openapi.json): the section's OpenAPI document (also as [YAML](https://docs.payme.io/payments/google-pay/openapi.yaml))
- [Payments — IL Direct Debit OpenAPI spec](https://docs.payme.io/payments/il-direct-debit/openapi.json): the section's OpenAPI document (also as [YAML](https://docs.payme.io/payments/il-direct-debit/openapi.yaml))
- [Payments — Tokenization OpenAPI spec](https://docs.payme.io/payments/tokenization/openapi.json): the section's OpenAPI document (also as [YAML](https://docs.payme.io/payments/tokenization/openapi.yaml))
- [Payments — Subscriptions OpenAPI spec](https://docs.payme.io/payments/subscriptions/openapi.json): the section's OpenAPI document (also as [YAML](https://docs.payme.io/payments/subscriptions/openapi.yaml))
- [Payments — Invoices OpenAPI spec](https://docs.payme.io/payments/invoices/openapi.json): the section's OpenAPI document (also as [YAML](https://docs.payme.io/payments/invoices/openapi.yaml))
- [Payments — Generate a Sale with 3D Secure OpenAPI spec](https://docs.payme.io/payments/generate-a-sale-with-3d-secure/openapi.json): the section's OpenAPI document (also as [YAML](https://docs.payme.io/payments/generate-a-sale-with-3d-secure/openapi.yaml))
- [Payments — Standalone 3D Secure service OpenAPI spec](https://docs.payme.io/payments/standalone-3d-secure-service/openapi.json): the section's OpenAPI document (also as [YAML](https://docs.payme.io/payments/standalone-3d-secure-service/openapi.yaml))
- [Payments — Merchants Management OpenAPI spec](https://docs.payme.io/payments/merchants-management/openapi.json): the section's OpenAPI document (also as [YAML](https://docs.payme.io/payments/merchants-management/openapi.yaml))
- [Payments — Buyers Management OpenAPI spec](https://docs.payme.io/payments/buyers-management/openapi.json): the section's OpenAPI document (also as [YAML](https://docs.payme.io/payments/buyers-management/openapi.yaml))
- [Payments — Query APIs OpenAPI spec](https://docs.payme.io/payments/query-apis/openapi.json): the section's OpenAPI document (also as [YAML](https://docs.payme.io/payments/query-apis/openapi.yaml))
- [Payments tool definitions](https://docs.payme.io/api/v1/projects/payments/api/tools.json): one function-calling tool per endpoint
- [Payments full text](https://docs.payme.io/payments/llms-full.txt): every Payments page in one file
- [B2B Payments — Contracts OpenAPI spec](https://docs.payme.io/b2b-payments/contracts/openapi.json): the section's OpenAPI document (also as [YAML](https://docs.payme.io/b2b-payments/contracts/openapi.yaml))
- [B2B Payments — Wallets OpenAPI spec](https://docs.payme.io/b2b-payments/wallets/openapi.json): the section's OpenAPI document (also as [YAML](https://docs.payme.io/b2b-payments/wallets/openapi.yaml))
- [B2B Payments tool definitions](https://docs.payme.io/api/v1/projects/b2b-payments/api/tools.json): one function-calling tool per endpoint
- [B2B Payments full text](https://docs.payme.io/b2b-payments/llms-full.txt): every B2B Payments page in one file
- [Keep — Seller API OpenAPI spec](https://docs.payme.io/keep/seller-api/openapi.json): the section's OpenAPI document (also as [YAML](https://docs.payme.io/keep/seller-api/openapi.yaml))
- [Keep — Partners API OpenAPI spec](https://docs.payme.io/keep/partners-api/openapi.json): the section's OpenAPI document (also as [YAML](https://docs.payme.io/keep/partners-api/openapi.yaml))
- [Keep tool definitions](https://docs.payme.io/api/v1/projects/keep/api/tools.json): one function-calling tool per endpoint
- [Keep full text](https://docs.payme.io/keep/llms-full.txt): every Keep page in one file
- [Products and Customers — Authentication OpenAPI spec](https://docs.payme.io/products-and-customers/authentication/openapi.json): the section's OpenAPI document (also as [YAML](https://docs.payme.io/products-and-customers/authentication/openapi.yaml))
- [Products and Customers — Products OpenAPI spec](https://docs.payme.io/products-and-customers/products/openapi.json): the section's OpenAPI document (also as [YAML](https://docs.payme.io/products-and-customers/products/openapi.yaml))
- [Products and Customers — Customers OpenAPI spec](https://docs.payme.io/products-and-customers/customers/openapi.json): the section's OpenAPI document (also as [YAML](https://docs.payme.io/products-and-customers/customers/openapi.yaml))
- [Products and Customers tool definitions](https://docs.payme.io/api/v1/projects/products-and-customers/api/tools.json): one function-calling tool per endpoint
- [Products and Customers full text](https://docs.payme.io/products-and-customers/llms-full.txt): every Products and Customers page in one file
- [AI Toolkit full text](https://docs.payme.io/agents/llms-full.txt): every AI Toolkit page in one file
- [All documentation, full text](https://docs.payme.io/llms-full.txt): every page in one file
- [MCP server](https://docs.payme.io/mcp): Model Context Protocol over Streamable HTTP (MCP protocol 2026-07-28, and 2025-11-25 or earlier) — search the docs, read pages, endpoints and OpenAPI specs. It needs an MCP client, not a web fetch (a GET answers 405). A chat app generally needs a person to add this URL in its settings; a coding agent with a command line can often register it itself. Without that, read each page's Markdown version, or the normal page if your tool can't open it. Setup for each tool: the AI Toolkit page
- [Skills catalog](https://docs.payme.io/.well-known/agent-skills/index.json): installable agent skills, each one a page of these docs (`npx skills add https://docs.payme.io/`)
- [Integration kit](https://docs.payme.io/integration-kit/index.json): every file of the reference code and test cases, with its address relative to this folder
- [Search API](https://docs.payme.io/api/v1/search?q=): GET with `q=<query>`; returns matching pages as JSON
- CLI: `npx -p @payme-io/docs-cli payme-docs` — with an API key, read, edit, add and manage these docs from a terminal, CI or an AI agent: `get` a page as an editable document, change it, `update --dry-run` to check, then `update` (refused if someone else changed it meanwhile); usage: the package README (`@payme-io/docs-cli` on npm). Without a key, read them through the Markdown URLs, MCP or the search API
- 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

## Accepting Payments

How-to guides for accepting payments with PayMe: checkout and in-person payments, Apple Pay, Google Pay, Israeli direct debit, capture, saved cards, 3D Secure and reporting.

### Checkout and In-Person

- [Hosted Payment Page options](https://docs.payme.io/accepting-payments/checkout-and-in-person/hosted-payment-page-options): Pre-fill PayMe's hosted payment page with the buyer's details, read the parameters of the success redirect to sale_return_url, and show sale_url in an iframe.
- [Hosted Fields JSAPI guide](https://docs.payme.io/accepting-payments/checkout-and-in-person/hosted-fields-jsapi-guide): Add PayMe Hosted Fields to your own checkout: how the flow works, a complete minimal page, five working examples, charging the token from your server, and the full JavaScript API reference with every error shape.
- [Template sales (one link, many payments)](https://docs.payme.io/accepting-payments/checkout-and-in-person/multi-payment-page): A template sale is one payment link that many buyers can pay; each payment creates its own sale. Create it with generate-sale and sale_type template; close it with cancel-template or sale_expiry_seconds.
- [Take in-person payments with a POS device](https://docs.payme.io/accepting-payments/checkout-and-in-person/point-of-sale): For partners. Order POS devices with vas-enable (extend_items in vas_data adds devices). PayMe pairs new devices; to pair yourself call pos/pair (payme_client_key, seller_payme_id, pos_id, terminal_id, optional name), then pos/authenticate with the 6-digit verification_code. Callbacks: point-of-sale-action-pair-update, -authenticate-update. Pay: POST /sales with payment.method pos, pos_id, currency; a decline is HTTP 200 status_code 1; 26020 means still verifying, wait for the callback. Refund: PUT /sales/{id} with payment.action refund. pos/transmit returns acknowledge_number and report.
- [Let the buyer choose how to pay](https://docs.payme.io/accepting-payments/checkout-and-in-person/let-the-buyer-choose): Send sale_payment_method: multi to generate-sale (default is credit-card). The card form is always shown. Apple Pay, Google Pay and Bit appear only if the seller's service is active and installments is 1, 0 or 102-112; fixed 2-12 leaves card only. Wallet buttons need a browser that supports them; Bit is ILS only; capture_buyer keeps card and Apple Pay (if set up). Wallets and Bit pay in one payment. Callbacks carry the method used in sale_payment_method; get-sales keeps multi, get-transactions has transaction_payment_method. Not a template sale.
- [Accept payments in a mobile app](https://docs.payme.io/accepting-payments/checkout-and-in-person/mobile-apps): Mobile app checkout: the app calls your server; your server calls generate-sale with the MPL and returns sale_url; the app opens it in SFSafariViewController (iOS) or Chrome Custom Tabs (Android), not a WebView. sale_return_url must be a public http(s) URL (myapp:// fails with error 21): use an HTTPS page that hands back with Universal Links/App Links or a button. Handle a closed browser. Confirm with the sale-complete callback and get-sales (sale_status completed, sale_price). Test wallets in the in-app browser on real devices. The iOS and Android SDKs are legacy.

### Payment Methods

- [Accept Apple Pay](https://docs.payme.io/accepting-payments/payment-methods/apple-pay): Accept Apple Pay on PayMe's Hosted Payment Page, or show the Apple Pay button on your own page: host PayMe's domain file, register the domains with vas-enable, create the sale and call appleSale().
- [Accept Google Pay](https://docs.payme.io/accepting-payments/payment-methods/google-pay): Accept Google Pay on PayMe's Hosted Payment Page, or render the Google Pay button on your own page with googleSale(): setup, the payment result including 3D Secure, errors and testing.
- [Israeli Direct Debit](https://docs.payme.io/accepting-payments/payment-methods/israeli-direct-debit): Collect an Israeli direct debit authorization (mandate) with generate-sale and sale_type token, then charge the bank account with the returned token (buyer_key). Covers the callbacks and timing of each step.
- [Accept Bit payments](https://docs.payme.io/accepting-payments/payment-methods/bit): Bit runs on PayMe's payment page only. Enable it: the seller installs Bit from the dashboard app store, or a partner calls vas-enable (status_code 2 means PayMe completes it); without it generate-sale returns 720. Create the sale with sale_payment_method: bit (or multi), currency ILS, one payment (351), no capture_buyer (4). The buyer scans a QR code or opens the Bit app and approves. sale-complete on success; sale-failure with 23001 rejected, 23002 canceled, 23003 expired; the same sale_url stays payable. Refund with refund-sale.
- [Accept PayPal payments](https://docs.payme.io/accepting-payments/payment-methods/paypal): PayPal sales settle in the seller's own PayPal account, not the PayMe balance: no withdrawals, no market_fee, refunds paid from PayPal. Activation: contact PayMe Partners (partners@payme.io); without it generate-sale returns 720. Create the sale with generate-sale, sale_payment_method paypal, and send sale_callback_url, sale_return_url and cancel_url. Redirect the buyer to sale_url (not an iframe). One payment only (351), no capture_buyer (4), not on multi. Authorize: capture-sale or multi-capture; void the whole authorization only. PayPal disputes don't reach PayMe.

### Capture and Saved Cards

- [Authorize now, capture later](https://docs.payme.io/accepting-payments/capture-and-saved-cards/capture-sale): Place a hold on the buyer's card, then charge it within 7 days with capture-sale, or release it with refund-sale.
- [Capture an authorization in several parts](https://docs.payme.io/accepting-payments/capture-and-saved-cards/multi-capture): Multi-capture: charge an authorized card or PayPal sale in several parts, each a new sale linked to the authorization.
- [Save a card with a token sale](https://docs.payme.io/accepting-payments/capture-and-saved-cards/create-payment-with-buyer-key-token): Moved. Saving a buyer's card as a token (buyer_key) and charging it later is covered in the guide Save a card and charge it later: /accepting-payments/capture-and-saved-cards/save-a-card-and-charge-it-later
- [Build recurring billing with subscriptions](https://docs.payme.io/accepting-payments/capture-and-saved-cards/build-recurring-billing): generate-subscription: status 1 with sub_url, or status 2 with a permanent buyer_key. A job charges each iteration from sub_start_date; each attempt is a sale_type 3 sale; success sends sub-iteration-success with payme_sale_id. List a subscription's sales with get-sales sale_type 3 + sale_parent_code = sub_payme_code. Card check fails: status 4, no retry. Renewal fails: status 7, daily retry, 7 attempts, then 5 + sub-cancel. Pause skips iterations; a paused subscription can't be canceled (305). set-price changes future charges. No wallets.
- [Save a card and charge it later](https://docs.payme.io/accepting-payments/capture-and-saved-cards/save-a-card-and-charge-it-later): Save a card as a buyer_key: capture_buyer: 1 on generate-sale (charge and save), sale_type: token (save, no charge), Hosted Fields tokenize() or capture-buyer-token (PCI). capture-buyer-token is single-use unless buyer_is_permanent: true; a used token gives 604. buyer_is_private: true = one seller; default = any seller of the partner, and get-buyer-key then needs payme_client_key (603). Charge: generate-sale + buyer_key, at once, no CVV, no 3D Secure; a decline is HTTP 200 with status_code 1. Store buyer_key encrypted, server-side.

### 3D Secure

- [3D Secure as a service](https://docs.payme.io/accepting-payments/3d-secure/3d-secure-as-a-service): Run PayMe's 3D Secure 2 authentication as its own API call, without charging the card, and use the result with PayMe or another gateway.
- [3DS with Hosted Fields](https://docs.payme.io/accepting-payments/3d-secure/3ds-with-hosted-fields): Run 3D Secure on a Hosted Fields token: collect the browser data with PayMe.clientData, pay the sale with pay-sale and meta_data_jwt, and handle the challenge redirect and the result.
- [How 3D Secure works on PayMe](https://docs.payme.io/accepting-payments/3d-secure/how-3d-secure-works): PayMe runs 3D Secure 2 on a card payment when the seller has the 3D Secure service (PayMe enables it), the card brand is supported (not Discover, JCB or Isracard) and a rule selects it: a foreign card, 3+ installments, an amount at or above the account's threshold (minor units, no currency conversion), the account's own rules, or services 3DSecure active:true. active:false can't skip the system rules. Hosted Fields and the Direct API must send meta_data_jwt to pay-sale, or 3D Secure is skipped silently. A challenge returns status_code 5 and redirect_url. A failed check returns 21017.

### After the Sale

- [Handle chargebacks](https://docs.payme.io/accepting-payments/after-the-sale/handle-chargebacks): A chargeback is a payment the buyer's issuer takes back; the issuer decides. PayMe sends sale-chargeback (sale_status chargeback or partial-chargeback; inquiry_number, inquiry_code, card_last_four_digits, vas_3ds_exists) and emails the seller. The amount is taken from the PayMe balance; a handling fee may apply under the agreement and isn't returned automatically. Respond as the email describes, within its deadline; there is no chargeback API. A reversal sends sale-chargeback-refund. refund-sale on a charged-back sale returns 305. get-transactions lists chargeback rows.
- [Issue invoices and receipts for your sales](https://docs.payme.io/accepting-payments/after-the-sale/issue-invoices-and-receipts): Automatic documents: with invoicing set up, a paid or captured sale issues a document and each refund a credit document. sale_invoice_url is in sale-complete and refund; the number comes later in get-sales sale_invoices. Skip one sale with services [{name: invoice, settings: {active: false}}]. Documents API (deprecated, contact partners@payme.io first): needs its own activation (703); POST /documents with doc_type, buyer_name, items; asynchronous, so GET /documents/{doc_id} returns 1005 until ready; authority_redirect_url means Tax Authority approval first.

### Reporting

- [Find the right data](https://docs.payme.io/accepting-payments/reporting/find-the-right-data): Lookup table from business questions to the PayMe query API, filters and response fields that answer them (get-transactions for volume, refunds and chargebacks; get-sales for order status and release dates; get-subscriptions; get-sellers for balances; get-withdrawals and get-future-withdrawals for payouts), with paging (500 per page by default), Asia/Jerusalem time, rate limits and who can query what.
- [Reconcile sales and withdrawals](https://docs.payme.io/accepting-payments/reporting/reconcile-sales-and-withdrawals): Step-by-step reconciliation of a seller's withdrawals (get-withdrawals, with withdrawal_source and withdrawal_card_brand) against money movements (get-transactions grouped by transaction_release_date, net of fees via transaction_price_after_fees), how to catch missed callbacks with get-sales, the fee fields in sale_fees, and why the totals can differ.

## Marketplaces & Platforms

How-to guides for platforms and marketplaces on PayMe: onboarding sellers, platform fees, withdrawals, the reference lists sellers need, and reporting across sellers.

### Start Here

- [Start here: build a platform or marketplace on PayMe](https://docs.payme.io/marketplaces-and-platforms/start-here/how-platforms-work): Map of the PayMe partner model. A partner holds payme_client_key and a client password; each seller has its own MPL (seller_payme_id), public key, balance and bank account. Steps: onboard sellers (create-seller, documents, approval), enable payment methods (vas-enable), create sales with the seller's MPL and market_fee, handle callbacks, pay out (withdrawals), report. PayMe sets partner-level defaults: callback and return URLs, required seller fields, withdrawal plan, price range, rate limit. Seller callbacks go to the partner's default callback URL.

### Seller Onboarding

- [Create sellers](https://docs.payme.io/marketplaces-and-platforms/seller-onboarding/create-seller): Partner guide to onboarding sellers. Create a seller with POST /create-seller (payme_client_key required; PayMe sets the required fields per partner, error 19; 5 calls per minute per IP, error 998) and store the returned seller_payme_id (MPL), or send the seller the seller_dashboard_signup_link to finish on PayMe's onboarding pages. Upload documents with upload-seller-files. Sellers can take payments at once; payouts wait for PayMe's approval.
- [Enable payment methods and services for your sellers](https://docs.payme.io/marketplaces-and-platforms/seller-onboarding/enable-services): Partner guide to seller services (VAS). Sellers install Apple Pay, Google Pay and Bit from the dashboard app store. Partners call vas-enable with payme_client_key, seller_payme_id and the partner's vas_payme_id (from PayMe Partners); status_code 0 = on, 2 = Zendesk ticket, PayMe completes it. Apple Pay needs vas_data.websites (up to 99, domain file checked live, 703). Check with get-vas-seller (vas_type names, error 24; no callback). Turn off with vas-disable; then sales with that method fail 720. 703 = partner lacks the service.
- [Onboard a seller, from creation to first payout](https://docs.payme.io/marketplaces-and-platforms/seller-onboarding/onboard-a-seller): Partner guide to a seller's lifecycle. Collect details (PayMe sets required fields per partner, error 19). create-seller: store the MPL and public key, send seller_dashboard_signup_link; 5 calls/min per IP. Documents: 1 and 2 for every seller, 3 for most; 90-97 are personal (error 184). Approval: seller-approve callback and seller_approved on get-sellers; seller-update arrives during review. Then services, the first sale, and the first payout: approved, bank details, released funds, minimum 100.00; plans 1/2/3; errors 109, 907, 908, 913.

### Fees and Payouts

- [Platform fees](https://docs.payme.io/marketplaces-and-platforms/fees-and-payouts/platform-fees): How a partner charges a platform fee on its sellers' sales. market_fee is a percent (0-60) set as the seller's default on create-seller or per sale on generate-sale; market_fee_fixed adds a fixed fee per sale in major units. Errors 304 and 308. The seller's default can't be changed with update-seller; contact PayMe. See the fee on get-sellers, get-sales and get-transactions.
- [Withdrawals](https://docs.payme.io/marketplaces-and-platforms/fees-and-payouts/withdrawals): How sellers get paid. seller_withdrawal_plan 1 (manual) sellers request payouts with withdraw-balance (whole released balance, withdrawal_amount, or transaction_ids); plans 2 and 3 are automatic (error 907); paid-directly sellers get error 908. The seller must be approved by PayMe (error 109). Track with get-withdrawals and get-future-withdrawals; the withdrawal-complete callback; common errors.

### Seller Reference

- [File types](https://docs.payme.io/marketplaces-and-platforms/seller-reference/file-types): Reference list of seller document type codes for upload-seller-files and seller_additional_details[].files[].type. Every seller needs 1 (ID) and 2 (bank account); 3 (corporate certificate) for all but private individuals, house committees and municipalities, which need 14+7 and 27+7. Codes 90-97 are individual documents attached to the seller's primary individual (error 184 with more than one individual). Unknown code: error 20.
- [Business field codes (MCC)](https://docs.payme.io/marketplaces-and-platforms/seller-reference/mcc-list): Reference list of PayMe business field codes (10000 and up, top-level fields and their children) with Hebrew and English names. Send the code as seller_person_business_type on create-seller or update-seller; an unknown or inactive code returns error 110. The live list is GET /business-fields (allow_children=true for child codes). The Hebrew name is authoritative.
- [Individual roles](https://docs.payme.io/marketplaces-and-platforms/seller-reference/individual-seller-types): Role codes for individuals linked to a seller: 1 Owner, 2 Signatory, 4 Director, 8 Executive, 16 Back Office, 32 Charity Member, 64 Committee Member, 128 Corporate Officer. Send them as an array in seller_additional_details[].type on create-seller (required, error 160; unknown code error 24). Without additional individuals, the seller's own person is Owner and Signatory for a private individual or sole proprietorship, Back Office otherwise.
- [Seller incorporation types (Israel)](https://docs.payme.io/marketplaces-and-platforms/seller-reference/seller-incorporation-types-il): Israeli incorporation type codes for seller_inc on create-seller and update-seller (0 or 1 Individual, 2 Sole Proprietorship, 3 Incorporated Company, 4 Partnership, 5 Exempt Sole Proprietorship, 6 Charity, 7 Limited Partnership, 8 Publicly Traded Company, 9 Shared Cooperative, 10 Public Benefit Company, 295 House Committee, 296 Municipalities and councils). The type must match seller_address_country, and seller_inc_code must fit the type's rule, otherwise error 114.
- [VAS types](https://docs.payme.io/marketplaces-and-platforms/seller-reference/vas-types): List of vas_type values for PayMe value-added services (VAS). The API takes and returns the type name (case-insensitive), for example AlternativePaymentMethod for Apple Pay and Google Pay; numeric codes are rejected with error 24. Used by vas-enable and get-vas-seller.

### Reporting

- [Reporting across your sellers](https://docs.payme.io/marketplaces-and-platforms/reporting/reporting-across-your-sellers): How a partner reports across its sellers with the query APIs: send payme_client_key (body or PayMe-Partner-Key header) and optionally seller_payme_id (up to 100). Recipes for volume and refunds (get-transactions), active subscriptions (get-subscriptions), seller counts and balances (get-sellers, not api_mode slim), payouts (get-withdrawals, get-future-withdrawals), paging up to 500 per page and rate limits.

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

### Groups

- [Accepting Payments](https://docs.payme.io/payments/accepting-payments): Hosted Payment Page, Hosted Fields - JSAPI, Direct API, iOS SDK, Android SDK, Point of Sale (POS), Post Sale Actions
- [Wallets & APMs](https://docs.payme.io/payments/wallets-apms): Apple Pay, Google Pay, IL Direct Debit
- [Saved Cards & Recurring](https://docs.payme.io/payments/saved-cards-recurring): Tokenization, Subscriptions
- [Documents](https://docs.payme.io/payments/documents): Invoices
- [3D Secure](https://docs.payme.io/payments/3d-secure): Generate a Sale with 3D Secure, Standalone 3D Secure service
- [Platforms & Marketplaces](https://docs.payme.io/payments/platforms-marketplaces): Merchants Management, Buyers Management
- [Data & Reporting](https://docs.payme.io/payments/data-reporting): Query APIs, Codes & Statuses

### Getting Started

- [Integration Options](https://docs.payme.io/payments/getting-started/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).
- [Callback types reference](https://docs.payme.io/payments/getting-started/callback-types): 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-*.
- [Get API access and go live: from sandbox to production](https://docs.payme.io/payments/getting-started/go-live): 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](https://docs.payme.io/payments/getting-started/connect-a-new-website): 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

- [Hosted Payment Page](https://docs.payme.io/payments/hosted-payment-page): A payment page hosted by PayMe: create a sale with generate-sale and show the returned sale_url in an iframe or a redirect. Card and bank details never reach your servers.
- [Create a sale (hosted payment page)](https://docs.payme.io/payments/hosted-payment-page/post-generate-sale): POST /generate-sale — Create a sale (hosted payment page)
- [Create a multi-method checkout sale](https://docs.payme.io/payments/hosted-payment-page/post-generate-sale-2): POST /generate-sale — Create a multi-method checkout sale

### Hosted Fields - JSAPI

- [Hosted Fields - JSAPI](https://docs.payme.io/payments/hosted-fields-jsapi): Put PayMe's card inputs in your own checkout form with the browser SDK, then charge the token from your server with generate-sale.
- [Charge a Hosted Fields token](https://docs.payme.io/payments/hosted-fields-jsapi/post-generate-sale-hosted-fields-jsapi): POST /generate-sale — Charge a Hosted Fields token

### Direct API

- [Direct API](https://docs.payme.io/payments/direct-api): Charge cards and save them as tokens from your own server. For partners certified PCI DSS Level 1.
- [Pay a sale](https://docs.payme.io/payments/direct-api/post-pay-sale): POST /pay-sale — Pay a sale

### iOS SDK

- [iOS SDK](https://docs.payme.io/payments/ios-sdk): Legacy SDK, not recommended for new integrations: use the Hosted Payment Page in a secure in-app browser instead. The PayMe iOS SDK collects card details in your app and embeds your seller_payme_id. The guide covers importing PMLib.framework, initializing the SDK, and paying a sale, paying a subscription and capturing a buyer token.

### Android SDK

- [Android SDK](https://docs.payme.io/payments/android-sdk): Legacy SDK, not recommended for new integrations: use the Hosted Payment Page in a secure in-app browser instead. The PayMe Android SDK collects card details in your app and embeds your seller_payme_id. The guide covers building and importing the AAR with Gradle, initializing the SDK, paying a sale, paying a subscription, capturing a buyer token, and the reporting calls, which belong on your server.

### Point of Sale (POS)

- [Point of Sale (POS)](https://docs.payme.io/payments/point-of-sale-pos): Take card-present EMV payments on a POS device: prerequisites, device setup and pairing, payments and refunds.
- [Order POS devices](https://docs.payme.io/payments/point-of-sale-pos/post-vas-enable): POST /vas-enable — Order POS devices
- [Create a POS payment](https://docs.payme.io/payments/point-of-sale-pos/post-payment): POST /sales — Create a POS payment
- [Refund a POS sale](https://docs.payme.io/payments/point-of-sale-pos/put-sales): PUT /sales/{sale_guid} — Refund a POS sale

### Post Sale Actions

- [Refund a sale](https://docs.payme.io/payments/post-sale-actions/post-refund-sale): POST /refund-sale — Refund a sale
- [Void an authorization](https://docs.payme.io/payments/post-sale-actions/void-sale): POST /refund-sale — Void an authorization
- [Capture an authorized sale](https://docs.payme.io/payments/post-sale-actions/post-capture-sale): POST /capture-sale — Capture an authorized sale
- [Cancel a multi-payment page](https://docs.payme.io/payments/post-sale-actions/post-cancel-template): POST /cancel-template — Cancel a multi-payment page

### Apple Pay

- [Apple Pay](https://docs.payme.io/payments/apple-pay): Accept Apple Pay on PayMe's Hosted Payment Page, or on your own page with the browser SDK's appleSale().
- [Enable Apple Pay for a seller](https://docs.payme.io/payments/apple-pay/post-vas-enable-apple-pay): POST /vas-enable — Enable Apple Pay for a seller
- [Create a Apple Pay sale](https://docs.payme.io/payments/apple-pay/post-generate-sale-apple-pay): POST /generate-sale — Create a Apple Pay sale

### Google Pay

- [Google Pay](https://docs.payme.io/payments/google-pay): Accept Google Pay on PayMe's Hosted Payment Page, or on your own page with the browser SDK's googleSale().
- [Enable Google Pay for a seller](https://docs.payme.io/payments/google-pay/post-vas-enable-google-pay): POST /vas-enable — Enable Google Pay for a seller
- [Create a Google Pay sale](https://docs.payme.io/payments/google-pay/post-generate-sale-google-pay): POST /generate-sale — Create a Google Pay sale

### IL Direct Debit

- [Create an Israeli direct debit authorization](https://docs.payme.io/payments/il-direct-debit/post-generate-sale-il-direct-debit): POST /generate-sale — Create an Israeli direct debit authorization
- [Charge an Israeli direct debit authorization](https://docs.payme.io/payments/il-direct-debit/post-generate-sale-2-il-direct-debit): POST /generate-sale — Charge an Israeli direct debit authorization

### Tokenization

- [Save a card as a token](https://docs.payme.io/payments/tokenization/post-capture-buyer-token): POST /capture-buyer-token — Save a card as a token
- [Save a card (token sale)](https://docs.payme.io/payments/tokenization/post-generate-sale-tokenization): POST /generate-sale — Save a card (token sale)
- [Get the buyer key of a sale or subscription](https://docs.payme.io/payments/tokenization/post-get-buyer-key): POST /get-buyer-key — Get the buyer key of a sale or subscription
- [Create a partner-level token](https://docs.payme.io/payments/tokenization/post-sellers-mpl-tokens): POST /sellers/{mpl}/tokens — Create a partner-level token

### Subscriptions

- [Subscriptions](https://docs.payme.io/payments/subscriptions): Recurring payments with subscriptions: the lifecycle, statuses, pausing, template subscriptions, callbacks and iteration types.
- [Create a subscription](https://docs.payme.io/payments/subscriptions/post-generate-subscription): POST /generate-subscription — Create a subscription
- [Pay a subscription](https://docs.payme.io/payments/subscriptions/post-generate-subscription-2): POST /pay-subscription — Pay a subscription
- [Cancel a subscription](https://docs.payme.io/payments/subscriptions/postcancel-subscription): POST /cancel-subscription — Cancel a subscription
- [Pause a subscription](https://docs.payme.io/payments/subscriptions/post-pause-subscription): POST /pause-subscription — Pause a subscription
- [Resume a subscription](https://docs.payme.io/payments/subscriptions/patch-subscriptions-sub-payme-id-resume): PATCH /subscriptions/{sub_payme_id}/resume — Resume a subscription
- [Update a subscription's price](https://docs.payme.io/payments/subscriptions/patch-subscriptions-sub-id-set-price): PATCH /subscriptions/{sub_payme_id}/set-price — Update a subscription's price

### Invoices

- [Create a document](https://docs.payme.io/payments/invoices/post-create-invoice): POST /documents — Create a document
- [Get a document](https://docs.payme.io/payments/invoices/show-generated-document-by-id): GET /documents/{document_id} — Get a document
- [List documents](https://docs.payme.io/payments/invoices/get-documents): GET /documents — List documents

### Generate a Sale with 3D Secure

- [Generate a Sale with 3D Secure](https://docs.payme.io/payments/generate-a-sale-with-3d-secure): 3D Secure on hosted-payment-page sales: when PayMe applies it (foreign cards, 3 or more installments, amounts from the account's threshold) and how to force it on or off per sale with services.
- [Create a sale with 3D Secure](https://docs.payme.io/payments/generate-a-sale-with-3d-secure/post-generate-sale-generate-a-sale-with-3d-secure): POST /generate-sale — Create a sale with 3D Secure

### Standalone 3D Secure service

- [Standalone 3D Secure service](https://docs.payme.io/payments/standalone-3d-secure-service): Run 3D Secure 2 authentication as a separate step, without charging the card: the flow from browser data to the resolved 3DS values.
- [Start 3D Secure authentication](https://docs.payme.io/payments/standalone-3d-secure-service/post-initialize-3dsecure-request): POST /sales/{payme_sale_id}/3ds — Start 3D Secure authentication
- [Resolve a 3D Secure hash](https://docs.payme.io/payments/standalone-3d-secure-service/get-sales-payme-sale-id-3ds-hash): GET /sales/{payme_sale_id}/3ds/{hash_3dsecure} — Resolve a 3D Secure hash

### Merchants Management

- [Create a seller](https://docs.payme.io/payments/merchants-management/post-create-seller): POST /create-seller — Create a seller
- [Update a seller](https://docs.payme.io/payments/merchants-management/post-update-seller): POST /update-seller — Update a seller
- [Upload seller files](https://docs.payme.io/payments/merchants-management/post-upload-seller-files): POST /upload-seller-files — Upload seller files
- [List a seller's services](https://docs.payme.io/payments/merchants-management/post-get-vas-seller): POST /get-vas-seller — List a seller's services
- [Withdraw a seller's balance](https://docs.payme.io/payments/merchants-management/post-withdraw-balance): POST /withdraw-balance — Withdraw a seller's balance
- [List a seller's public keys](https://docs.payme.io/payments/merchants-management/get-sellers-mpl-public-keys): GET /sellers/{seller_payme_id}/public-keys — List a seller's public keys
- [List business fields](https://docs.payme.io/payments/merchants-management/get-business-fields): GET /business-fields — List business fields
- [Attach a saved card to a seller](https://docs.payme.io/payments/merchants-management/post-add-card-to-seller): POST /add-card-to-seller — Attach a saved card to a seller

### Buyers Management

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

### Query APIs

- [Query APIs](https://docs.payme.io/payments/query-apis): The query APIs list sales, transactions, subscriptions, sellers and withdrawals. A partner sends payme_client_key and sees its sellers; a seller sends its own seller_payme_id (body or PayMe-Merchant-Key header) and sees only its own data. Results page at 500 by default (page 1-1000, page_size 1-500); filters are exact matches except *_min/*_max; times are Asia/Jerusalem.
- [List sales](https://docs.payme.io/payments/query-apis/post-get-sales): POST /get-sales — List sales
- [List transactions](https://docs.payme.io/payments/query-apis/post-get-transactions): POST /get-transactions — List transactions
- [List subscriptions](https://docs.payme.io/payments/query-apis/post-get-subscriptions): POST /get-subscriptions — List subscriptions
- [List sellers](https://docs.payme.io/payments/query-apis/post-get-sellers): POST /get-sellers — List sellers
- [List withdrawals](https://docs.payme.io/payments/query-apis/post-get-withdrawals): POST /get-withdrawals — List withdrawals
- [List future withdrawals](https://docs.payme.io/payments/query-apis/get-future-withdrawals): POST /get-future-withdrawals — List future withdrawals
- [List banks](https://docs.payme.io/payments/query-apis/get-banks-country-iso-code): GET /banks/{country_iso_code} — List banks

### Codes & Statuses

- [Sale Types](https://docs.payme.io/payments/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](https://docs.payme.io/payments/codes-statuses/sale-statuses): Reference list of sale statuses, from `initial` and `completed` to `refunded`, `chargeback` and `voided`, with what each means.
- [Understand the sale lifecycle](https://docs.payme.io/payments/codes-statuses/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](https://docs.payme.io/payments/codes-statuses/transaction-types): Reference list of transaction type numbers, such as Sale, Token, Authorization/Void and Balance.
- [Transaction Statuses](https://docs.payme.io/payments/codes-statuses/transaction-statuses): Reference list of transaction statuses, from `pending` and `validated` to refunds, chargebacks and voids.
- [Subscription statuses](https://docs.payme.io/payments/codes-statuses/subscription-statuses): Reference list of subscription statuses (sub_status): initial, active, paused, failed, canceled, completed, and failed with a retry pending.
- [Subscription iteration types](https://docs.payme.io/payments/codes-statuses/subscription-iteration-types): Reference list of subscription billing intervals (sub_iteration_type): daily, weekly, monthly, yearly and quarterly.
- [Bank authorization statuses](https://docs.payme.io/payments/codes-statuses/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](https://docs.payme.io/payments/codes-statuses/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](https://docs.payme.io/payments/codes-statuses/document-types): Values of doc_type for Create a document: work order, delivery note, invoices, invoice receipt, credit invoice, receipts and price offer.

## B2B Payments

API reference for business-to-business payments: create payment contracts that send a payment or request one, manage their invoices and recipients, and transfer funds between wallets.

### Contracts

- [Contracts](https://docs.payme.io/b2b-payments/contracts): A payment contract moves money between two sellers on a due date (payment.type 1 send, 2 request). Methods: funds-transfer, credit-card, il-direct-debit (ILS); card/direct debit max 5000000 minor units. Card: tokenize (generate-sale sale_type token), attach with add-card-to-seller; direct debit attaches itself after bank approval. Send buyer_key at the TOP LEVEL of POST /payment-contracts; without it PayMe charges the payer's valid card that expires last. Auth: PayMe-Merchant-Key header. Callback payme_signature = md5(client key + client password + guid). Errors 11000-11004, 380-394.
- [Create a payment contract](https://docs.payme.io/b2b-payments/contracts/post-user): POST /payment-contracts — Create a payment contract
- [Run a B2B payment contract end to end](https://docs.payme.io/b2b-payments/contracts/contract-lifecycle): B2B contract flow. Header PayMe-Merchant-Key = MPL. payment.type 1 send (initiator pays) or 2 request (recipient pays); the recipient approves in PayMe. Methods: funds-transfer, credit-card, il-direct-debit (ILS only, 320); card/debit max 5000000 (393). Card: tokenize, add-card-to-seller, send buyer_key top level. A repeat create within 5 min returns the same contract. Status 1, 2, 3 (auto), 4; or 5 with error_code 11000-11004 (read error_code); payment-contract-* callbacks. Change: PUT /payment-contracts/{guid}; cancel: .../cancellations (initiator); files: .../invoices. Errors 380-394.
- [List payment contracts](https://docs.payme.io/b2b-payments/contracts/get-contracts): GET /payment-contracts — List payment contracts
- [List contract files](https://docs.payme.io/b2b-payments/contracts/get-contracts-files): GET /payment-contracts/{payment_contract_guid}/invoices — List contract files
- [Upload contract files](https://docs.payme.io/b2b-payments/contracts/post-contracts-files): POST /payment-contracts/{payment_contract_guid}/invoices — Upload contract files
- [Replace a contract file](https://docs.payme.io/b2b-payments/contracts/put-contracts-files): PUT /payment-contracts/{payment_contract_guid}/invoices/{invoice_guid} — Replace a contract file
- [Delete a contract file](https://docs.payme.io/b2b-payments/contracts/delete-contracts-files): DELETE /payment-contracts/{payment_contract_guid}/invoices/{invoice_guid} — Delete a contract file
- [List previous recipients](https://docs.payme.io/b2b-payments/contracts/get-recipient): GET /payment-contracts/recipients — List previous recipients

### Wallets

- [Transfer funds between sellers](https://docs.payme.io/b2b-payments/wallets/post-generate-transfer): POST /sales — Transfer funds between sellers

## Keep

APIs for Keep, PayMe's accounting product: partners create and manage sellers, income documents, expenses, and tax and VAT balances, authenticating with OAuth 2.0 client credentials.

### Partner Authorization

- [Prerequisites](https://docs.payme.io/keep/partner-authorization/prerequisites): Partner authorization layer protects the Partner's data on the Keep domain against unauthorized access and mutation.
- [Authorization Flow](https://docs.payme.io/keep/partner-authorization/authorization-flow): Keep uses OAuth 2.0 client credentials. POST /oauth2/token (form-encoded) with grant_type=client_credentials, client_id, client_secret and optional scope (partner-api or seller-api); send Authorization: Bearer <access_token>; refresh with grant_type=refresh_token. Use the lifetime returned in expires_in; when supplied, refresh_expires_in gives the refresh-token lifetime. Keep is served on https://<partner_domain>.keep.co.il; HTTPS only. Credentials come from your Account Manager and cannot be rotated by you.

### Seller API

- [List income documents](https://docs.payme.io/keep/seller-api/listsellerincomedocuments): GET /seller/api/documents/income — List income documents
- [Seller API](https://docs.payme.io/keep/seller-api): The Seller API lets accounting integrations create and retrieve seller income documents such as invoices and receipts. This page is the editable landing for the Seller API category.
- [Create income document](https://docs.payme.io/keep/seller-api/createsellerincomedocument): POST /seller/api/documents/income — Create income document
- [Get income document](https://docs.payme.io/keep/seller-api/getsellerincomedocument): GET /seller/api/documents/income/{id} — Get income document

### Partners API

- [Obtain access token](https://docs.payme.io/keep/partners-api/gettoken): POST /oauth2/token — Obtain access token
- [Partners API](https://docs.payme.io/keep/partners-api): The Keep Partner API authenticates with OAuth 2.0 client credentials and refresh tokens. Token endpoint errors return error and error_description. Guard and validation HTTP errors normally include statusCode and message, plus correlationId and category. Retry with exponential backoff.
- [Create seller](https://docs.payme.io/keep/partners-api/createseller): POST /api/public/sellers/create — Create seller
- [Get seller](https://docs.payme.io/keep/partners-api/getsellerbyid): GET /api/public/sellers/{sellerId} — Get seller
- [Get available plans](https://docs.payme.io/keep/partners-api/getpartnerplans): GET /api/public/plans — Get available plans
- [List expenses](https://docs.payme.io/keep/partners-api/listpublicexpenses): GET /api/public/expenses — List expenses
- [Upload expense document](https://docs.payme.io/keep/partners-api/uploadpublicexpense): POST /api/public/expenses — Upload expense document
- [Update expense](https://docs.payme.io/keep/partners-api/updatepublicexpense): PATCH /api/public/expenses/{expenseId} — Update expense
- [Update seller](https://docs.payme.io/keep/partners-api/updatesellerbyid): PUT /api/public/sellers/{sellerId}/update — Update seller
- [Set seller billing plan](https://docs.payme.io/keep/partners-api/setsellerplan): POST /api/public/plans/activate — Set seller billing plan
- [List income documents](https://docs.payme.io/keep/partners-api/listincomedocuments): GET /partner/api/documents/income — List income documents
- [Create manual income document](https://docs.payme.io/keep/partners-api/createmanualincomedocument): POST /partner/api/documents/income/manual — Create manual income document
- [Get financial checkpoints](https://docs.payme.io/keep/partners-api/getcheckpoints): GET /partner/api/statistic/checkpoints — Get financial checkpoints
- [Get tax predictions](https://docs.payme.io/keep/partners-api/gettaxpredictions): GET /partner/api/statistic/tax-predictions — Get tax predictions

## Products and Customers

API reference for storing a seller's product catalogue and customer records: create, list, update and delete products and customers, authenticated with a JWT from `POST /auth-tokens`.

### Authentication

- [Authentication](https://docs.payme.io/products-and-customers/authentication): Hosts: https://payme-store-staging.payme.io/api/ (sandbox), https://payme-store.payme.io/api/ (production). POST /auth-tokens with {"mpl": seller MPL, "key": partner payme_client_key} returns 201 with auth_token (JWT) and refresh_token; send Authorization: Bearer <auth_token>. POST /refresh-exchanges with {"refresh_token"} (no headers) returns a new auth_token and a new single-use refresh_token. Prices are decimal major units as {amount, currency}. Errors: status_error_details, status_error_code (501 validation, 999 other), validation_errors, session; HTTP 400, 401, 404, 409, 500.
- [Get an access token](https://docs.payme.io/products-and-customers/authentication/post-auth-token): POST /auth-tokens — Get an access token
- [Refresh an access token](https://docs.payme.io/products-and-customers/authentication/post-auth-refresh): POST /refresh-exchanges — Refresh an access token

### Products

- [List products](https://docs.payme.io/products-and-customers/products/get-products): GET /products — List products
- [Get a product](https://docs.payme.io/products-and-customers/products/get-products-guid): GET /products/{guid} — Get a product
- [Update a product](https://docs.payme.io/products-and-customers/products/patch-products-product-id): PATCH /products/{guid} — Update a product
- [Delete a product](https://docs.payme.io/products-and-customers/products/delete-products-guid): DELETE /products/{guid} — Delete a product
- [Create a product](https://docs.payme.io/products-and-customers/products/post-user): POST /products — Create a product

### Customers

- [List customers](https://docs.payme.io/products-and-customers/customers/get-customers): GET /customers — List customers
- [Create a customer](https://docs.payme.io/products-and-customers/customers/post-customers): POST /customers — Create a customer
- [Get a customer](https://docs.payme.io/products-and-customers/customers/get-customers-guid): GET /customers/{guid} — Get a customer
- [Update a customer](https://docs.payme.io/products-and-customers/customers/patch-customers): PATCH /customers/{guid} — Update a customer
- [Delete a customer](https://docs.payme.io/products-and-customers/customers/delete-customers): DELETE /customers/{guid} — Delete a customer

## AI Toolkit

Step-by-step procedures, rules, checks, code and test cases for integrating with PayMe as a partner or a direct seller. Includes installable agent skills and one page per common error.

### Start

- [Get Your Dedicated Test Account](https://docs.payme.io/agents/start/get-your-test-account): Every integration starts with a dedicated test account. A seller opens one from the dashboard (Switch to test account, then Create test account) or signs up at paid.co.il. A partner writes to partners@payme.io for a sandbox partner key, partner secret and a connected terminal. PayMe publishes no shared test credentials.
- [What to Ask PayMe First](https://docs.payme.io/agents/start/ask-payme-first): Before building, ask PayMe (partners@payme.io) whether a terminal is connected to the sandbox account, to set the Default Callback URL per environment, whether Hosted Fields sellers need 3D Secure, whether subscriptions are enabled, what seller_plan values apply, how partial capture behaves, and whether white-label onboarding can be enabled.
- [Rules for Agents](https://docs.payme.io/agents/start/rules-for-agents): Numbered rules with stable IDs for PayMe integrations. SEC secrets stay on the server. MON money is integer minor units. TRN success is status_code 0 in a 2xx response, and money calls with unknown outcomes are not retried. CB callback bodies are never trusted and are confirmed by query. TOK tokens are encrypted bearer credentials. WRK look up fields, sandbox first, claim only what was run.

### Partner

- [Integrate as a Partner](https://docs.payme.io/agents/partner/payme-partner-integration): The procedure for a partner (marketplace or platform) integration: load the rules, inspect the project and keep three record files, interview the person in short rounds, plan and get approval, build in a fixed order, prove it with test cases and the sandbox, and report. Also published as the agent skill payme-partner-integration.

### Seller

- [Integrate as a Direct Seller](https://docs.payme.io/agents/seller/payme-seller-integration): The procedure for a direct-seller integration, using one credential, the MPL: load the rules, inspect the project, ask the person a few questions, plan and get approval, build in a fixed order, prove it with test cases and the sandbox, and report. Callbacks are confirmed by query. Also published as the agent skill payme-seller-integration.

### Steps

- [Config and Transport](https://docs.payme.io/agents/steps/config-and-transport): Build configuration and one PayMe client first. Choose the environment from config, keep credentials out of code, treat status_code 0 in a 2xx response as the only success, read a failure by its body (HTTP 500 with status_code 1 and an error code is a refusal), do not retry money calls with an unknown outcome, omit local callback URLs (error 21), keep two public URL settings, and use dd/mm/yyyy on seller and subscription dates but yyyy-mm-dd hh:mm:ss on query date filters.
- [Money](https://docs.payme.io/agents/steps/money): PayMe amounts are integers in minor units. generate-sale rounds a decimal sale_price rather than refusing it, so 600.75 becomes 601 and charges 6.01, and 50.75 becomes 51 and fails with error 352. The default range is 500 to 4000000 per account. Convert only for display, and reject bad amounts before calling PayMe.
- [Seller Onboarding](https://docs.payme.io/agents/steps/seller-onboarding): Partners onboard sellers through PayMe's white-label form or create-seller. In the sandbox seller_phone 0501234567 failed with error 25 and +972501234567 passed. Dates are dd/mm/yyyy. Store seller_payme_id and the public key, ignore seller_payme_secret, read state from get-sellers, and never block checkout on approval, which gates payouts only.
- [Checkout](https://docs.payme.io/agents/steps/checkout): Every PayMe flow starts with generate-sale. Default to the hosted page, add Hosted Fields when the checkout must look native, use a saved token only when no buyer is present. Keep one open sale per order: a failed hosted sale stays payable, so reuse it, send your order ID as transaction_id, store payme_sale_id, fulfil only after a query confirms payment, and use sale_expiry_seconds to limit how long a payment page stays open.
- [Callbacks (Partner)](https://docs.payme.io/agents/steps/callbacks-partner): For partners, a sale callback's valid signature means only worth checking, because it covers credentials and two IDs, not status or amount. Confirm with get-transactions using the seller's MPL and match your own order. Subscription, seller and withdrawal-complete callbacks are unsigned, so re-read them. Delivered means below 400, 4xx is retried, and a failing domain can be skipped, so reconcile, including finished orders, and a failed sale can still complete.
- [Callbacks (Direct Seller)](https://docs.payme.io/agents/steps/callbacks-seller): A direct seller cannot check payme_signature, because it needs partner credentials. Treat every callback as a trigger: find your order by the payme_sale_id you stored, call get-transactions with your MPL and your order ID, check the rows, then apply PayMe's answer. Reply below 400 for recorded decisions, rate-limit lookups, and re-check on a schedule because callbacks can be skipped.
- [Capture, Refund, Void](https://docs.payme.io/agents/steps/capture-refund-void): An authorization lasts 7 days and captures once; a second capture fails with error 305 and a late one with 516. A refund with no amount after a partial refund returns exactly the rest, and the sale stays partial-refund, so track the total. refund-sale on an uncaptured authorization voids it. Refund rows in get-transactions have the action Refund or Partial Refund; a void adds none. Partial capture's remainder is unconfirmed, so do not offer it yet.
- [Saved Cards](https://docs.payme.io/agents/steps/saved-cards): Saved cards use a token. capture_buyer, Hosted Fields and capture-buyer-token give a buyer_key; POST /sellers/{mpl}/tokens gives a uuid sent as token, and it worked across a partner's sellers in the sandbox. Without buyer_is_permanent, a second charge failed with error 604. Encrypt tokens, never send them to a browser. A direct seller sends buyer_is_private: true and fetches the token with get-buyer-key after confirming the sale.
- [Subscriptions](https://docs.payme.io/agents/steps/subscriptions): PayMe runs the subscription schedule, so never build a charging scheduler. Subscription callbacks are unsigned: re-read with get-subscriptions using the seller's MPL in the JSON body. Grant service for each increase in sub_iterations_completed, not per notification. Status 7 is failed-retry, so don't dun the buyer. Monthly start days must be 1 to 28, and a token used here must be permanent.
- [Balances and Payouts](https://docs.payme.io/agents/steps/balances-and-payouts): For partners, balances are in seller_wallets on get-sellers. wallet_releasable comes from release dates. A withdrawal can be refused because the seller is not validated (109) or is on an automatic plan (907). withdrawal-complete is unsigned and fires on commit, before the bank transfer, so re-read with get-withdrawals. market_fee reaches the platform separately, by default monthly.
- [Implementation Traps](https://docs.payme.io/agents/steps/implementation-traps): A checklist of traps found by independent review of a real PayMe integration: two payable sales for one order, concurrent capture or refund, unknown refund outcomes, reconcile clearing flags on empty answers, retried payouts or subscriptions, counting a void as a refund, and lenient number parsing. Check your code against each row before review.

### Verify

- [Test Cases and Reference Code](https://docs.payme.io/agents/verify/test-cases-and-reference-code): PayMe publishes language-neutral JSON test cases and TypeScript and browser reference code at /integration-kit/, listed in index.json, under the MIT licence. Port every case for your role into your own test suite and make it pass, whatever your language. Add tests for your own connecting code. The files ship with each docs release.
- [Readiness Preflight](https://docs.payme.io/agents/verify/readiness-preflight): Run these before any sandbox step. Confirm credentials are set without printing them and are not placeholders, the config loads, a read-only query is accepted, the running server has the current settings, the public address answers from the internet, and PayMe has connected a terminal and, for partners, set the Default Callback URL.
- [Sandbox Walk-through](https://docs.payme.io/agents/verify/sandbox-walk-through): Run each chosen flow against the PayMe sandbox and confirm final states with a query. Order: setup and forged callback, sellers (partner), open sales, pay them with test cards, confirm, then capture, void, partial refund and remainder, saved card reuse, subscription actions, payouts. Tick only what was run. Partners also need one real signed sale callback verified.
- [Go-Live Checklist](https://docs.payme.io/agents/verify/go-live-checklist): Before going live with PayMe, switch base URL, credentials and Hosted Fields testMode together, keep secrets in a secrets manager, use a real HTTPS callback address, confirm a forged callback is rejected, remove simulators, reconcile on a schedule, watch authorizations near 7 days, and log session IDs. Partners also confirm the production Default Callback URL.
- [Proof-of-Integration Report](https://docs.payme.io/agents/verify/proof-of-integration-report): A template for proving a PayMe integration works. Fill in evidence per area, including test cases ported, independent review, credentials accepted, forged callback unchanged and real signed callback for partners. List each flow actually run with its final state confirmed by query, the flows not run, findings, open questions and how many times a person stepped in.

### Errors

- [Troubleshooting by Symptom](https://docs.payme.io/agents/errors/troubleshooting): Symptom-first troubleshooting for PayMe integrations. Every card failing on the hosted page points to no terminal (420). A paid subscription stuck at initial means the handler expects signatures. A real sale callback rejected means a wrong partner secret. No callbacks means an unreachable address, a local URL or a skipped domain. Tunnel 1033 and 502 mean tunnel or server down.
- [Error 420: No Terminal Available](https://docs.payme.io/agents/errors/error-420): PayMe error 420 (Please try a different card or contact customer support). PayMe found no terminal that can process this card for this seller.
- [Error 25: Invalid Phone Number](https://docs.payme.io/agents/errors/error-25): PayMe error 25 (Please verify phone number). A phone number was refused.
- [Error 21: Invalid URL](https://docs.payme.io/agents/errors/error-21): PayMe error 21 (Please verify URL validity). PayMe refused a URL in the request, and the whole call fails.
- [Error 790: Parameter Not Allowed on This Plan](https://docs.payme.io/agents/errors/error-790): PayMe error 790 (A parameter is missing or cannot be set on this plan). The seller's plan requires a field you left out, or refuses a field you sent.
- [Error 174: Not Supported for This Seller Type](https://docs.payme.io/agents/errors/error-174): PayMe error 174 (Feature is not supported for this seller type). The account behind this seller ID can't perform the call.
- [Error 114: Business Type Not Valid](https://docs.payme.io/agents/errors/error-114): PayMe error 114 (The selected business type is not valid for this business). The seller's business type doesn't fit its other details.
- [Error 121: Invalid Business Code](https://docs.payme.io/agents/errors/error-121): PayMe error 121 (The business code is invalid, Please enter only numbers). seller_inc_code isn't a positive number.
- [Error 352: Invalid Price](https://docs.payme.io/agents/errors/error-352): PayMe error 352 (Invalid price, out of min-max bounds). An amount is outside the allowed range.
- [Error 305: Action Not Allowed in This Status](https://docs.payme.io/agents/errors/error-305): PayMe error 305 (Cannot perform action due to an incorrect status). The sale isn't in a status that allows this call.
- [Error 163: Seller Inactive](https://docs.payme.io/agents/errors/error-163): PayMe error 163 (Account settings problem - please contact Customer Support). The seller exists but isn't active.
- [Error 130: Seller Over Sale Limit](https://docs.payme.io/agents/errors/error-130): PayMe error 130 (Seller is over sale limit, unable to create new sales). The sale would take the seller over its processing limit. Complete any pending verification, then ask partners@payme.io to review the limit.
- [Error 998: Too Many Requests or Duplicate Action](https://docs.payme.io/agents/errors/error-998): PayMe error 998 (Operation is not permitted). HTTP 429.
- [Error 513: Duplicate Purchase](https://docs.payme.io/agents/errors/error-513): PayMe error 513 (Duplicate purchase attempt detected. Please wait one minute before retrying). A saved-card charge repeated the same seller, amount and currency within 60 seconds. The check is off unless PayMe turns it on, so most integrations never see this code.
- [Error 516: Authorization Expired](https://docs.payme.io/agents/errors/error-516): PayMe error 516 (Sale authorization has been expired). The capture came more than 7 days after the authorization, so it can no longer be captured.
- [Error 42: Number Must Be an Integer](https://docs.payme.io/agents/errors/error-42): PayMe error 42 (Number must be an integer). A value that must be whole had decimals.
- [Error 109: Seller Not Validated](https://docs.payme.io/agents/errors/error-109): PayMe error 109 (Seller not validated). The seller hasn't been validated, so a withdrawal is refused.
- [Error 10: Field Must Be Numeric](https://docs.payme.io/agents/errors/error-10): PayMe error 10 (Field must be numeric). A field that must be a number isn't.
- [Error 304: Market Fee Out of Range](https://docs.payme.io/agents/errors/error-304): PayMe error 304 (Market fee is not in the allowed range). market_fee or market_fee_fixed isn't a number, or is negative.
- [Error 308: Market Fee Above Maximum](https://docs.payme.io/agents/errors/error-308): PayMe error 308 (Market fee exceed allowed maximum of 60%). The fee, including any market_fee_fixed as a percent of the price, is above 60%.
- [Error 116: Invalid Birth Date](https://docs.payme.io/agents/errors/error-116): PayMe error 116 (Invalid birthdate). seller_birthdate is unreadable, or the person is under 16.
- [Error 118: Invalid ID Issue Date](https://docs.payme.io/agents/errors/error-118): PayMe error 118 (Invalid social ID issue date). seller_social_id_issued is unreadable or in the future.
- [Error 200: Partner Key Not Found](https://docs.payme.io/agents/errors/error-200): PayMe error 200 (Merchant was not found). The payme_client_key or PayMe-Partner-Key matches no partner.
- [Error 201: Partner Inactive](https://docs.payme.io/agents/errors/error-201): PayMe error 201 (Merchant is blocked). The partner account isn't active.
- [Error 251: Seller Not Found](https://docs.payme.io/agents/errors/error-251): PayMe error 251 (Seller was not found). The seller_payme_id or seller_id matches no seller.
- [Error 252: Currency Not Allowed](https://docs.payme.io/agents/errors/error-252): PayMe error 252 (Currency is not allowed for this seller). This seller can't use that currency.
- [Error 604: Token Inactive](https://docs.payme.io/agents/errors/error-604): PayMe error 604 (Buyer inactive). The saved-card token can't be charged any more.
- [Error 605: Token From Another Seller](https://docs.payme.io/agents/errors/error-605): PayMe error 605 (The buyer was not captured using the provided seller). The token doesn't belong to the seller in the request.