SDK for JavaScript

SDK for JavaScript is a software development kit for development of web services which are capable of integrating with the ecommpay payment solutions to perform purchases by using Payment Page. This section describes how to use SDK for JavaScript to build purchase experience from inside of your web service.

SDK for JavaScript is compatible with the Node.js 4.x runtime environment for executing JavaScript code. You can download SDK for JavaScript from GitHub: https://github.com/ITECOMMPAY/paymentpage-sdk-js.

What can I do with SDK for JavaScript?

SDK for JavaScript allows you to do the following:

Calculate signature and generate request for opening the Payment Page payment form
Check callback signature and extract payment details from callbacks

What's inside?

SDK for JavaScript contains the following:

src—a library for development
_tests_—a library for automatic testing

Using SDK for JavaScript

To start using SDK for JavaScript you need to complete the following tasks:

Make sure you have you have ready your merchant ID and secret key obtained from ecommpay.
1. If your company has never obtained any ID or secret key from ecommpay, you need to submit an application for connecting to the ecommpay payment platform at https://ecommpay.com/apply-now/.
2. If your company already has an ID and a secret key to sign messages obtained from ecommpay, you need to notify the ecommpay technical support specialists that you want to use SDK for JavaScript and consult the customer support on how to arrange a test run.
Integrate the ecommpay payment solution in your web service:
1. Install the SDK for JavaScript libraries into a directory inside your web service project.
2. Import the libraries you need into your web service application.
Test and put your web service in production mode.
- Use test merchant ID and test values for payment parameters from the _tests_ library.
- Once testing is complete, request your production merchant ID from ecommpay and put your web service in production mode.

With any questions regarding the use of SDK for JavaScript contact the ecommpay technical support specialists at support@ecommpay.com.

Installing and importing libraries

You can install the SDK for JavaScript libraries manually or automatically with Yarn or npm, package-management systems used to install and manage software packages written in JavaScript.

The following steps describe how to install the SDK for JavaScript libraries by using Yarn or npm:

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
- npm: https://docs.npmjs.com/
Navigate into the web service source code directory in command line and run one of the following commands:
```
npm install ecommpay // for npm
yarn add ecommpay    // for Yarn
```
A package-management system automatically downloads the SDK for JavaScript libraries in the source code directory to enable you to use all the modules provided by the libraries.

Import the modules into your web service project:

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

Opening payment form

Payment form invocation request consists of a set of parameters, which are signed to secure the data transmitted to the ecommpay payment platform. SDK for JavaScript allows you to seamlessly sign parameters and generate requests. To open the Payment Page payment form by using SDK for JavaScript do the following:

Create an instance of the Payment class and specify payment details and the secret key you obtained from the ecommpay technical support specialists. The secret key is required to sign invocation requests.
```
const e = new Payment('186', '<secret_key>');
        // Project ID and Secret key
e.paymentId = 'TEST_1555943554067';
        // Payment ID must be unique within your project scope
e.paymentAmount = 1000;
        // Amount in minor currency units
e.paymentCurrency = 'EUR';
        // Currency in ISO-4217 alpha-3 format
e.paymentDescription = 'Payment description';
       // Payment description (optional)
```
All parameters in this example with the exception of the payment description are required to perform a payment. You can also use any optional parameters available for Payment Page. For more information about the Payment Page invocation parameters, see Parameters for opening payment form.

Generate payment form invocation request:

const url = e.getUrl();

Correct payment form invocation request contains payment parameters and signature (abbreviated):

https://paymentpage.ecommpay.com/payment?signature=OEKRlLXQsa2..
               ..gWg%3D%3D&payment_id=pid_1555943554067...

Use the generated request to open the payment form, for example:

<link rel="stylesheet" href="https://paymentpage.ecommpay.com/shared/merchant.css" />
<script type="text/javascript" src="https://paymentpage.ecommpay.com/shared/merchant.js"></script>
<script type="text/javascript">
    EPayWidget.run({ baseUrl: '<the URL generated in the previous step>'}, 'get');
</script>

Other ways to open the payment form are described in the following article.

Here is an example of generating a URL for opening a payment form in English. The payment method selection page includes detailed payment information including amount, currency, and short payment description.

Figure: Example of generating Payment Page invocation request

const e = new Payment('186', '<secret_key>');
        // Project ID and Secret key
