Generate Sale with 3D Secure

This is a variant of POST /generate-sale — Generate Payment; the request and responses below are the ones documented for Generate a Sale with 3D Secure.

Credentials

Overview

In order to process sales with the 3D secure activated, please follow the next steps:

  1. Make sure the service is enabeled for your partner account on PayMe's system.
  2. Use generate-sale to send the request.
  3. If you want to set specific rules for 3D secure initiation process, make sure you reach out to your onboarding manager and have them in place before inititating the transaction.

Create a sale with Dynamic 3DS

This option requires signup in advanced to the 3DS service. As part of generate-sale command, you can add the following object to the request:

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

Redirecting When the Authentication Failed

If the user has failed on the authentication step (When a challenge is presented - 6 digit OTP that is sent to the card holder), a redirect will be initiated sending the user to PayMe's Hosted Payment Page for an additional try to input another credit card.

If you would like to avoid such cases and redirect the card-holder back to your own payment page, please include an additional parameter in your sale generating request (generate-sale) which is cancel_url.

Parameter Name Type Example
cancel_url URL https://payme.io

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 Our unique seller ID
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.
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 yes Amount of installments for the sale. For additional information see Note 1 below
market_fee number no 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
sale_send_notifcation 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_key string no 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
buyer_perform_validation boolean no Flag for performing an online validation of the card with the Issuer. Default value is true
sale_payment_method string no Flag for performing an online validation of the card with the Issuer. Default value is true
layout string no 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
language string no Changes the language of the payment IFRAME to English, as well as the error messages. Default value is Hebrew (he)
services object no

Request example

No example is documented; this template is generated from the fields — replace the placeholder values.

{
  "seller_payme_id": "<seller_payme_id>",
  "sale_price": 0,
  "currency": "<currency>",
  "product_name": "<product_name>",
  "transaction_id": "<transaction_id>",
  "installments": "<installments>",
  "market_fee": 0,
  "sale_send_notifcation": false,
  "sale_callback_url": "<sale_callback_url>",
  "sale_email": "<sale_email>",
  "sale_return_url": "<sale_return_url>",
  "sale_mobile": "<sale_mobile>",
  "sale_name": "<sale_name>",
  "capture_buyer": "<capture_buyer>",
  "buyer_key": "<buyer_key>",
  "buyer_perform_validation": false,
  "sale_payment_method": "<sale_payment_method>",
  "layout": "<layout>",
  "language": "<language>",
  "services": {}
}

Code samples

curl

curl -X POST 'https://sandbox.payme.io/api/generate-sale' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "seller_payme_id": "<seller_payme_id>",
  "sale_price": 0,
  "currency": "<currency>",
  "product_name": "<product_name>",
  "installments": "<installments>"
}'

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": "<seller_payme_id>",
    "sale_price": 0,
    "currency": "<currency>",
    "product_name": "<product_name>",
    "installments": "<installments>"
  }),
});

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

Python

import requests

response = requests.post(
    "https://sandbox.payme.io/api/generate-sale",
    json={
        "seller_payme_id": "<seller_payme_id>",
        "sale_price": 0,
        "currency": "<currency>",
        "product_name": "<product_name>",
        "installments": "<installments>",
    },
)

print(response.text)

PHP

<?php

$body = <<<'BODY'
{
  "seller_payme_id": "<seller_payme_id>",
  "sale_price": 0,
  "currency": "<currency>",
  "product_name": "<product_name>",
  "installments": "<installments>"
}
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. 
{
  "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 
{
  "status_code": 1,
  "status_error_details": "קישור משתמש לא נמצא",
  "status_additional_info": null,
  "status_error_code": 251
}