{"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":"Tokenization"}],"paths":{"/capture-buyer-token":{"post":{"operationId":"post-capture-buyer-token","summary":"Save a card as a token","tags":["Tokenization"],"description":"## Overview\n\nSaves a card and returns a `buyer_key` you can charge later. Nothing is charged. You send raw card details, so call it from your server only if you are PCI DSS Level 1 certified. Otherwise save cards with [Hosted Fields](/payments/hosted-fields-jsapi) or a [`token` sale](/accepting-payments/capture-and-saved-cards/save-a-card-and-charge-it-later).\n\nName the seller with `seller_payme_id`. (Hosted Fields sends the seller's public key in the `PayMe-Public-Key` header instead.) \n\n### Two flags decide what the token is\n\n- `buyer_is_permanent: true` makes a token you can charge any number of times. Without it the token is single-use: the first `generate-sale` charge with it deactivates it, later charges fail with error `604`, and subscriptions reject it.\n- `buyer_is_private: true` ties the token to this seller (MPL). Without it the token belongs to your account, and any seller of the same partner can charge it. To read such a token back with [`get-buyer-key`](/payments/tokenization/post-get-buyer-key) you need `payme_client_key`.\n\n\n\n### Charging the token\n\nSend the `buyer_key` with [`generate-sale`](/payments/hosted-payment-page/post-generate-sale) to charge the card at once, with no payment page and no CVV. These charges run without 3D Secure. A permanent token doesn't expire in PayMe, but a charge can still fail if the card has expired or the issuer declines it, so handle the `sale-failure` callback. Store `buyer_key` encrypted: it stands in for the card number. \n\nSaving the same card again for the same buyer and seller can return the existing `buyer_key`. \n\n### Errors\n\nA declined card returns HTTP 500, with the decline code in `status_error_code` (for example `20004`) and the masked card number in `status_additional_info`. This differs from `pay-sale`, which returns HTTP 200 for a decline. A value that looks like a card number in any field other than `credit_card_number` returns HTTP 400, error `20`. ","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"seller_payme_id":{"type":"string","description":"The seller's MPL."},"credit_card_number":{"type":"string","description":"Card number, digits only."},"credit_card_exp":{"type":"string","description":"Card expiry as `MMYY` (`MM/YY` and `MMYYYY` are also accepted). An expired or invalid date returns error `356`."},"credit_card_cvv":{"type":"string","description":"CVV, 3 or 4 digits. Required unless `token_terminal` is `true`."},"token_terminal":{"type":"boolean","description":"`true` to save the card without a CVV, on a token terminal. Default `false`."},"buyer_name":{"type":"string","description":"Buyer's full name."},"buyer_email":{"type":"string","description":"Buyer's email address."},"buyer_phone":{"type":"string","description":"Buyer's phone number."},"buyer_social_id":{"type":"string","description":"Buyer's national ID number, digits only."},"buyer_zip_code":{"type":"string","description":"Buyer's zip code, letters and digits only; anything else returns error `37`."},"buyer_business_code":{"type":"string","description":"For a business buyer: its registration number. Send it with `buyer_business_name`, or neither."},"buyer_business_name":{"type":"string","description":"For a business buyer: its name. Send it with `buyer_business_code`, or neither."},"buyer_is_permanent":{"type":"boolean","description":"`true`: a permanent token you can charge any number of times. Default `false`: a single-use token; the first `generate-sale` charge deactivates it and later charges fail with error `604`. Subscriptions accept permanent tokens only."},"buyer_is_private":{"type":"boolean","description":"`true`: only this seller (MPL) can charge the token. Default `false`: the token belongs to your account, and any seller of the same partner can charge it."},"buyer_perform_validation":{"type":"boolean","description":"Check the card with the issuer before saving it. Default `true`."},"language":{"type":"string","description":"Language of error messages: `en`, or `he` (the default). `es`, `ru` and `ar` are accepted, but messages then come back mostly in English. Any other value returns error `51`."}},"required":["seller_payme_id","credit_card_number","credit_card_exp"]},"example":{"seller_payme_id":"MPLDEMO-MPLDEMO-MPLDEMO-1234567","credit_card_number":"5326105300985846","credit_card_exp":"1230","credit_card_cvv":"658","buyer_name":"Israel Israeli","buyer_email":"buyer@example.com","buyer_phone":"+972500000000","buyer_social_id":"008336174","buyer_is_permanent":true,"language":"en"}}}},"responses":{"200":{"description":"The card is saved.","x-response-kind":"success","content":{"application/json":{"schema":{"type":"object","properties":{"status_code":{"type":"integer","description":"`0`: the card is saved."},"buyer_key":{"type":"string","description":"The token. Send it as `buyer_key` on `generate-sale`."},"buyer_name":{"type":"string","description":"Buyer's full name."},"buyer_email":{"type":"string","description":"Buyer's email address."},"buyer_phone":{"type":"string","description":"Buyer's phone number."},"buyer_card_mask":{"type":"string","description":"Masked card number, for example `532610******5846`."},"buyer_card_exp":{"type":"string","description":"Card expiry, `MMYY`."},"buyer_social_id":{"type":"string","description":"Buyer's national ID number."},"buyer_is_permanent":{"type":"boolean","description":"`true` for a permanent token, `false` for a single-use token."},"session":{"type":"string","description":"PayMe's ID for this request. Quote it when you contact PayMe."}}},"example":{"status_code":0,"buyer_key":"BUYERDEMO-BUYERDEMO-BUYERDEMO-1234567","buyer_name":"Israel Israeli","buyer_email":"buyer@example.com","buyer_phone":"+972500000000","buyer_card_mask":"532610******5846","buyer_card_exp":"1230","buyer_social_id":"008336174","buyer_is_permanent":true,"session":"Ab12Cd34"}}}},"400":{"description":"Error `20`: a card-like number in a field other than `credit_card_number`.","x-response-kind":"error","content":{"application/json":{"schema":{"type":"object","properties":{"status_code":{"type":"integer","description":"`1`: the request failed."},"status_error_code":{"type":"integer","description":"PayMe's error code. See [Errors](/payments/getting-started/errors)."},"status_error_details":{"type":"string","description":"The error message, in the language you asked for."},"status_additional_info":{"type":"string","description":"Extra detail: usually the field at fault, the sale's current status, or the masked card number."},"session":{"type":"string","description":"PayMe's ID for this request. Quote it when you contact PayMe."}}},"example":{"status_code":1,"status_error_details":"Validation error","status_additional_info":"buyer_name contains invalid data","status_error_code":20,"session":"Ab12Cd34"}}}},"500":{"description":"Request errors and declines. `1`: a required field is missing (named in `status_additional_info`). `251`: unknown seller. `354`, `355`, `356`: invalid CVV, card number or expiry. `37`: invalid `buyer_zip_code`. A decline returns its decline code, such as `20004`, with the masked card number in `status_additional_info`.","x-response-kind":"error","content":{"application/json":{"schema":{"type":"object","properties":{"status_code":{"type":"integer","description":"`1`: the request failed."},"status_error_code":{"type":"integer","description":"PayMe's error code. See [Errors](/payments/getting-started/errors)."},"status_error_details":{"type":"string","description":"The error message, in the language you asked for."},"status_additional_info":{"type":"string","description":"Extra detail: usually the field at fault, the sale's current status, or the masked card number."},"session":{"type":"string","description":"PayMe's ID for this request. Quote it when you contact PayMe."}}},"example":{"status_code":1,"status_error_details":"Refusal by credit company. Please try a different card","status_additional_info":"400000******0002","status_error_code":20004,"session":"Ab12Cd34"}}}}}}},"/generate-sale":{"post":{"operationId":"post-generate-sale-tokenization","summary":"Save a card (token sale)","tags":["Tokenization"],"description":"## Overview\n\nSaves the buyer's card as a token (`buyer_key`) for later server-to-server charges. Send `sale_type: token` to save the card without charging (PayMe sets the price to `100`, which is not charged), or `capture_buyer: 1` on a normal sale to charge and save. The token arrives as `buyer_key` in the callback; you can also read it with [`get-buyer-key`](/payments/tokenization/post-get-buyer-key).\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\n| To | Send |\n|---|---|\n| Save the card without charging | `sale_type: token` |\n| Charge and save the card | `sale_type: sale` (default) and `capture_buyer: 1` |\n| Save a card on a page that can be opened only once | `sale_type: token`, `layout: token-capture` and `sale_should_be_opened_once: true` |\n| Charge a saved card later | `buyer_key` on a new `generate-sale`; see [Create a sale](/payments/hosted-payment-page/post-generate-sale) |\n\nTo charge and save, send the same request as the example with `\"sale_type\": \"sale\"`, your real `sale_price` and `\"capture_buyer\": 1`.\n\nRules:\n\n- Send `buyer_is_private: true` to tie the token to this seller. Without it the token is account-level: any seller of the same partner can charge it, and a `get-buyer-key` call that sends `seller_payme_id` fails with error `603`.\n- Token capture works with `credit-card`, `apple-pay`, `il-direct-debit` and `multi`; other methods return `4`.\n- `product_name` and a numeric `sale_price` are required even when nothing is charged.\n- Store `buyer_key` encrypted: it replaces the card number.\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### 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).","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`."},"sale_type":{"type":"string","description":"`token` – save the card without charging (the price is set to `100`). `sale` (default) – charge; add `capture_buyer: 1` to save the card too. Token capture works with `credit-card`, `apple-pay`, `il-direct-debit` and `multi` (other methods return `4`). The full list is on [Sale Types](/payments/codes-statuses/sale-types)."},"sale_price":{"type":"integer","description":"Amount in minor units. Required, but for a token sale any numeric value works: PayMe replaces it with `100` and charges nothing. A missing or non-numeric value returns `352`. For a charge-and-save sale, the default allowed range is `500`–`4000000`."},"currency":{"type":"string","description":"Sale currency, a 3-letter ISO 4217 code. Optional for a token sale (the account's default currency is used); required to charge."},"product_name":{"type":"string","description":"Short description shown to the buyer and in the seller's records, up to 500 characters. Required, also for token sales (missing returns `353`)."},"capture_buyer":{"type":"string","description":"`1` or `true` to save the buyer's card as a token after the payment; the token arrives as `buyer_key` in the callback. Omit it, or send `0`, to skip. Works with `credit-card`, `apple-pay`, `il-direct-debit` and `multi` (other methods return `4`). Can't be combined with `buyer_key` (`601`)."},"buyer_is_private":{"type":"boolean","description":"With `capture_buyer` or a token sale: `true` ties the token to this seller, so `get-buyer-key` works with the seller's MPL. Without it the token is account-level: any seller of the same partner can charge it, and a `get-buyer-key` call that sends `seller_payme_id` fails with error `603`."},"buyer_perform_validation":{"type":"boolean","description":"With `capture_buyer` or a token sale: whether PayMe validates the card with the issuer before saving the token. Default `true`. Sending `true` without `capture_buyer` or a token sale returns `608`."},"sale_payment_method":{"type":"string","description":"Payment method; see [Available Payment Methods](/payments/wallets-apms). Default `credit-card`. Send `multi` to let the buyer choose among every method enabled on the account. Case-insensitive. An unknown value returns `24`; a method not enabled on the account returns `720` with the method name; `bacs` needs `GBP` and `sepa` needs `EUR` (`320`). Send a string: an array returns `368` (HTTP 400)."},"layout":{"type":"string","description":"Payment page layout: `dynamic` (default), `dynamic-loose` (no social ID or CVV validation), `qr-sms` (Bit: QR code or SMS), `token-capture` (save a card without a charge; requires `sale_type: token`). Other values fall back to `dynamic`."},"sale_should_be_opened_once":{"type":"boolean","description":"`true`: with `layout: token-capture`, the page can be opened only once. Ignored otherwise."},"buyer_key":{"type":"string","description":"To charge a saved token later, on a new `generate-sale`: the call charges it at once, with no payment page. Can't be combined with `capture_buyer` (`601`) or `sale_type: token` (`602`)."},"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."},"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."},"sale_return_url":{"type":"string","description":"Where PayMe redirects the buyer (the iframe or the full page) after a successful payment, with the sale details as query parameters; see [Hosted Payment Page options](/accepting-payments/checkout-and-in-person/hosted-payment-page-options). If omitted, your partner's default return URL is used, if one is set. Same address rules as `sale_callback_url` (error `21`)."},"sale_send_notification":{"type":"boolean","description":"`true`: PayMe sends the buyer a payment request with the payment link, by email to `sale_email` and by SMS to `sale_mobile`. Default `false`."},"sale_email":{"type":"string","description":"Buyer's email. Pre-fills the payment page and receives the payment request when `sale_send_notification` is `true`."},"sale_mobile":{"type":"string","description":"Buyer's mobile number. Pre-fills the payment page and receives the SMS payment request when `sale_send_notification` is `true` and the SMS service is active on the account."},"sale_name":{"type":"string","description":"Buyer's full name. Pre-fills the payment page (split at the first space into first and last name) and is used in notifications."},"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`."}},"required":["seller_payme_id","sale_price","product_name"]},"example":{"seller_payme_id":"MPLDEMO-MPLDEMO-MPLDEMO-1234567","sale_type":"token","sale_price":100,"currency":"ILS","product_name":"Save card","buyer_is_private":true,"sale_callback_url":"https://your-server.example.com/payme/callback","language":"en"}}}},"responses":{"200":{"description":"Token sale created","x-response-kind":"success","content":{"application/json":{"schema":{"type":"object","properties":{"status_code":{"type":"integer","description":"`0` success, `1` error."},"sale_url":{"type":"string","description":"PayMe's payment page for this sale. Show it to the buyer in an iframe or a redirect, exactly as returned. It stays payable while the sale is `initial` or `failed`, until `sale_expiry_seconds` passes if you sent it."},"payme_sale_id":{"type":"string","description":"PayMe's sale ID. Store it: refunds, captures and queries use it."},"payme_sale_code":{"type":"integer","description":"Short numeric sale code, for display only."},"price":{"type":"integer","description":"Sale amount in minor units (`100` for a token sale)."},"transaction_id":{"type":"string","description":"Your order reference, as sent."},"currency":{"type":"string","description":"Sale currency (ISO 4217)."},"sale_payment_method":{"type":"string","description":"Payment method of the sale, for example `credit-card` or `multi`."},"session":{"type":"string","description":"Request ID. Quote it when you contact PayMe."}}},"example":{"status_code":0,"session":"AtsJ0as5","sale_url":"https://sandbox.payme.io/sale/generate/SALE1700-000000AA-EXAMPLE1-SALE0001","payme_sale_id":"SALE1700-000000AA-EXAMPLE1-SALE0001","payme_sale_code":12345678,"price":100,"transaction_id":null,"currency":"ILS","sale_payment_method":"credit-card"}}}},"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"}}}}}}},"/get-buyer-key":{"post":{"operationId":"post-get-buyer-key","summary":"Get the buyer key of a sale or subscription","tags":["Tokenization"],"description":"## Overview\n\nReturns the saved card (`buyer_key`) of a paid sale or of a subscription. Send `payme_sale_id` or `sub_payme_id`, not both.\n\nUse `sub_payme_id` for a subscription whose card was entered on `sub_url`: subscription calls and callbacks never return the `buyer_key`.\n\nFor Israeli direct debit, approving a new authorization creates a buyer key behind the scenes; read it with this call.\n\n### Which credential to send\n\nSend the credential in the JSON body; a `PayMe-Partner-Key` header alone isn't enough.\n\n| The token | Send |\n|---|---|\n| Saved with `buyer_is_private: true` (seller-level) | `seller_payme_id`, or (partners) `payme_client_key` |\n| Saved without it (the default), or a partner-level token | `payme_client_key` only. Adding `seller_payme_id` fails with HTTP 403, error `603` |\n\nA direct seller has no partner key, so it must save the token with `buyer_is_private: true` to read it back.\n\n","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"payme_sale_id":{"type":"string","description":"The paid sale whose saved card you want. Send this or `sub_payme_id`."},"sub_payme_id":{"type":"string","description":"The subscription whose saved card you want. Send this or `payme_sale_id`."},"seller_payme_id":{"type":"string","description":"The seller's MPL, for a seller-level token (saved with `buyer_is_private: true`). Don't send it for an account-level token: that fails with error `603`. Send this or `payme_client_key`."},"payme_client_key":{"type":"string","description":"Partners: your partner key, in the JSON body. Reads both kinds of token when you send no `seller_payme_id`."},"language":{"type":"string","description":"Language of error messages: `en`, or `he` (the default). `es`, `ru` and `ar` are accepted, but messages then come back mostly in English. Any other value returns error `51`."}}},"example":{"payme_client_key":"XXXXXXXX","payme_sale_id":"SALEDEMO-XXXXXXXX-XXXXXXXX-XXXXXXXX","language":"en"}}}},"responses":{"200":{"description":"The saved card.","x-response-kind":"success","content":{"application/json":{"schema":{"type":"object","properties":{"status_code":{"type":"integer","description":"`0`: success."},"payme_sale_id":{"type":"string","description":"The sale you asked about. Returned when you sent `payme_sale_id`."},"sub_payme_id":{"type":"string","description":"The subscription you asked about. Returned instead of `payme_sale_id` when you sent `sub_payme_id`."},"buyer_key":{"type":"string","description":"The saved card's token."},"buyer_card_mask":{"type":"string","description":"Masked card number, for example `532610******5846`."},"buyer_card_expiry":{"type":"string","description":"Card expiry, `MMYY`."},"buyer_card_brand":{"type":"string","description":"Card brand: `MasterCard`, `Visa`, `AmericanExpress`, `Diners`, `Isracard` and so on."},"session":{"type":"string","description":"PayMe's ID for this request. Quote it when you contact PayMe."}}},"example":{"status_code":0,"payme_sale_id":"SALEDEMO-XXXXXXXX-XXXXXXXX-XXXXXXXX","buyer_key":"BUYERDEMO-BUYERDEMO-BUYERDEMO-1234567","buyer_card_mask":"532610******5846","buyer_card_expiry":"1230","buyer_card_brand":"MasterCard","session":"Ab12Cd34"}}}},"400":{"description":"Error `1`: neither `payme_sale_id` nor `sub_payme_id` sent. Error `20`: both sent. Error `600`: no saved card on this sale or subscription, or the sale isn't paid (`status_additional_info` then holds its status, `initial` or `failed`).","x-response-kind":"error","content":{"application/json":{"schema":{"type":"object","properties":{"status_code":{"type":"integer","description":"`1`: the request failed."},"status_error_code":{"type":"integer","description":"PayMe's error code. See [Errors](/payments/getting-started/errors)."},"status_error_details":{"type":"string","description":"The error message, in the language you asked for."},"status_additional_info":{"type":"string","description":"Extra detail: usually the field at fault, the sale's current status, or the masked card number."},"session":{"type":"string","description":"PayMe's ID for this request. Quote it when you contact PayMe."}}},"example":{"status_code":1,"status_error_details":"Buyer not found","status_additional_info":"No Buyer for Sale","status_error_code":600,"session":"Ab12Cd34"}}}},"403":{"description":"Error `603`: `seller_payme_id` sent for an account-level token. Error `303` (sale) or `370` (subscription): it belongs to another partner.","x-response-kind":"error","content":{"application/json":{"schema":{"type":"object","properties":{"status_code":{"type":"integer","description":"`1`: the request failed."},"status_error_code":{"type":"integer","description":"PayMe's error code. See [Errors](/payments/getting-started/errors)."},"status_error_details":{"type":"string","description":"The error message, in the language you asked for."},"status_additional_info":{"type":"string","description":"Extra detail: usually the field at fault, the sale's current status, or the masked card number."},"session":{"type":"string","description":"PayMe's ID for this request. Quote it when you contact PayMe."}}},"example":{"status_code":1,"status_error_details":"Merchant not allowed to use this buyer","status_additional_info":"","status_error_code":603,"session":"Ab12Cd34"}}}},"500":{"description":"Request errors. `1`: neither `payme_client_key` nor `seller_payme_id` in the body. `200`: unknown partner key. `251`: unknown seller. `350`: no sale has this ID. `605`: a seller-level token read with another seller's MPL.","x-response-kind":"error","content":{"application/json":{"schema":{"type":"object","properties":{"status_code":{"type":"integer","description":"`1`: the request failed."},"status_error_code":{"type":"integer","description":"PayMe's error code. See [Errors](/payments/getting-started/errors)."},"status_error_details":{"type":"string","description":"The error message, in the language you asked for."},"status_additional_info":{"type":"string","description":"Extra detail: usually the field at fault, the sale's current status, or the masked card number."},"session":{"type":"string","description":"PayMe's ID for this request. Quote it when you contact PayMe."}}},"example":{"status_code":1,"status_error_details":"Required parameter is missing","status_additional_info":"payme_client_key / seller_payme_id","status_error_code":1,"session":"Ab12Cd34"}}}}}}},"/sellers/{mpl}/tokens":{"post":{"operationId":"post-sellers-mpl-tokens","summary":"Create a partner-level token","tags":["Tokenization"],"description":"## Overview\n\n**For PayMe partners only.** Saves a card as a token that belongs to your partner account, so you can charge it later for any of your sellers. A buyer saves a card while buying from one seller and can then pay another seller without typing it again. A seller-level token can't do that.\n\nThe MPL in the path (the `seller_payme_id` of one of your sellers) identifies your account; the call takes no other key. Treat the MPL as a secret: call this endpoint from your server only, never from a browser. \n\n**This endpoint takes raw card details, so call it only if you are PCI DSS certified.** Without that certification, capture the same kind of token on a page PayMe hosts: send [`generate-sale`](/payments/hosted-payment-page/post-generate-sale) with `sale_type: \"seller-token\"` and show the buyer its `sale_url`. PayMe sets the price of such a sale itself.\n\n## Using the token\n\nThe token is the `uuid` in the response. Send it as `token` on `generate-sale`, with the `seller_payme_id` of the seller you are charging for. It is not a `buyer_key`: sent as `buyer_key`, it fails with error `600`. Against a seller of a different partner it fails with error `605`.\n\nThe token is permanent: it doesn't expire in PayMe, and each charge with it runs at once, with no CVV and no 3D Secure. A charge can still fail if the card has expired or the issuer declines it. \n\nThe response isn't PayMe's usual envelope. A success has no `status_code`, so check for HTTP 201 and a `uuid`. A failure has the usual `status_code: 1` and `status_error_code`; decide from those, not from the HTTP status.\n\nA token is a bearer credential: store it encrypted, and never log it or send it to a browser. See [Saved Cards](/agents/steps/saved-cards) for the rules.\n\nThis page covers `credit-card`, the method checked in the sandbox.","parameters":[{"name":"mpl","in":"path","required":true,"description":"The `seller_payme_id` (MPL) of one of your sellers. It identifies your partner account, so keep it secret and send it from your server only. The token is stored under this seller and can be charged for your other sellers too.","schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"payment":{"type":"object","description":"The card to save."},"payment.method":{"type":"string","description":"`credit-card`."},"payment.card_number":{"type":"string","description":"Card number, digits only."},"payment.card_expiry":{"type":"string","description":"Card expiry, `MMYY`."},"payment.card_cvv":{"type":"string","description":"CVV, 3 or 4 digits. Required unless `options.use_token_terminal` is `true`; missing, it returns error `1`."},"customer":{"type":"object","description":"The buyer."},"customer.name":{"type":"string","description":"Buyer's full name. Missing: error `1`."},"customer.email":{"type":"string","description":"Buyer's email address. Missing or invalid: error `13`."},"customer.phone":{"type":"string","description":"Buyer's phone number. Missing: error `1`."},"customer.social_id":{"type":"string","description":"Buyer's Israeli ID number. When sent, it must be a valid Israeli ID."},"customer.zip_code":{"type":"string","description":"Buyer's zip code."},"customer.country":{"type":"string","description":"Buyer's country, a two-letter code such as `IL`."},"customer.state":{"type":"string","description":"Buyer's state or region."},"customer.city":{"type":"string","description":"Buyer's city."},"customer.line1":{"type":"string","description":"Buyer's street address."},"customer.line2":{"type":"string","description":"Buyer's address, second line."},"customer.business_code":{"type":"string","description":"For a business buyer: its registration number. Send it with `customer.business_name`, or neither."},"customer.business_name":{"type":"string","description":"For a business buyer: its name. Send it with `customer.business_code`, or neither."},"options":{"type":"object","description":"Token options."},"options.validate_token":{"type":"boolean","description":"Check the card with the issuer before saving it. Default `true`."},"options.use_token_terminal":{"type":"boolean","description":"`true` to save the card without a CVV, on a token terminal. Then `payment.card_cvv` is optional. Default `false`."}},"required":["payment","payment.method","payment.card_number","payment.card_expiry","customer","customer.name","customer.email","customer.phone"]},"example":{"payment":{"method":"credit-card","card_number":"4557430402053431","card_expiry":"1230","card_cvv":"200"},"customer":{"name":"First Last","email":"buyer@example.com","phone":"+972501234567","social_id":"008336174"}}}}},"responses":{"201":{"description":"The token was created","x-response-kind":"success","content":{"application/json":{"schema":{"type":"object","properties":{"uuid":{"type":"string","description":"The token. Send it as token on generate-sale."},"customer":{"type":"object","description":"name, email, phone and social_id"},"payment":{"type":"object","description":"display (the masked card number), expiry, brand, club, type, organization, origin_country and is_foreign"}}},"example":{"uuid":"00000000-0000-0000-0000-000000000000","customer":{"name":"First Last","email":"buyer@example.com","phone":"+972501234567","social_id":"008336174"},"payment":{"display":"455743******3431","expiry":"1230","brand":"Visa"}}}}},"400":{"description":"The card was declined or failed validation. Read `status_code` and `status_error_code`.","x-response-kind":"error","content":{"application/json":{"schema":{"type":"object","properties":{"status_code":{"type":"integer","description":"`1`: the request failed."},"status_error_code":{"type":"integer","description":"PayMe's error code, such as `20004` for a declined card."},"status_error_details":{"type":"string","description":"The error message."},"status_additional_info":{"type":"string","description":"More detail, such as the masked card number."}}},"example":{"status_code":1,"status_error_code":20004,"status_error_details":"Refusal by credit company. Please try a different card","status_additional_info":"400000******0002"}}}},"500":{"description":"A required field is missing or invalid","x-response-kind":"error","content":{"application/json":{"schema":{"type":"object","properties":{"status_code":{"type":"integer","description":"1"},"status_error_code":{"type":"integer","description":"`1` for a missing field (`customer.name`, `customer.phone`, `payment.card_cvv` and so on), named in `status_additional_info`. `13` for a missing or invalid email."},"status_error_details":{"type":"string","description":"The error message"},"status_additional_info":{"type":"string","description":"The field at fault, when there is one"}}},"example":{"status_code":1,"status_error_code":1,"status_error_details":"Required parameter is missing","status_additional_info":"payment.card_cvv"}}}}}}}}}