{"openapi":"3.1.0","info":{"title":"Payments","version":"1.0.0","description":"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."},"servers":[{"url":"https://sandbox.payme.io/api","description":"Sandbox"},{"url":"https://live.payme.io/api","description":"Production"}],"components":{"securitySchemes":{"merchantKey":{"type":"apiKey","in":"header","name":"PayMe-Merchant-Key"},"partnerKey":{"type":"apiKey","in":"header","name":"PayMe-Partner-Key"},"publicKey":{"type":"apiKey","in":"header","name":"PayMe-Public-Key"},"signature":{"type":"apiKey","in":"header","name":"PayMe-Signature"}}},"tags":[{"name":"Hosted Fields - JSAPI"}],"paths":{"/generate-sale":{"post":{"operationId":"post-generate-sale-hosted-fields-jsapi","summary":"Charge a Hosted Fields token","tags":["Hosted Fields - JSAPI"],"description":"## Overview\n\nCharges the token that `instance.tokenize()` returned, from your server, in one call: send it as `buyer_key`. There is no payment page and no `sale_url`. Read the result from `status_code`: a declined charge also returns HTTP 200.\n\n`POST https://sandbox.payme.io/api/generate-sale` (production: `https://live.payme.io/api/generate-sale`), with a JSON body (`Content-Type: application/json`).\n\nThis is the server step of the [Hosted Fields guide](/accepting-payments/checkout-and-in-person/hosted-fields-jsapi-guide). The same call charges any saved token; see [Save a card and charge it later](/accepting-payments/capture-and-saved-cards/save-a-card-and-charge-it-later).\n\n| To | Send |\n|---|---|\n| Charge now (J4) | `sale_type: sale` (default) |\n| Authorize now, capture later (J5, up to 168 hours) | `sale_type: authorize`; then [capture-sale](/accepting-payments/capture-and-saved-cards/capture-sale) |\n\n### Credentials\n\nSend `seller_payme_id` (the MPL) in the JSON body: this endpoint doesn't read the `PayMe-Merchant-Key` header, so a request without a body MPL returns error `1`. Partners add `payme_client_key` (or the `PayMe-Partner-Key` header) and may name the seller by `seller_id` instead. See [Authentication](/payments/getting-started/authentication).\n\n### What to expect\n\n- Success: `status_code: 0` and the sale and transaction fields, the same as the callback.\n- Decline: **HTTP 200** with `status_code: 1`, `status_error_code` (for example `20004`) and `status_error_details`.\n- Every call creates a new sale, even when the charge is refused. Check the sale before you retry; see [Idempotency and Retries](/payments/getting-started/idempotency-and-retries).\n- The token's own payment method is used.\n- Errors: `buyer_key` with `capture_buyer` returns `601`, with `sale_type` `token`/`seller-token` `602`, with `template` `606`, and with `multi-capture` `357`. A token of another seller returns `605`; an inactive or already-used single-use token returns `604`; a charge over the seller's processing limit returns `130`.\n- Never put card numbers in any field (error `20`), and don't send the legacy `price` field (major units; it overrides `sale_price`).\n\n### Callbacks\n\nWhen the sale is paid, PayMe sends a `POST` with an `application/x-www-form-urlencoded` body to `sale_callback_url`. The notification types and fields are on [Callbacks](/payments/getting-started/callbacks).\n\n### Issuing an invoice to a business\n\nWith the invoicing service active on the account, send `buyer_business_name` and `buyer_business_code` to issue the invoice to a business. Send both, or neither.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"seller_payme_id":{"type":"string","description":"The seller's MPL. Send it in the JSON body: `generate-sale` doesn't read the `PayMe-Merchant-Key` header, so a request without a body MPL returns error `1`. Partners may send `seller_id` with `payme_client_key` instead."},"payme_client_key":{"type":"string","description":"Partners only: your partner key (or send the `PayMe-Partner-Key` header). With `seller_payme_id`, the seller must belong to you, otherwise error `20`."},"seller_id":{"type":"string","description":"Partners only: your own ID for the seller, set in `create-seller`, sent instead of `seller_payme_id`. Requires `payme_client_key`."},"buyer_key":{"type":"string","description":"The token from `instance.tokenize()`, or a saved `buyer_key`. The sale is charged at once."},"sale_price":{"type":"integer","description":"Sale amount in minor units: 50.75 is sent as `5075`. The default allowed range is `500`–`4000000`, the same in every currency; PayMe can set a different range for a partner. A missing, non-numeric or out-of-range value returns error `352`. Decimals are rounded."},"currency":{"type":"string","description":"Sale currency, a 3-letter [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) code such as `ILS`, enabled on the account (otherwise error `252`). Required for `sale` and `authorize`; a `token` or `template` sale without it uses the account's default currency."},"product_name":{"type":"string","description":"Short description of the product or service, up to 500 characters. Shown to the buyer, and on the invoice when the invoicing service is active. Missing returns error `353`."},"transaction_id":{"type":"string","description":"Your own order reference, up to 50 characters. PayMe returns it in responses and callbacks but doesn't check it for uniqueness."},"installments":{"type":"string","description":"Number of payments: `1` (default) to `12`. More than one installment is ILS only (`312`) and needs a card token. Fixed values above 12 fail unless PayMe has enabled more installments on your account. A non-numeric value returns `10`, an ILS price lower than the number of installments `358`."},"sale_type":{"type":"string","description":"`sale` (default) – charge now (J4). `authorize` – reserve the amount for up to 168 hours, then capture it with [`capture-sale`](/accepting-payments/capture-and-saved-cards/capture-sale) (J5). `token`, `seller-token` and `template` can't be combined with `buyer_key` (`602`, `606`)."},"market_fee":{"type":"number","description":"The partner's (marketplace's) fee: a percentage of the sale price, VAT included, from `0` to `60`. It is added on top of PayMe's fees and transferred to the marketplace once a month. Default: the seller's market fee set at `create-seller`. A non-numeric value returns `10`, a negative one `304`, and more than 60 `308`. Ignored for sellers paid directly."},"sale_callback_url":{"type":"string","description":"Where PayMe sends server-to-server callbacks for this sale, as a form-encoded `POST`; see [Callbacks](/payments/getting-started/callbacks). If omitted, PayMe uses your partner's default callback URL, if one is set; a seller has no dashboard setting for it, so send it on every call. Must be a public address: `localhost`, private or loopback IP addresses and IPv6 addresses are refused with error `21`, which fails the whole call."},"language":{"type":"string","description":"Language of the payment page and the error messages. Default `he`. `he` and `en` are fully supported; `es`, `ru` and `ar` are accepted, but messages and the payment page are then mostly in English. Case-insensitive; any other value, or an empty string, returns error `51`."},"buyer_business_name":{"type":"string","description":"With the invoicing service: the business name the invoice is issued to. Send it together with `buyer_business_code`, or neither."},"buyer_business_code":{"type":"integer","description":"With the invoicing service: the business code (VAT identifier) the invoice is issued to. Send it together with `buyer_business_name`, or neither."},"items":{"type":"array","description":"Line items of the sale, as an array of objects. If you send `items`, every item needs `name`, `quantity`, `unit_price` and `total`; an invalid item returns error `20` (HTTP 422) with the failing rules in `status_additional_info`. Item keys are case-insensitive.","items":{"type":"object","properties":{"name":{"type":"string","description":"Item name, 1–50 characters."},"quantity":{"type":"integer","description":"Quantity, `0`–`999999`."},"unit_price":{"type":"integer","description":"Price of one unit, in minor units."},"total":{"type":"integer","description":"Line total after discount, in minor units, `0`–`9000000000`."},"unit_measurement":{"type":"string","description":"Unit of measurement, for example `kg`."},"discount_total":{"type":"number","description":"Discount on this line, in minor units, sent as a negative number."},"description":{"type":"string","description":"Item description, up to 150 characters."},"product_code":{"type":"string","description":"Your catalog code for the item, up to 100 characters."},"commodity_code":{"type":"number","description":"Numeric commodity code of the item."},"custom1":{"type":"string","description":"Free text for your own use, up to 100 characters."},"custom2":{"type":"string","description":"Free text for your own use, up to 100 characters."}},"required":["name","quantity","unit_price","total"]}}},"required":["seller_payme_id","buyer_key","sale_price","currency","product_name"]},"example":{"seller_payme_id":"MPLDEMO-MPLDEMO-MPLDEMO-1234567","buyer_key":"BUYERDEMO-BUYERDEMO-BUYERDEMO-1234567","sale_price":1000,"currency":"ILS","product_name":"Smartphone","transaction_id":"order-1001","installments":"1","sale_callback_url":"https://your-server.example.com/payme/callback","language":"en"}}}},"responses":{"200":{"description":"Declined. A declined token charge returns HTTP 200; check `status_code`.","x-response-kind":"error","content":{"application/json":{"schema":{"type":"object","properties":{"status_code":{"type":"integer","description":"`1`: the charge failed."},"status_error_code":{"type":"integer","description":"Decline or error code, for example `20004`; see [Errors](/payments/getting-started/errors)."},"status_error_details":{"type":"string","description":"The message, in the requested `language`."},"payme_sale_id":{"type":"string","description":"The sale this call created."}}},"example":{"status_code":1,"status_error_code":20004,"status_error_details":"Refusal by credit company. Please try a different card","payme_sale_id":"SALE1700-000000AA-EXAMPLE1-SALE0001","sale_url":"https://sandbox.payme.io/sale/generate/SALE1700-000000AA-EXAMPLE1-SALE0001"}}}},"500":{"description":"Request refused. Most request errors return HTTP 500 with `status_code: 1`; some return 400, 403, 422 or 429. See [Errors](/payments/getting-started/errors).","x-response-kind":"error","content":{"application/json":{"schema":{"type":"object","properties":{"status_code":{"type":"integer","description":"`1` for an error."},"status_error_code":{"type":"integer","description":"PayMe's error code, for example `251` (seller not found) or `352` (invalid price)."},"status_error_details":{"type":"string","description":"The error message, in the requested `language` (Hebrew by default)."},"status_additional_info":{"type":"string","description":"Extra detail, usually the name of the field at fault."},"session":{"type":"string","description":"Request ID. Quote it when you contact PayMe."}}},"example":{"status_code":1,"status_error_details":"Seller was not found","status_additional_info":"seller_payme_id","status_error_code":251,"session":"AtsJ0as5"}}}}}}}}}