e.paymentId = 'TEST_1555943554067';
        // Payment ID must be unique within your project scope
e.paymentAmount = 1000;
        // Amount in minor currency units
e.paymentCurrency = 'EUR';
        // Currency in ISO-4217 alpha-3 format
e.paymentDescription = 'Payment description';
       // Payment description (optional)
e.anguage_code: 'EN';
       // Language code to use in payment form
const url = e.getUrl();
       // Complete request with signature

Using the test mode

When working with the SDK for JavaScript, you can use the test mode. It allows you to get information about errors if there were any when payment parameters were specified. If there were none, it lets you open the payment form in the Test mode (the top of the form will be indicated as such) and use random data.

Before using the test mode, make sure that the server of the web service can send the HTTP requests to sdk.ecommpay.com. This allows you to specify various parameters to open the payment form as part of the testing activities (you will be able to use both test and production parameters) and to analyse error information. Use the following code:

const payment = new Payment(<project_id>, '<secret_key>');
payment.paymentId = "<payment_id_in_your_service>";
payment.paymentAmount = 1001;
payment.paymentCurrency = 'EUR';
payment.paymentDescription = 'Test payment';
payment.testMode = true; // Turning the test mode on
 
try:

Information about the errors that occurred in testing is provided in error messages as follows:

One or more parameters is not valid:
 
Customer_id:
    Must be not null // The id of the customer, required for this request, was not specified
Account_token:
    Invalid account token  // Incorrect token value was specified

Processing callbacks

The ecommpay payment platform sends payment results to the callback URL you specified when connecting to ecommpay. Callback is an HTTP POST request that contains response data in JSON format in the req.body object. To extract payment information from JSON string, do the following:

Create an instance of Callback by using the secret key and the JSON string from the callback obtained from the ecommpay payment platform:
```
const callback = new Callback(<secret_key>, req.body);
```

The following example contains the methods for extracting callback information in the source code that uses the Express framework:

app.post('/payment/callback', function(req, res) {
  const callback = new Callback(<secret_key>, req.body);
  if (callback.isPaymentSuccess()) {
    const paymentCont = callback.payment(); // Getting information about the payment
    const paymentId = callback.getPaymentId(); // Getting payment ID

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

By using SDK for JavaScript, you can automatically check validity of callback signature. Below, you will find an example of callback that includes signature and payment results.

Figure: Sample payment callback

{
             "project_id": 186,       // Project ID
             "payment": {             // Payment details
             "id": "pid_1555943554067",       // Payment ID
             "type": "purchase",  // Payment type
             "status": "success", // Payment status
             "date": "2021-08-28T09:11:28+0000",  // Payment date and time
             "method": "card",  // Payment method
             "sum": {           // Payment amount and currency
             "amount": 1000,
             "currency": "EUR"
             },
             "description": "Test payment"  // Payment description
             },
             "account": {           // Payment instrument details
             "number": "431422******0056 ",
             "token": "9cb38282187b7a5b5b91b5814c6b814162741b29c0c486fbbc500cd451abb8b2",
             "type": "visa",
             "card_holder": "ADA LOVELACE",
             "id": 778804,
             "expiry_month": "11",
             "expiry_year": "2024"
             },
             "operation": {     // The last operation within payment
             "id": 17839000001150,  // Operation ID
             "type": "sale",        // Operation type
             "status": "success",   // Operation status
             "date": "2021-08-28T09:11:28+0000", // Operation date and time
             "created_date": "2021-08-28T09:10:50+0000",
             "request_id": "2c8af331519833f2c96c4a1aaf60edfcffb...", // Request ID
             "sum_initial": {    // Initial payment amount and currency 
             "amount": 1000,
             "currency": "EUR"
             },
             "sum_converted": {
             // Payment amount and currency as per applicable project conversion rules
             "amount": 1000,
             "currency": "EUR"
             },
             "provider": {     // Payment details in payment system
             "id": 6,
             "payment_id": "15354474886323",
             "date": "2021-02-07T08:34:24+0000",
             "auth_code": "563253",
             "endpoint_id": 6
             },
             "code": "0",          // Unified response code
             "message": "Success", // User-readable response code
             "eci": "05"           // ECI code, result of 3-D Secure check
              },
              "signature": "22YlUIIgoppli/JX8w5F5+c2h12RXi81WLmgDx..."  // Signature
              }