Create a sale with 3D Secure

• 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): 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.
• Request body field payme_client_key (optional): 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.

Overview

Creates a sale on the hosted payment page with 3D Secure. The call is an ordinary generate-sale that returns sale_url; 3D Secure runs inside PayMe's payment page.

POST https://sandbox.payme.io/api/generate-sale (production: https://live.payme.io/api/generate-sale), with a JSON body (Content-Type: application/json).

Credentials

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

When 3D Secure runs

3D Secure must be enabled on the account by PayMe. PayMe's system rules then apply it to card payments that match any of them: a card issued in a country other than the seller's registered country, 3 or more installments, or an amount of at least the account's 3D Secure threshold. The amount rule compares sale_price in minor units with the threshold, without converting currencies. To add rules of your own, ask your onboarding manager before you go live.

Force it on or off for one sale

Send services with the 3DSecure service. This needs the 3D Secure service on the account.

{
  "services": [{"name": "3DSecure", "settings": {"active": true}}]
}

• "active": true forces 3D Secure on this sale.
• "active": false turns off your account's own 3D Secure rules for this sale. PayMe's system rules (foreign card, 3 or more installments, the amount threshold) still apply; only PayMe can switch those off for the account.
• A setting for a service the account doesn't have is ignored, without an error. Each entry needs settings: an entry without it returns error 1 after the sale has already been created.

When authentication fails

When the buyer fails the 3D Secure challenge, the sale becomes failed and PayMe sends the buyer to the first of these that is set: your sale_return_url (with payme_status=error), then cancel_url, then PayMe's payment page to try another card.

Check the result

Query the sale with get-transactions or get-sales and read sale_is_3ds. The sale callback carries sale_3ds (1 when 3D Secure was used). Sandbox test cards for the challenge are on Test Cards and Payment Methods.

Rules for every request

• Amounts are in minor units (1000 = 10.00).
• Never put card numbers in any field. A value (other than transaction_id and order_number) that contains a 14–19-digit number passing the card checksum is refused with error 20 (HTTP 400), "<field> contains invalid data".
• Don't send the legacy price field: it is in major units and, when numeric, overrides sale_price.
• PayMe doesn't de-duplicate transaction_id: every call creates a new sale. See Idempotency and Retries.
• Errors return status_code: 1 with status_error_code, most with HTTP 500. See Errors.

Callbacks

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

Parameters

This endpoint takes no path, query or header parameters.

Request body

Content type: application/json

Request example

{
  "seller_payme_id": "MPLDEMO-MPLDEMO-MPLDEMO-1234567",
  "sale_price": 60000,
  "currency": "ILS",
  "product_name": "Laptop",
  "transaction_id": "order-1002",
  "installments": "1",
  "sale_callback_url": "https://your-server.example.com/payme/callback",
  "sale_return_url": "https://your-site.example.com/payment/success",
  "cancel_url": "https://your-site.example.com/checkout",
  "language": "en",
  "services": [
    {
      "name": "3DSecure",
      "settings": {
        "active": true
      }
    }
  ]
}

Code samples

curl

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": 60000,
  "currency": "ILS",
  "product_name": "Laptop",
  "transaction_id": "order-1002",
  "installments": "1",
  "sale_callback_url": "https://your-server.example.com/payme/callback",
  "sale_return_url": "https://your-site.example.com/payment/success",
  "cancel_url": "https://your-site.example.com/checkout",
  "language": "en",
  "services": [
    {
      "name": "3DSecure",
      "settings": {
        "active": true
      }
    }
  ]
}'

Node.js

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": 60000,
    "currency": "ILS",
    "product_name": "Laptop",
    "transaction_id": "order-1002",
    "installments": "1",
    "sale_callback_url": "https://your-server.example.com/payme/callback",
    "sale_return_url": "https://your-site.example.com/payment/success",
    "cancel_url": "https://your-site.example.com/checkout",
    "language": "en",
    "services": [
      {
        "name": "3DSecure",
        "settings": {
          "active": true
        }
      }
    ]
  }),
});

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

Python

import requests

response = requests.post(
    "https://sandbox.payme.io/api/generate-sale",
    json={
        "seller_payme_id": "MPLDEMO-MPLDEMO-MPLDEMO-1234567",
        "sale_price": 60000,
        "currency": "ILS",
        "product_name": "Laptop",
        "transaction_id": "order-1002",
        "installments": "1",
        "sale_callback_url": "https://your-server.example.com/payme/callback",
        "sale_return_url": "https://your-site.example.com/payment/success",
        "cancel_url": "https://your-site.example.com/checkout",
        "language": "en",
        "services": [
            {
                "name": "3DSecure",
                "settings": {
                    "active": True,
                },
            },
        ],
    },
)

print(response.text)

PHP

<?php

$body = <<<'BODY'
{
  "seller_payme_id": "MPLDEMO-MPLDEMO-MPLDEMO-1234567",
  "sale_price": 60000,
  "currency": "ILS",
  "product_name": "Laptop",
  "transaction_id": "order-1002",
  "installments": "1",
  "sale_callback_url": "https://your-server.example.com/payme/callback",
  "sale_return_url": "https://your-site.example.com/payment/success",
  "cancel_url": "https://your-site.example.com/checkout",
  "language": "en",
  "services": [
    {
      "name": "3DSecure",
      "settings": {
        "active": true
      }
    }
  ]
}
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 (success)

{
  "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": 60000,
  "transaction_id": "order-1002",
  "currency": "ILS",
  "sale_payment_method": "credit-card"
}

500 — Request refused. Most request errors return HTTP 500 with status_code: 1; some return 400, 403, 422 or 429. See Errors. (error)

{
  "status_code": 1,
  "status_error_details": "Seller was not found",
  "status_additional_info": "seller_payme_id",
  "status_error_code": 251,
  "session": "AtsJ0as5"
}