https://sandbox.payme.io/api
{
"openapi": "3.1.0",
"info": {
"title": "Hosted Payment Page",
"version": "1.0",
"description": "Our Hosted Payment Page is an exhaustive solution for sellers that are not PCI DSS compliant and cannot hold card details. It allows you to receive payments in various ways (card payments, bank payments and alternative payment methods) as the payment/checkout page is fully hosted by PayMe."
},
"servers": [
{
"url": "https://sandbox.payme.io/api",
"description": "Staging"
},
{
"url": "https://live.payme.io/api",
"description": "Production "
}
],
"paths": {
"/generate-sale": {
"post": {
"summary": "Generate Payment",
"operationId": "post-generate-sale",
"responses": {
"200": {
"description": "Sale Created Successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"x-examples": {
"example-1": {
"status_code": 0,
"sale_url": "https://preprod.paymeservice.com/sale/generate/XXXXXXXX-XXXXXXXX-XXXXXXXX-XXXXXXXX",
"payme_sale_id": "XXXXXXXX-XXXXXXXX-XXXXXXXX-XXXXXXXX",
"payme_sale_code": 12345678,
"price": 10000,
"transaction_id": "12345",
"currency": "USD"
}
},
"properties": {
"status_code": {
"type": "number",
"description": "Status of the request (0 - success, 1 - error)",
"enum": [
0,
1
]
},
"sale_url": {
"type": "string",
"description": "The URL of the IFRAME secured payment form to display to the buyer",
"example": "https://sandbox.paymeservice.com/sale/generate/XXXXXXXX-XXXXXXXX-XXXXXXXX-XXXXXXXX"
},
"payme_sale_id": {
"type": "string",
"description": "Our unique sale ID",
"pattern": "XXXXXXXX-XXXXXXXX-XXXXXXXX-XXXXXXXX"
},
"payme_sale_code": {
"type": "number",
"description": "Our unique sale code (for display purposes only)",
"example": 12345678
},
"price": {
"type": "number",
"description": "Sale final price. For example, if the price is 50.75 (max 2 decimal points) the value that needs to be sent is 5075",
"example": 10000
},
"transaction_id": {
"type": "string",
"description": "Merchant's unique sale ID for correlation with us",
"example": "12345"
},
"currency": {
"type": "string",
"description": "Sale currency. [3-letter ISO 4217 name](https://en.wikipedia.org/wiki/ISO_4217).",
"example": "ILS"
}
}
},
"examples": {
"example-1": {
"value": {
"status_code": 0,
"sale_url": "string",
"payme_sale_id": "string",
"payme_sale_code": 12345678,
"price": 10000,
"transaction_id": "12345",
"currency": "string"
}
}
}
}
}
},
"500": {
"description": "Missing Required Information",
"content": {
"application/json": {
"schema": {
"description": "",
"type": "object",
"x-examples": {
"example-1": {
"status_code": 1,
"status_error_details": "קישור משתמש לא נמצא",
"status_additional_info": null,
"status_error_code": 251
}
},
"properties": {
"status_code": {
"type": "number",
"example": 0
},
"status_error_details": {
"type": "string",
"example": "Contact our Support team for further information"
},
"status_additional_info": {},
"status_error_code": {
"type": "number",
"example": 420
}
},
"required": [
"status_code",
"status_error_details",
"status_error_code"
]
},
"examples": {
"example-1": {
"value": {
"status_code": 0,
"status_error_details": "string",
"status_additional_info": null,
"status_error_code": 0
}
}
}
}
}
}
},
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"seller_payme_id": {
"type": "string",
"description": "MPL. Your private key in PayMe system.",
"example": "MPLDEMO-MPLDEMO-MPLDEMO-1234567"
},
"sale_price": {
"type": "number",
"description": "Sale final price.
\nFor example, if the price is 50.75 (max 2 decimal points) the value that needs to be sent is 5075.
\nNote that the minimum value is 500.",
"example": 100,
"default": 0
},
"currency": {
"type": "string",
"description": "Sale currency. [3-letter ISO 4217 name](https://en.wikipedia.org/wiki/ISO_4217).",
"example": "ILS"
},
"product_name": {
"type": "string",
"description": "Short name and description of the product/service.
\nThis text will be shown in the invoice as well, if the seller has enabled the invoices module in his account panel.
\nLimited to 500 characters",
"example": "Phone"
},
"transaction_id": {
"type": "string",
"description": "Merchant's unique sale ID for correlation with us",
"example": "12345"
},
"installments": {
"type": "string",
"description": "Amount of installments for the sale.\nWe allow you to manually set the number of installments or to specify a top limit of installments for the buyer to choose from while paying.
\nSetting a fixed number of installments is simply entering a number between 1 and 12.
\nThe sale will be initiated with this number of installments and the buyer will not be able to change it.
To set a range for the buyer to choose from, enter the following:
\n`103` - allow up to 3 installments
\n`106` - allow up to 6 installments
\n`109` - allow up to 9 installments
\n`112` - allow up to 12 installments",
"example": "1"
},
"market_fee": {
"type": "number",
"description": "A decimal representing the percent of the sale price that is collected for the marketplace (includes VAT).
\nThis fee is added on top of our fees and transferred to the marketplace once a month.
\nDefault value is the market fee of the Seller, as set upon Seller creation.",
"example": 0.5
},
"sale_send_notification": {
"type": "boolean",
"description": "Flag to send email and/or SMS notifications"
},
"sale_callback_url": {
"type": "string",
"description": "Callback response to your page regarding call to our API. Default value is taken from the Merchant's settings. Note that you may not send a \"localhost\" URL as value",
"example": "https://www.example.com/payment/callback"
},
"sale_email": {
"type": "string",
"description": "In case sale send notification is true provide the address to send email notification",
"example": "test@testmail.com"
},
"sale_return_url": {
"type": "string",
"description": "We will redirect the IFRAME and the buyer to this URL upon payment success. Default value is taken from the Merchant's settings",
"example": "https://www.example.com/payment/success"
},
"sale_mobile": {
"type": "string",
"description": "In case sale send notification is true, provide the phone number to send SMS notification, if the seller has enabled the SMS module in his account panel",
"example": "+972525888888"
},
"sale_name": {
"type": "string",
"description": "The name that will be displayed when sending a notification",
"example": "John Doe"
},
"capture_buyer": {
"type": "string",
"description": "Flag for requesting the buyer's token for this payment (0 - do not capture token, 1 - capture token). For additional information see Tokens explanation below",
"example": "0"
},
"buyer_perform_validation": {
"type": "string",
"x-stoplight": {
"id": "wy06gtboqqp67"
},
"description": "Flag for performing an online validation of the card with the Issuer."
},
"sale_type": {
"type": "string",
"example": "sale",
"description": "You can find all the sale types [here](https://payme.stoplight.io/docs/guides/branches/main/okab0oj46ivn7-sale-types)."
},
"sale_payment_method": {
"type": "string",
"description": "the Payment method used to pay the sale.
\r\nFor all the payment methods [click here](https://payme.stoplight.io/docs/payments/branches/V1.5/zqjehf9tm2jnk-payment-methods).",
"example": "credit-card"
},
"layout": {
"type": "string",
"description": "IFRAME payment page layout. Optional attribute which may be used with \"bit\" sale_payment_method. Avai lable layouts are:dynamic, qr-sms or dynamic-loose \ndynamic loose removes the validation for the social ID and CVV.",
"example": "dynamic"
},
"language": {
"type": "string",
"description": "Changes the language of the payment IFRAME to English, as well as the error messages. Default value is Hebrew (he)",
"example": "he"
},
"order_number": {
"type": "string",
"description": "Purchase Order Number",
"example": "6545584"
},
"items": {
"type": "array",
"description": "This is an object that should include multiple arrays. An array for each product (item) that is a part of this sale.",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"example": "shirt",
"description": "Name of items\nMaximum length: 26 characters"
},
"quantity": {
"type": "number",
"example": 1,
"description": "Number of items\nMaximum length: 12 digits"
},
"unit_price": {
"type": "number",
"example": 500,
"description": "Price of single unit in pennies\nMaximum length: 12 digits"
},
"unit_measurement": {
"type": "string",
"description": "Unit of measurment \nMaximum length: 12 characters",
"example": "\"pounds\""
},
"total": {
"type": "number",
"description": "Total Price After Discount\nMaximum length: 12 digits",
"example": 100
},
"discount_total": {
"type": "number",
"description": "In negative pennies amount\nMaximum length: 12 digits",
"example": 50
},
"description": {
"type": "string",
"description": "Maximum length: 26 characters",
"example": "\"free text\""
},
"product_code": {
"type": "string",
"description": "Maximum length: 12 characters",
"example": "\"ab123\""
},
"commodity_code": {
"type": "number",
"description": "Maximum length: 12 digits",
"example": 123456789101
}
}
}
},
"fees": {
"type": "object",
"description": "Amount of tax in pennies",
"properties": {
"tax": {
"type": "number",
"description": "The tax collected as a part of the payment - In pennies\nMaximum Length: 12 Digits",
"example": 5200
},
"duty": {
"type": "number",
"description": "The international fees collected as a part of the payment - In pennies\nMaximum Length: 12 Digits",
"example": 6000
},
"discount": {
"type": "number",
"description": "The total discount given for the payment - In pennies\nMaximum Length: 12 Digits",
"example": 8000
},
"shipping": {
"type": "number",
"description": "The shipping cost charged as a part of the payment - In pennies\nMaximum Length: 12 Digits",
"example": 10000
}
}
},
"shipping_details": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Individual's full name/Company's name\nMaximum Length: 50 Characters",
"example": "John Doe"
},
"email": {
"type": "string",
"description": "Email address of the addressee\nMaximum Length: 100 Characters",
"example": "test@payme.io"
},
"phone": {
"type": "string",
"description": "Phone number of the addressee \nMaximum Length: 50 Characters",
"example": "+111174448863"
},
"address": {
"type": "object",
"description": "Address Object",
"properties": {
"line1": {
"type": "string",
"description": "Line 1 of the shipping address\nNo Limits.",
"example": "123 Hollywood St."
},
"line2": {
"type": "string",
"description": "Line 1 of the shipping address\nNo Limits.",
"example": "Building A"
},
"postal_code": {
"type": "string",
"description": "Postal code of the shipping address\nNo Limits.",
"example": "1234567"
},
"city": {
"type": "string",
"description": "City of the shipping address\nNo Limits.",
"example": "Miami"
},
"state": {
"type": "string",
"example": "Florida",
"description": "State of the shipping address\nNo Limits."
},
"country": {
"type": "string",
"description": "Country of the shipping address\nNo Limits.",
"example": "US"
}
}
}
}
},
"billing_details": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Individual's full name/Company's name\nNo Limits.",
"example": "PayMe"
},
"email": {
"type": "string",
"description": "Email address of the payer\nNo Limits.",
"example": "payer@payme.io"
},
"phone": {
"type": "string",
"description": "Phone number of the payer\nNo Limits.",
"example": "+111174448863"
},
"address": {
"type": "object",
"properties": {
"line1": {
"type": "string",
"description": "Line 1 of the billing address\nNo Limits.",
"example": "123 Hollywood St."
},
"line2": {
"type": "string",
"example": "Building A",
"description": "Line 2 of the billing address\nNo Limits."
},
"postal_code": {
"type": "string",
"example": "1234567",
"description": "Postal code of the billing address\nNo Limits."
},
"city": {
"type": "string",
"description": "City of the billing address\nNo Limits.",
"example": "Miami"
},
"state": {
"type": "string",
"description": "State of the shipping address\nNo Limits.",
"example": "Florida"
},
"country": {
"type": "string",
"description": "Country of the billing address\nNo Limits.",
"example": "US"
}
}
}
}
},
"buyer_name": {
"type": "string",
"x-stoplight": {
"id": "9zwn4eu0recee"
},
"description": "Buyer's name",
"example": "John Doe"
},
"buyer_social_id": {
"type": "string",
"x-stoplight": {
"id": "cgh15ja4vaf1b"
},
"description": "Buyer's social ID",
"example": "123456789"
},
"buyer_email": {
"type": "string",
"x-stoplight": {
"id": "b4lu5siskn9eb"
},
"description": "Buyer's email",
"example": "buyer@email.com"
},
"buyer_phone": {
"type": "string",
"x-stoplight": {
"id": "3kdndcsfmbxvu"
},
"description": "Buyer's phone",
"example": "0501234567"
}
},
"required": [
"seller_payme_id",
"sale_price",
"currency",
"product_name"
]
},
"examples": {
"New Sale": {
"value": {
"seller_payme_id": "MPLDEMO-MPLDEMO-MPLDEMO-1234567",
"sale_price": 1000,
"currency": "ILS",
"product_name": "Smartphone",
"transaction_id": "12345",
"installments": "1",
"market_fee": 0.5,
"sale_send_notification": true,
"sale_callback_url": "https://www.payme.io",
"sale_email": "test@payme.io",
"sale_return_url": "https://www.payme.io",
"sale_mobile": "+9725254448888",
"sale_name": "Test User",
"capture_buyer": false,
"buyer_perform_validation": false,
"sale_type": "sale",
"sale_payment_method": "credit-card",
"layout": "string",
"language": "he"
}
},
"Sale with Level 2/3 Data": {
"value": {
"seller_payme_id": "MPLDEMO-MPLDEMO-MPLDEMO-1234567",
"sale_price": 0,
"currency": "ILS",
"product_name": "Phone",
"transaction_id": "12345",
"installments": "1",
"market_fee": 0.5,
"sale_send_notification": true,
"sale_callback_url": "https://www.example.com/payment/callback",
"sale_email": "test@testmail.com",
"sale_return_url": "https://www.example.com/payment/success",
"sale_mobile": "+972525888888",
"sale_name": "John Doe",
"capture_buyer": "0",
"buyer_perform_validation": false,
"sale_type": "sale",
"sale_payment_method": "credit-card",
"layout": "string",
"language": "he",
"order_number": "6545584",
"items": [
{
"name": "shirt",
"quantity": 1,
"unit_price": 0,
"unit_measurement": "string",
"total": 0,
"discount_total": 0,
"description": "string",
"product_code": "string",
"commodity_code": "123546"
}
],
"fees": {
"tax": 5200,
"duty": 6000,
"discount": 8000,
"shipping": 10000
},
"shipping_details": {
"name": "John Doe",
"email": "test@payme.io",
"phone": "+111174448863",
"address": {
"line1": "123 Hollywood St.",
"line2": "Building A",
"postal_code": "1234567",
"city": "Miami",
"state": "Florida",
"country": "US"
}
},
"billing_details": {
"name": "PayMe",
"email": "payer@payme.io",
"phone": "+111174448863",
"address": {
"line1": "123 Hollywood St.",
"line2": "Building A",
"postal_code": "1234567",
"city": "Miami",
"state": "Florida",
"country": "US"
}
}
}
},
"Multi Payment Page": {
"value": {
"seller_payme_id": "MPLDEMO-MPLDEMO-MPLDEMO-1234567",
"sale_price": 150000,
"currency": "ILS",
"product_name": "Computer",
"transaction_id": "12345",
"installments": "0",
"market_fee": 0.5,
"sale_send_notification": true,
"sale_callback_url": "https://www.payme.io",
"sale_email": "test@payme.io",
"sale_return_url": "https://www.payme.io",
"sale_mobile": "+9725254448888",
"sale_name": "Test User",
"capture_buyer": false,
"buyer_perform_validation": false,
"sale_type": "template",
"sale_payment_method": "credit-card",
"layout": "string",
"language": "he"
}
},
"Pay with Existing Token": {
"value": {
"seller_payme_id": "MPLDEMO-MPLDEMO-MPLDEMO-1234567",
"sale_price": 150000,
"currency": "ILS",
"product_name": "Computer",
"transaction_id": "12345",
"installments": "0",
"market_fee": 0.5,
"sale_send_notification": true,
"sale_callback_url": "https://webhook.site/1dc520cf-c70f-4119-9e06-ceffbdad6196",
"sale_email": "test@payme.io",
"sale_return_url": "https://www.payme.io",
"sale_mobile": "+9725254448888",
"sale_name": "Test User",
"capture_buyer": false,
"buyer_perform_validation": false,
"sale_type": "token",
"sale_payment_method": "credit-card",
"layout": "string",
"language": "he"
}
},
"New Authorization": {
"value": {
"seller_payme_id": "MPLDEMO-MPLDEMO-MPLDEMO-1234567",
"sale_price": 150000,
"currency": "ILS",
"product_name": "Computer",
"transaction_id": "12345",
"installments": "0",
"market_fee": 0.5,
"sale_send_notification": true,
"sale_callback_url": "https://www.payme.io",
"sale_email": "test@payme.io",
"sale_return_url": "https://www.payme.io",
"sale_mobile": "+9725254448888",
"sale_name": "Test User",
"capture_buyer": false,
"buyer_perform_validation": false,
"sale_type": "authorize",
"sale_payment_method": "credit-card",
"layout": "string",
"language": "he"
}
}
}
},
"application/xml": {
"schema": {
"type": "object",
"properties": {
"seller_payme_id": {
"type": "string",
"description": "Our unique seller ID\n\n",
"pattern": "XXXXXXXX-XXXXXXXX-XXXXXXXX-XXXXXXXX"
},
"sale_price": {
"type": "number",
"description": "Sale final price. For example, if the price is 50.75 (max 2 decimal points) the value that needs to be sent is 5075. Note that the minimum value is 500\n\n",
"example": 10000
},
"currency": {
"type": "string",
"description": "Sale currency. 3-letter ISO 4217 name\n\n",
"pattern": "USD`"
},
"product_name": {
"type": "string",
"description": "Short name and description of the product/service. This text will be shown in the invoice as well, if the seller has enabled the invoices module in his account panel. Limited to 500 characters\n\n",
"example": "Smartphone"
},
"transaction_id": {
"type": "string",
"description": "Merchant's unique sale ID for correlation with us\n\n",
"pattern": "12345"
},
"installments": {
"type": "string",
"description": "Amount of installments for the sale. For additional information see Note 1 below\n\n",
"pattern": "1"
},
"market_fee": {
"type": "number",
"description": "A decimal between 0.00 and 60.00 representing the percent of the sale price that is collected for the marketplace (includes VAT). This fee is added on top of our fees and transferred to the marketplace once a month. Default value is the market fee of the Seller, as set upon Seller creation\n\n",
"example": 2.5
},
"sale_callback_url": {
"type": "string",
"description": "Callback response to your page regarding call to our API. Default value is taken from the Merchant's settings. Note that you may not send a \"localhost\" URL as value\n\n",
"pattern": "https://www.example.com/payment/callback"
},
"sale_return_url": {
"type": "string",
"description": "We will redirect the IFRAME and the buyer to this URL upon payment success. Default value is taken from the Merchant's settings\n\n",
"pattern": "https://www.example.com/payment/success`"
},
"sale_send_notification": {
"description": "Flag to send email and/or SMS notifications\n\n",
"type": "boolean"
},
"sale_email": {
"type": "string",
"description": "In case sale send notification is true provide the address to send email notification\n\n",
"example": "duckshop@example.com`"
},
"sale_mobile": {
"type": "string",
"description": "In case sale send notification is true, provide the phone number to send SMS notification, if the seller has enabled the SMS module in his account panel\n\n",
"pattern": "123456789"
},
"sale_name": {
"type": "string",
"description": "The name that will be displayed when sending a notification\n\n",
"pattern": "John"
},
"capture_buyer": {
"type": "string",
"description": "Flag for requesting the buyer's token for this payment (0 - do not capture token, 1 - capture token). For additional information see Tokens explanation below\n\n",
"pattern": "0"
},
"buyer_key": {
"type": "string",
"description": "Buyer key for an instant-payment with the token. This key is received through the use of capture_buyer. Note that this attribute cannot co-exist with the capture_buyer parameter in the same request\n\n",
"pattern": "XXXXXXXX-XXXXXXXX-XXXXXXXX-XXXXXXXX"
},
"buyer_perform_validation": {
"type": "boolean",
"description": "Flag for performing an online validation of the card with the Issuer. Default value is true\n\n"
},
"sale_payment_method": {
"type": "string",
"description": "Sale payment method. Available methods are: credit-card, bit, paypal, sepa, bacs, echeck, alipay-qr, funds-transfer. Default value is credit-card\n\n",
"pattern": "credit-card"
},
"layout": {
"type": "string",
"description": "IFRAME payment page layout. Optional attribute which may be used with \"bit\" sale_payment_method. Available layouts are: dynamic, qr-sms. Default value is dynamic\n\n"
},
"language": {
"type": "string",
"description": "Changes the language of the payment IFRAME to English, as well as the error messages. Default value is Hebrew (he)\n\n",
"pattern": "en"
},
"": {
"type": "string"
}
},
"required": [
"seller_payme_id",
"sale_price",
"currency",
"product_name",
"installments"
]
}
},
"multipart/form-data": {
"schema": {
"type": "object",
"properties": {}
}
}
},
"description": ""
},
"description": "\n## Overview\n\n\nThis endpoint can be used for the following actions:\n\nAction | Description\n----|----\nBasic Sale (J4) | Allows you to create a sale.\nAothorization (J5)| The requested amount gets reserved (blocked) on the credit card of the buyer for up to 168 hours.
You can find more information in our [Capture Sale Guide](https://payme.stoplight.io/docs/guides/branches/main/5hztg1usesrsf-capture-sale-authorization).\nMulti Payment Page | Enables payments on a single sale link, by multiple buyers.
You can find more information in our [Multi Payment Page Guide](https://payme.stoplight.io/docs/guides/branches/main/cij4imxt4y3z2-multi-payment-page).\n Create Payment With Buyer Key (Token)| Enables to capture token once the buyer pays (enter the payment details).
You can find more information in our [Create Payment With Buyer Key (Token) Guide](https://payme.stoplight.io/docs/guides/branches/main/dpm16r1dqtjs0-create-payment-with-buyer-key-token).\n\n\n**You can find examples of the request body in the top-right corner under \"Examples\".**\n\n* For all the sale types [click here](https://payme.stoplight.io/docs/guides/branches/main/okab0oj46ivn7-sale-types).\n* For all the payment methods [click here](https://payme.stoplight.io/docs/payments/branches/V1.5/zqjehf9tm2jnk-payment-methods).\n\n\n#### Callbacks\nOnce the sale is paid successfully, we will notify the marketplace with the sale details with a POST of `type` `x-www-form-urlencoded` request to the marketplace Callback URL.
\nYou can find the sale callback attributes [here](https://payme.stoplight.io/docs/guides/branches/main/i90qmmbdut067-sale-callbacks).\n\n#### Issuing an Invoice for a Business\nIn the case where you are connected to our invoices services, you can send the following parameters as a part of your `generate-sale` API request to us when paying using a Token (saved card) in our platform.\n\nPlease add the following parameters to your request:\nParameter Name|Parameter Type|Example & Limitations\n--|--|--\n`buyer_business_name`| `string` | The name of the business the invoice should be issued for.\n`buyer_business_code` | `integer` | The business code (VAT identifier) of the company the invoice is issued for. "
},
"parameters": []
}
},
"components": {
"schemas": {}
}
}
