# Generate Payment with Token

This is a variant of [POST /generate-sale — Generate Payment](/payments-migrated/hosted-payment-page/post-generate-sale); the request and responses below are the ones documented for Hosted Fields - JSAPI.

- Sandbox: `POST https://sandbox.payme.io/api/generate-sale`
- Production: `POST https://live.payme.io/api/generate-sale`

## Credentials

- Request body field `seller_payme_id` (required): MPL. Your private key in PayMe system.

## Overview


This endpoint can be used for the following actions:

Action | Description
----|----
Basic Sale (J4) | Allows you to create a sale.
Authorization (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](/guides-and-use-cases-migrated/payments/capture-sale).


Please note that you have to create a payment with token (Buyer Key). That 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](/guides-and-use-cases-migrated/payments/create-payment-with-buyer-key-token).


**See the request example below.**

* For all the sale types see [Sale Types](/guides-and-use-cases-migrated/lists-statuses/sale-types).



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

You can find the sale callback attributes [Sale Callbacks](/guides-and-use-cases-migrated/lists-statuses/sale-callbacks).

#### Issuing an Invoice for a Business
In 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.

Please add the following parameters to your request:
Parameter Name|Parameter Type|Example & Limitations
--|--|--
`buyer_business_name`| `string` | The name of the business the invoice should be issued for.
`buyer_business_code` | `integer` | The business code (VAT identifier) of the company the invoice is issued for.

## Parameters

This endpoint takes no path, query or header parameters.

## Request body

Content type: `application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `seller_payme_id` | string | yes | MPL. Your private key in PayMe system. |
| `sale_price` | number | yes | 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. |
| `currency` | string | yes | Sale currency. [3-letter ISO 4217 name](https://en.wikipedia.org/wiki/ISO_4217). |
| `product_name` | string | yes | 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 |
| `transaction_id` | string | no | Merchant's unique sale ID for correlation with us |
| `installments` | string | no | Amount of installments for the sale. We 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. Setting a fixed number of installments is simply entering a number between 1 and 12. The 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: `103` - allow up to 3 installments `106` - allow up to 6 installments `109` - allow up to 9 installments `112` - allow up to 12 installments |
| `market_fee` | number | no | A decimal 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. |
| `sale_send_notification` | boolean | no | Flag to send email and/or SMS notifications |
| `sale_callback_url` | string | no | 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 |
| `sale_email` | string | no | In case sale send notification is true provide the address to send email notification |
| `sale_return_url` | string | no | We will redirect the IFRAME and the buyer to this URL upon payment success. Default value is taken from the Merchant's settings |
| `sale_mobile` | string | no | 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 |
| `sale_name` | string | no | The name that will be displayed when sending a notification |
| `capture_buyer` | string | no | 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 |
| `buyer_perform_validation` | boolean | no | Flag for performing an online validation of the card with the Issuer. |
| `sale_type` | string | no | You can find all the sale types [Sale Types](/guides-and-use-cases-migrated/lists-statuses/sale-types). |
| `sale_payment_method` | string | no | the Payment method used to pay the sale. For all the payment methods see [Available Payment Methods](/payments-migrated/direct-api/available-payment-methods). |
| `layout` | string | no | 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 dynamic loose removes the validation for the social ID and CVV. |
| `language` | string | no | Changes the language of the payment IFRAME to English, as well as the error messages. Default value is Hebrew (he) |
| `order_number` | string | no | Purchase Order Number |
| `items` | array | no | This is an object that should include multiple arrays. An array for each product (item) that is a part of this sale. |
| `items[].name` | string | no | Name of the Item Minimum length: 1 Character Maximum length: 50 Characters |
| `items[].quantity` | integer | no | Number of items, Minimum length: 0 digits, Maximum length: 6 digits |
| `items[].unit_price` | integer | no | Price of single unit in pennies, No length limitations |
| `items[].unit_measurement` | string | no | Unit of measurment, Minimum length: 0 characters (nullable), Maximum length: 12 characters |
| `items[].total` | integer | no | Total Price After Discount, Minimum length: 0 digits, Maximum length: 10 digits |
| `items[].discount_total` | number | no | In negative pennies amount, Minimum length: 0 digits (nullable), Maximum length: 12 digits |
| `items[].description` | string | no | The item description, Minimum length: 0 characters (nullable, Maximum length: 150 characters |
| `items[].product_code` | string | no | The item catalog code. Minimum length: 0 characters (nullable), Maximum length: 100 characters |
| `items[].commodity_code` | number | no | The item's commodity code, Minimum length: 0 digits (nullable), Maximum length: unlimited |
| `fees` | object | no | Amount of tax in pennies |
| `fees.tax` | number | no | The tax collected as a part of the payment - In pennies, Minimum length: 0, Maximum Length: 12 Digits |
| `fees.duty` | number | no | The international fees collected as a part of the payment - In pennies, Minimum lenth: 0, Maximum Length: 12 Digits |
| `fees.discount` | number | no | The total discount given for the payment - In pennies, Minimum length: 0, Maximum Length: 12 Digits |
| `fees.shipping` | number | no | The shipping cost charged as a part of the payment - In pennies, Minimum lenth: 0, Maximum Length: 12 Digits |
| `shipping_details` | object | no |  |
| `shipping_details.name` | string | no | Individual's full name/Company's name, Maximum Length: 50 Characters |
| `shipping_details.email` | string | no | Email address of the addressee, Maximum Length: 100 Characters |
| `shipping_details.phone` | string | no | Phone number of the addressee, Maximum Length: 50 Characters |
| `shipping_details.address` | object | no | Address Object |
| `shipping_details.address.line1` | string | no | Line 1 of the shipping address, No Limits. |
| `shipping_details.address.line2` | string | no | Line 1 of the shipping address, No Limits. |
| `shipping_details.address.postal_code` | string | no | Postal code of the shipping address, No Limits. |
| `shipping_details.address.city` | string | no | City of the shipping address, No Limits. |
| `shipping_details.address.state` | string | no | State of the shipping address, No Limits. |
| `shipping_details.address.country` | string | no | Country of the shipping address, No Limits. |
| `billing_details` | object | no |  |
| `billing_details.name` | string | no | Individual's full name/Company's name, No Limits. |
| `billing_details.email` | string | no | Email address of the payer, No Limits. |
| `billing_details.phone` | string | no | Phone number of the payer, No Limits. |
| `billing_details.address` | object | no |  |
| `billing_details.address.line1` | string | no | Line 1 of the billing address, No Limits. |
| `billing_details.address.line2` | string | no | Line 2 of the billing address, No Limits. |
| `billing_details.address.postal_code` | string | no | Postal code of the billing address No Limits. |
| `billing_details.address.city` | string | no | City of the billing address, No Limits. |
| `billing_details.address.state` | string | no | State of the shipping address, No Limits. |
| `billing_details.address.country` | string | no | Country of the billing address, No Limits. |

### Request example

```json
{
  "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"
}
```

## Code samples

### curl

```bash
curl -X POST 'https://sandbox.payme.io/api/generate-sale' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "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"
}'
```

### Node.js

```javascript
const response = await fetch("https://sandbox.payme.io/api/generate-sale", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "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"
  }),
});

