Quickstart

Figure: PHP

1 Linking SDK

1. If this has not been done previously, download, install, and set up the dependency manager Composer (https://getcomposer.org/).
2. Use the operating system command line to open the directory with the web service source code and execute the following command composer require ecommpay/paymentpage-sdk.
3. Include the script autoload.php into the web service source code.

// linking libraries
require` __DIR__.'../../vendor.autoload.php';

2 Ensuring data signing

Only then, when the values for all necessary parameters are defined, this data can be collected on the server side of the web service and the signature and the URL for opening the payment form can be generated. Here is an example of how to do this.

// Generating the signature and the link 

// creating the object of the Payment class and specifying the project and payment identifiers
$payment = new ecommpay Payment('57123', 'payment_443');

// specifying other required parameters
$payment->setPaymentAmount(1815)->setPaymentCurrency('EUR'); // payment amount and currency
$payment->setCustomerId('customer_112'); // customer identifier

// creating the object of the Gate class and specifying the secret key
$gate = new ecommpay\Gate('<secret_key>');

// generating the link for opening the payment form
$url = $gate->getPurchasePaymentPageUrl($payment);

3 Setting up the receipt of callbacks

To keep track of the payment results and other significant information, you can set up receiving and processing program callbacks sent from the payment platform. This is done in three steps:

1. Define and specify the URL for receiving callbacks by the web service within the project (at first, one URL can be specified, and then there can be several ones for various events). This can be done via Dashboard in the Projects section with the use of the Callbacks tab tools.
2. Set up the integrity validation and parsing of the callbacks, which are sent to the specified URL, with the use of the SDK.
3. Set up sending of synchronous HTTP responses with the information about the callbacks receipt: 200 OK if the signature is correct and 400 Bad Request if the signature is incorrect.

// Working with callbacks

// creating the object of the Gate class and specifying the secret key
$gate = new ecommpay\Gate('<secret_key>');

// creating the object of the Callback class and parsing the JSON string
// with the callback data ($data), with the data integrity validation
$callback = $gate->handleCallback($data);

// using methods for receiving information
Callback::getPaymentId();        // receiving the payment identifier
Callback::getPaymentStatus();    // receiving the payment status
Callback::getPayment();          // receiving all information from the callback

The payment statuses used in the payment platform are described in a separate section, and the information about callbacks and their usage is provided in a separate article. It should be noted that when a purchase is not confirmed by the customer in the payment form, it is not registered in the payment platform (thus does not have any status as well).

The information retrieved from the callbacks can be used for promptly updating the statuses of the orders in the web service, informing customers, and for other purposes—according to the web service operation model.

Figure: Python

1 Linking SDK

1. If this has not been done previously, download, install, and set up the package-management system—pip (https://pip.pypa.io/en/stable/).
2. Use the operating system command line to open the directory with the web service source code and execute the following command pip install ecommpay-sdk.
3. Include the libraries from the SDK into the web service source code.

# Linking libraries
from payment_page_sdk.gate import Gate
from payment_page_sdk.payment import Payment

2 Ensuring data signing

Only then, when the values for all necessary parameters are defined, this data can be collected on the server side of the web service and the signature and the URL for opening the payment form can be generated. Here is an example of how to do this.

# Generating the signature and the link 

# creating the object of the Payment class and specifying the project and payment identifiers
payment = Payment('57123', 'payment_443')

# specifying other required parameters
payment.payment_amount = 1815 # payment amount
payment.payment_currency = 'EUR' # payment currency
payment.customer_id = 'customer_112' # customer identifier

# creating the object of the Gate class and specifying the secret key
gate = Gate('<secret_key>')

# generating the link for opening the payment form
payment_url = gate.get_purchase_payment_page_url(payment)

3 Setting up the receipt of callbacks

To keep track of the payment results and other significant information, you can set up receiving and processing program callbacks sent from the payment platform. This is done in three steps:

1. Define and specify the URL for receiving callbacks by the web service within the project (at first, one URL can be specified, and then there can be several ones for various events). This can be done via Dashboard in the Projects section with the use of the Callbacks tab tools.
2. Set up the integrity validation and parsing of the callbacks, which are sent to the specified URL, with the use of the SDK.
3. Set up sending of synchronous HTTP responses with the information about the callbacks receipt: 200 OK if the signature is correct and 400 Bad Request if the signature is incorrect.

# Working with callbacks

# creating the object of the Gate class and specifying the secret key
gate = Gate('<secret_key>')

# creating the object of the Callback class and parsing the JSON string
# with the callback data (data), with the data integrity validation
callback = gate.handle_callback(data)

# using methods for working with callbacks
callback.get_payment_id()        # receiving the payment identifier
callback.get_payment_status()    # receiving the payment status
callback.get_payment()           # receiving all information from the callback

The payment statuses used in the payment platform are described in a separate section, and the information about callbacks and their usage is provided in a separate article. It should be noted that when a purchase is not confirmed by the customer in the payment form, it is not registered in the payment platform (thus does not have any status as well).

The information retrieved from the callbacks can be used for promptly updating the statuses of the orders in the web service, informing customers, and for other purposes—according to the web service operation model.

Figure: JavaScript

1 Linking SDK

1. If you have not yet installed a package-management system, you need to download, install and check settings. For more information, see: Yarn (https://yarnpkg.com/en/docs/getting-started) or npm (https://www.npmjs.com/package/ecommpay).
2. Navigate into the web service source code directory in command line and run one of the following commands: yarn add ecommpay or npm install ecommpay.
3. Import the modules into your web service project:

   const { Payment } = require('ecommpay');
   const { Callback } = require('ecommpay');
   

2 Ensuring data signing

Only then, when the values for all necessary parameters are defined, this data can be collected on the server side of the web service and the signature and the URL for opening the payment form can be generated. Here is an example of how to do this.

// Generating the signature and the link

// creating the object of the Payment class and specifying the project identifier and the secret key
const payment = new Payment('57123', 'payment_443');

// specifying the payment identifier
payment.paymentId = 'payment_443;

/// specifying other required parameters
payment.paymentAmount = 1815 // payment amount
payment.paymentCurrency = 'EUR' // payment currency
payment.customerId = 'customer_112' // customer identifier

// generating the link for opening the payment form
const url = payment.getUrl();

3 Setting up the receipt of callbacks

To keep track of the payment results and other significant information, you can set up receiving and processing program callbacks sent from the payment platform. This is done in three steps:

1. In the payment platform, define and specify the URL for receiving callbacks by the web service within the project (at first, one URL can be specified, and then there can be several ones for various events). This can be done via Dashboard in the Projects section with the use of the Callbacks tab tools.
2. Set up the integrity validation and parsing of the callbacks, which are sent to the specified URL, with the use of the SDK.
3. Set up sending of synchronous HTTP responses with the information about the callbacks receipt: 200 OK if the signature is correct and 400 Bad Request if the signature is incorrect.

// Working with callbacks

// creating the object of the Callback class and specifying the secret key
const callback = new Callback(<secret_key>, req.body);

// using methods for working with callbacks
app.post('/payment/callback', function(req, res) {
  const callback = new Callback(<secret_key>, req.body);
  if (callback.isPaymentSuccess()) {
    const paymentCont = callback.payment();    // receiving all information from the callback
    const paymentId = callback.getPaymentId(); // receiving the payment identifier

    // Add your code for proccessing successful payment
  }
});

The payment statuses used in the payment platform are described in a separate section, and the information about callbacks and their usage is provided in a separate article. It should be noted that when a purchase is not confirmed by the customer in the payment form, it is not registered in the payment platform (thus does not have any status as well).

The information retrieved from the callbacks can be used for promptly updating the statuses of the orders in the web service, informing customers, and for other purposes—according to the web service operation model.

Figure: PHP

1 Ensuring data singing

// Coding the algorithm
class Signer
{
    const ALGORITHM = 'sha512';
    const ITEMS_DELIMITER = ';';
 
 
    /**
     * Generate signature
     *
     * @param array $params
     * @param string $secretKey
     * @param array $ignoreParamKeys
     * @param bool $doNotHash
     *
     * @return string
     */
    public static function sign(array $params, string $secretKey, array $ignoreParamKeys = [], bool $doNotHash = false): string
    {
        $paramsPrepared = self::getParamsToSign($params, $ignoreParamKeys, 1, '');
        $stringToSign = implode(self::ITEMS_DELIMITER, $paramsPrepared);
 
        return $doNotHash
            ? $stringToSign
            : base64_encode(hash_hmac(self::ALGORITHM, $stringToSign, $secretKey, true));
    }
 
    /**
     * Get parameters to sign
     *
     * @param array $params
     * @param array $ignoreParamKeys
     * @param int $currentLevel
     * @param string $prefix
     *
     * @return array
     */
    private static function getParamsToSign(
        array  $params,
        array  $ignoreParamKeys = [],
        int    $currentLevel = 1,
        string $prefix = ''
    ): array
    {
        $paramsToSign = [];
 
        foreach ($params as $key => $value) {
            if (in_array($key, $ignoreParamKeys, true)) {
                continue;
            }
 
            $paramKey = ($prefix ? $prefix . ':' : '') . $key;
 
            if (is_object($value)) {
                $value = get_object_vars($value);
            }
 
            if (is_array($value)) {
                    $subArray = self::getParamsToSign($value, $ignoreParamKeys, $currentLevel + 1, $paramKey);
                    $paramsToSign = array_merge($paramsToSign, $subArray);               
            } else {
                if (is_bool($value)) {
                    $value = $value ? '1' : '0';
                } else {
                    $value = (string)$value;
                }
 
                $paramsToSign[$paramKey] = (string)$paramKey . ':' . $value;
            }
        }
 
        if ($currentLevel == 1) {
            ksort($paramsToSign, SORT_NATURAL);
        }
 
        return $paramsToSign;
    }


// Usage example

// specifying the secret key and the parameters for opening the payment form
$secretKey = "jwfbfjhewbrw33383kr3js9d987";
 
$params = [
    'project_id' => 57123,     
    'payment_amount' => 1815,
    'payment_currency' => 'EUR',
    'customer_id' => 'customer_112',
    'payment_id' => 'payment_443',
];
 
// generating the signature
$params['signature'] = Signer::sign($params, $secretKey);
 
// receiving the link for opening the payment form
$uriParams = http_build_query($params);
$link = implode('?', ['https://paymentpage.ecommpay.com/payment', $uriParams]);

2 Ensuring the receipt of callbacks

To keep track of the payment results and other significant information, you can set up receiving and processing program callbacks sent from the payment platform. This is done in three steps:

1. In the payment platform, define and specify the URL for receiving callbacks by the web service within the project (at first, one URL can be specified, and then there can be several ones for various events). This can be done via Dashboard in the Projects section with the use of the Callbacks tab tools.
2. Set up the integrity validation and parsing of the callbacks, which are sent to the specified URL, with the use of the SDK.
3. Set up sending of synchronous HTTP responses with the information about the callbacks receipt: 200 OK if the signature is correct and 400 Bad Request if the signature is incorrect.

// Working with callbacks. The example of comparing the received
// signature to the generated one

require_once 'Signer.php';

$secretKey = '<secret_key>';

$requestBody = '{
       "project_id": 57123,
       "payment": {
           "id": "payment_443",
           "type": "purchase",
           "status": "success",
           "date": "2022-03-03T10:50:29+0000",
           "method": "card",
           "sum": {
               "amount": 1815,
               "currency": "EUR"
           },
           "description": "Test payment"
       },
       "customer": {
           "id": "customer_112",
           "ip": "127.0.0.1",
           "phone": "+60-3-xxxx-xxxx",
           "email": "jane.doe@testmail.com"
       },
       "operation": {
           "id": 15788000002076,
           "type": "sale",
           "status": "success",
           "date": "2022-03-03T10:50:29+0000",
           "sum_initial": {
               "amount": 1815,
               "currency": "EUR"
           },
           "code": "0",
           "message": "Success"
       },
       "signature": "zwoFECy7H+WZFziw9IgR9031Uu878TuIv3dhFyHvCuvzIdRAzDQA=="
   }';

$requestBodyArray = json_decode($requestBody, true);

$actualSignature = $requestBodyArray['signature'];
unset($requestBodyArray['signature']);
$expectedSignature = Signer::sign($requestBodyArray, $secretKey);

print_r('Actual signature: ' . $actualSignature . PHP_EOL);
print_r('Expected signature: ' . $expectedSignature . PHP_EOL);

if ($expectedSignature === $actualSignature) {
    print_r('Signatures are equal');
} else {
    print_r('Signatures are not equal');
}

print_r(PHP_EOL);

The payment statuses used in the payment platform are described in a separate section, and the information about callbacks and their usage is provided in a separate article. It should be noted that when a purchase is not confirmed by the customer in the payment form, it is not registered in the payment platform (thus does not have any status as well).

The information retrieved from the callbacks can be used for promptly updating the statuses of the orders in the web service, informing customers, and for other purposes—according to the web service operation model.

Figure: Python

1 Ensuring data singing

# Coding the algorithm
import hmac
import base64
import hashlib
 
 
class Signer:
    def getSign(self, params, key):
        byteKey = key.encode()
        paramsPrepared = self.getParamsToSign(params)
        toSignString = ';'.join(paramsPrepared.values())
        hmacObj = hmac.new(byteKey, toSignString.encode(), hashlib.sha512)
 
return base64.b64encode(hmacObj.digest())

def getParamsToSign(self, params, currentLevel = 1, prefix = ''):
        paramsToSign = dict()
 
for paramKey in params.keys():
 
newParamKey = (prefix + ':' if prefix else '') + paramKey
 
if isinstance(params[paramKey], (dict)):
                subDict = self.getParamsToSign(params[paramKey], currentLevel + 1, newParamKey)
                paramsToSign.update(subDict)
else:
                if isinstance(params[paramKey], (bool)):
                    value = '1' if params[paramKey] == True else '0'
                else:
                    value = str(params[paramKey])
 
sortedParams = dict()
 
for key in sorted(paramsToSign.keys()):
            sortedParams[key] = paramsToSign[key]
 
return sortedParams


# Usage example

# specifying the secret key and the parameters for opening the payment form
import urllib.parse
import Signer
 
params = {
    'project_id': 57123, 
    'payment_amount': 1815,
    'payment_currency': 'EUR',
    'customer_id': 'customer_112',
    'payment_id': 'payment_443',
}

# Generating signature
signer = Signer.Signer()
 
params['signature'] = signer.getSign(params, '<secret_key>')
 
print(params['signature'])

# creating the signature
jointParams = urllib.parse.urlencode(params)
 
link = '?'.join(['https://paymentpage.ecommpay.com/payment', jointParams])

2 Ensuring the receipt of callbacks

To keep track of the payment results and other significant information, you can set up receiving and processing program callbacks sent from the payment platform. This is done in three steps:

1. In the payment platform, define and specify the URL for receiving callbacks by the web service within the project (at first, one URL can be specified, and then there can be several ones for various events). This can be done via Dashboard in the Projects section with the use of the Callbacks tab tools.
2. Set up the integrity validation and parsing of the callbacks, which are sent to the specified URL, with the use of the SDK.
3. Set up sending of synchronous HTTP responses with the information about the callbacks receipt: 200 OK if the signature is correct and 400 Bad Request if the signature is incorrect.

# Working with callbacks. The example of comparing the received
# signature to the generated one

from Signer import Signer
import base64

secretKey = '<secret_key>'
params = {
    "project_id": 57123,
    "payment": {
        "id": "payment_443",
        "type": "purchase",
        "status": "success",
        "date": "2022-03-03T10:50:29+0000",
        "method": "card",
        "sum": {
            "amount": 1815,
            "currency": "EUR"
        },
        "description": "Astronaut set"
    },
    "customer": {
        "id": "customer_112",
        "ip": "127.0.0.1",
        "phone": "+60-3-xxxx-xxxx",
        "email": "jane.doe@testmail.com"
    },
    "operation": {
        "id": 15788000002076,
        "type": "sale",
        "status": "success",
        "date": "2022-03-03T10:50:29+0000",
        "sum_initial": {
            "amount": 1815,
            "currency": "EUR"
        },
        "code": "0",
        "message": "Success"
    },
    "signature": "zwoFECy7H+WZFziw9IgR90SEmC+o3qXD7OIaHqgQuqcSwBC09W6yQA=="
}

signer = Signer()
actualSign = params['signature']
del params['signature']
expectedSign = signer.getSign(params, secretKey).decode()

print('Actual signature:' + actualSign)
print('Expected signature:' + expectedSign)

if (expectedSign == actualSign):
    print('Signature is correct')
else:
    print('Signature is incorrect')

The payment statuses used in the payment platform are described in a separate section, and the information about callbacks and their usage is provided in a separate article. It should be noted that when a purchase is not confirmed by the customer in the payment form, it is not registered in the payment platform (thus does not have any status as well).

The information retrieved from the callbacks can be used for promptly updating the statuses of the orders in the web service, informing customers, and for other purposes—according to the web service operation model.

Figure: JavaScript

1 Ensuring data signing

// Coding the algorithm
import hmacSHA512 from 'crypto-js/hmac-sha512';
import encBase64 from 'crypto-js/enc-base64';

export class Signer {
  getSign(params, key) {
    const paramsPrepared = this.getParamsToSign(params, 1);

    const joinedString = Object.values(paramsPrepared).join(';');

    const hash = hmacSHA512(joinedString, key);

    return hash.toString(encBase64);
  }

  getParamsToSign(
    params,
    prefix = '',
  ) {
    let paramsToSign = {};
    let value = '';

    let keys = Object.keys(params);
    let key = '';
    for (let i = 0; i < keys.length; i++) {
      key = keys[i];

      let paramKey = (prefix ? prefix + ':' : '') + key;

      if (typeof params[key] === 'object') {
        let subParams = this.getParamsToSign(
            params[key],
            paramKey,
          );

          Object.assign(paramsToSign, subParams);
      } else {
        if (typeof params[key] === 'boolean') {
          value = params[key] === true ? '1' : '0';
        } else {
          value = params[key].toString();
        }

        paramsToSign[paramKey] = paramKey + ':' + value;
      }
    }

    let orderedKeys = Object.keys(paramsToSign).sort();

    let ordered = {};

    for (let k = 0; k < orderedKeys.length; k++) {
      ordered[orderedKeys[k]] = paramsToSign[orderedKeys[k]];
    }

    return ordered;
  }
}

// Usage example

import { Signer } from './signer.js';

// specifying the secret key and the parameters for opening the payment form
let params = {
  project_id: 57123,
  payment_amount: 1815,
  payment_currency: 'EUR',
  customer_id: 'customer_112',
  payment_id: 'payment_443',
};

// generating signature
params['signature'] = new signer().getSign(params, '<secret_key>');

// receiving the link for opening the payment form
const uriParams = Object.keys(params)
  .sort()
  .reduce((paramsArray, key) => {
    paramsArray.push(key + '=' + encodeURIComponent(params[key]));
    return paramsArray;
  }, []);
const link = [
'https://paymentpage.ecommpay.com/payment',
  uriParams.join('&'),
].join('?');

2 Ensuring the receipt of callbacks

To keep track of the payment results and other significant information, you can set up receiving and processing program callbacks sent from the payment platform. This is done in three steps:

1. In the payment platform, define and specify the URL for receiving callbacks by the web service within the project (at first, one URL can be specified, and then there can be several ones for various events). This can be done via Dashboard in the Projects section with the use of the Callbacks tab tools.
2. Set up the integrity validation and parsing of the callbacks, which are sent to the specified URL, with the use of the SDK.
3. Set up sending of synchronous HTTP responses with the information about the callbacks receipt: 200 OK if the signature is correct and 400 Bad Request if the signature is incorrect.

// Working with callbacks. The example of comparing the received
// signature to the generated one

import { Signer } from './Signer';

const secretKey = '<secret_key>';

const params = {
    "project_id": 57123,
    "payment": {
        "id": "payment_443",
        "type": "purchase",
        "status": "success",
        "date": "2022-03-03T10:50:29+0000",
        "method": "card",
        "sum": {
            "amount": 1815,
            "currency": "EUR"
        },
        "description": "Astronaut set"
    },
    "customer": {
        "id": "customer_112",
        "ip": "127.0.0.1",
        "phone": "+60-3-xxxx-xxxx",
        "email": "jane.doe@testmail.com"
    },
    "operation": {
        "id": 15788000002076,
        "type": "sale",
        "status": "success",
        "date": "2022-03-03T10:50:29+0000",
        "sum_initial": {
            "amount": 1815,
            "currency": "EUR"
        },
        "code": "0",
        "message": "Success"
    },
    "signature": "zwoFECy7H+WZFziw9IgR90SHvCuvqXD7OIaHqgQuqcSwBC09W6yQA=="
};

const actualSignature = params['signature'];
delete params.signature;
const expectedSignature = (new signer()).getSign(params, secretKey);

console.log('Actual: ' + actualSignature);
console.log('Expected: '+expectedSignature);

if (actualSignature == expectedSignature) {
    console.log('Signatures is correct');
} else {
    console.log('Signature is incorrect');
}

The payment statuses used in the payment platform are described in a separate section, and the information about callbacks and their usage is provided in a separate article. It should be noted that when a purchase is not confirmed by the customer in the payment form, it is not registered in the payment platform (thus does not have any status as well).

The information retrieved from the callbacks can be used for promptly updating the statuses of the orders in the web service, informing customers, and for other purposes—according to the web service operation model.

Figure: Opening in a separate browser tab

To open the payment form as a separate HTML page, you should use the link obtained during signature generation. The link has the format of https://paymentpage.ecommpay.com/payment?<parameters> where <parameters> is a data string containing the names and values of the parameters.

In this case, the HTTP request with the use of the GET method can look as follows:

GET
/payment?payment_currency=EUR&project_id=42&payment_amount=1000&
customer_id=123&payment_id=4438&signature=AE5hmtzdP0Dt7qGTg... HTTP/1.1

Host: https://paymentpage.ecommpay.com

Figure: Linking libraries

<head>
...
// linking the CSS library
<link rel="stylesheet" href="https://paymentpage.ecommpay.com/shared/merchant.css" /> 

// linking the JavaScript library
<script type="text/javascript" src="https://paymentpage.ecommpay.com/shared/merchant.js">
</script>
...
</head>

Figure: Opening in a modal window

For Payment Page to open in a modal window with a button click on the web service page, the bind method of the JavaScript EPayWidget object can be used. When accessing this object, you should specify the button identifier (pay_button_id), the object with the parameters for opening Payment Page (configObj), and the HTTP method for sending requests (method):

EPayWidget.bind('pay_button_id',            // button identifier
                { payment_id: 'payment_443',         // payment identifier
                  payment_amount: 1815,              // payment amount
                  payment_currency: 'EUR',           // payment currency code
                  project_id: 57123,                 // project identifier
                  customer_id: 'customer_112',       // customer identifier
                  signature: 'YWb6Z20ByxpQ30hfTI' }, // signature
                 'post') // HTTP method

Figure: Opening directly on the page, in the iframe element

For Payment Page to open in the iframe element with a button click on the web service page, as with the modal window, the bind method of the JavaScript EPayWidget object can be used. When accessing this object, you should specify the button identifier (pay_button_id), the object with the parameters for opening Payment Page (configObj) which also contains the identifier of the element in which the payment form should be displayed (target_element), and the HTTP method for sending requests (method):

EPayWidget.bind('pay_button_id',             // button identifier
                { payment_id: 'payment_443',          // payment identifier
                  payment_amount: 1815,               // payment amount
                  payment_currency: 'EUR',            // payment currency code
                  project_id: 57123,                  // project identifier
                  customer_id: 'customer_112',        // customer identifier
                  signature: 'YWb6Z20ByxpQ30hfTI' },  // signature
                  target_element: 'widget-container', // element identifer
                 'post') // HTTP-method