console.log(await response.text());
```

### Python

```python
import requests

response = requests.post(
    "https://sandbox.payme.io/api/generate-sale",
    json={
        "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",
    },
)

print(response.text)
```

### PHP

```php
<?php

$body = <<<'BODY'
{
  "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"
}
BODY;

$ch = curl_init('https://sandbox.payme.io/api/generate-sale');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => $body,
]);

$response = curl_exec($ch);
curl_close($ch);

echo $response;
```

## Responses

### 200 — Sale Created Successfully (success)

| Field | Type | Description |
| --- | --- | --- |
| `status_code` | number | Status of the request (0 - success, 1 - error) |
| `sale_url` | string | The URL of the IFRAME secured payment form to display to the buyer |
| `payme_sale_id` | string | Our unique sale ID |
| `payme_sale_code` | number | Our unique sale code (for display purposes only) |
| `price` | number | Sale final price. For example, if the price is 50.75 (max 2 decimal points) the value that needs to be sent is 5075 |
| `transaction_id` | string | Merchant's unique sale ID for correlation with us |
| `currency` | string | Sale currency. 3-letter ISO 4217 name |

```json
{
  "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"
}
```

### 500 — Missing Required Information (error)

| Field | Type | Description |
| --- | --- | --- |
| `status_code` | number |  |
| `status_error_details` | string |  |
| `status_additional_info` | string |  |
| `status_error_code` | number |  |

```json
{
  "status_code": 1,
  "status_error_details": "קישור משתמש לא נמצא",
  "status_additional_info": null,
  "status_error_code": 251
}
```