Card data encryption script

General information

The ecommpay payment platform allows you to perform card payments and card verification using the payment form of your web service. This method helps you avoid additional customer redirections and configure payment routing yourself. To configure the functionality, you need to install an encryption script in the source code of the payment page of your web service, which collects the necessary parameters, encrypts the card data and creates a token for this card.

You also need to have a ready copy of your PCI DSS compliance certificate or, if your company is not PCI DSS-compliant, complete Self-Assessment Questionnaire. Refer to your key account manager in ecommpay to enable the functionality or if you need any assistance in completing Self-Assessment Questionnaire.

The functionality is available in the following Payment Page modes: Purchase and Card Verify. To perform a payment or a card verification by using such a token you need to display the payment form with required fields to a customer, get the response from the payment platform with the card token generated by the script, send a request for payment or verification using the token in a payment platform and receive a callback with the payment result. The full sequence of payment processing is provided below.

Data encryption and payments performing

To perform a payment by using encrypted card data, a merchant should do the following:

Receive API key—a unique key for the project used to identify the merchant, as well as the public key of the encryption certificate used to encrypt and decrypt the transmitted request data and issued for each project. This data is provided when integrating with the ecommpay payment platform, or it must be requested from the technical support at support@ecommpay.com. The API key is valid for an indefinite period, and the certificate is valid for 1 year.

Include the data encryption script in the web service project code, taking into account the following:

the web service project code or the script must contain the values of the API key, public key, project and customer IDs
request the customer card details on the payment form:
- pan—card number
- year—card expiry year in the YYYY format
- month—card expiry month in the MM format
- card_holder— cardholder name
- cvv—card verification code

Figure: Example of an embedded encryption script

<script type="text/javascript" src="https://paymentpage.ecommpay.com/shared/tokenize-request.js"></script>
<script>
    $(function () {
        var customerId = '<CUSTOMER ID (STRING)>';
        var projectId = <PROJECT ID (INTEGER)>;        
        var apiKey = '<API KEY (STRING)>';
        var publicKey = '<PUBLIC KEY (STRING)>';
        
        var successCallback = function (response) {
          // {
          //     "token": "11d2d39f571fe471cb8baff2801faf4ca09f24b3750eae17f870b813185a3123",
          //     "card_info": {
          //         "country": "US",
          //         "product_name": "Visa classic",
          //         "issuer_name": "BOKF, National Association"
          //     },
          //     "request_id": "212cd70fa48600664d2bf81c7f7-00000001",
          //     "status": "success"
          // }
        }
        
        var errorCallback = function (errors) {
          // [
          //     {
          //         "code": 2003,
          //         "message": "The property api_key is required"
          //     }
          // ]
        }

        $('form').submit(function (event) {
            var form = $(this);
            var data = {
                'pan': form.find('[name="pan"]').val(),
                'month': parseInt(form.find('[name="month"]').val()),
                'year': parseInt(form.find('[name="year"]').val()),
                'card_holder': form.find('[name="card_holder"]').val(),
                'cvv': form.find('[name="cvv"]').val(),
                'customer_id': customerId,
                'api_key': apiKey,
            };

            var tokenizeRequest = new TokenizeRequest(
                publicKey,
                projectId 
            );

            tokenizeRequest
            .create(data)
            // 200 (status: "success")
            .then(successCallback)
            // 400, 500 (status: "error")
            .catch(errorCallback);

            event.preventDefault();
        });
    });
</script>

After entering the data, when the customer clicks Pay, the script encrypts all the data received and sends a request to the payment platform for the card token generation. The following parameters are passed in the request:

project_id—the project identifier in which the payment is made, to verify the key encryption certificate,
crypto_message—a string containing all parameters passed by the merchant in encrypted form, including the customer ID, API key, and card data.

Figure: Request example

{
  "project_id": 1,
  "crypto_message": "XWbyj+wF8Zw0fDalBnivSl9BHqevrDH2OTCtaYN642xIneHp4ElpOu2VZ27DJf5rWVd+UvIrPPcdMjh8O/V1bOqlyaLjJHVPvcZAjtOKZWi493WxmzM7kBL0uUehyu+uOWcqqNjniM8XFtXRDs2Zonddvv0SdHpEgVjSDKDIxr5oHVoyEBMK/vyvDA/lPJB/DI3P6lo6SwQigTBQRpzWn0T//8/VX24ULxzXVrF9uT+I/Bs8szGeZa7w/IDnbDETdx6d2jZdi+LK/tDRw19KUZ0up/c/Ydlqm+y51BtIQSmXn0flkIyc4tZS6Qz62mDDgHXIyxrcImY8r5EOjQQweA=="
}

The payment platform sends a synchronous response to the request with the generated token and card data.

Figure: Example of a response with a generated token

{
  "status": "success",
  "token": "42ab631449a78914502803aed8a0e5a728d558035d29a56f4dcc136c6bfc3021",
  "card_info": {
    "country": "CZ",
    "product_name": "Standard MasterCard Card",
    "issuer_name": ""
  },
  "request_id": "4936329e7c57e1112c8dac2e2c705b6bf8f549be-..."
}

If errors occur during request processing, they are passed in the response in the errors array. The code and description are specified for each error. Before resending the request for token generation, you must correct all errors found.

Figure: Example of a response with errors

{
  "status":"error",
  "errors":[
        {"code":2003,"message":"The property api_key is required","field":"api_key","constraint":"required"},
        {"code":2003,"message":"The property cvv is required","field":"cvv","constraint":"required"}
    ]
}

Send the request for Payment Page opening including the card token in the account_token parameter and the checkout_script parameter, that determines the possibility to make a payment or to verify card by the card token generated by the encryption script. The using of Payment Page allows you to avoid additional processing of responses and callbacks from the payment platform during payment processing.
Figure: Example of Payment Page opening request to perform a purchase
```
EPayWidget.run(
    { payment_id: 'payment_token_1', 
      payment_amount: 10000, 
      payment_currency: 'EUR', 
      project_id: 102, 
      customer_id: '6789',    
      checkout_script: 1,
      account_token: '42ab631449a78914502803aed8a0e5a728d558035d29a56f4dcc136c6bfc3021',
      signature: 'kUi2x9dKHAVNU0FYldJrxh4yo+52Kt8...=='
    }
)
```
Figure: Example of a Payment Page opening request to perform a card verification
```
EPayWidget.run(
    { mode: 'card_verify',
      payment_id: 'payment_token_1', 
      payment_amount: 0, 
      payment_currency: 'EUR', 
      project_id: 102, 
      customer_id: '6789',    
      checkout_script: 1,
      account_token: '42ab631449a78914502803aed8a0e5a728d558035d29a56f4dcc136c6bfc3021',
      signature: 'kUi2x9dKHAVNU0FYldJrxh4yo+52Kt8...=='
    }
)
```
For the full list of Payment Page supported parameters, see Parameters for opening payment form.

The preloader page is displayed to the customer on Payment Page. If it is required to perform the 3‑D Secure check, the redirection of a customer to ACS URL occurs. Also if required cascade payment processing, collecting customer data, and submission of additional payment information are supported.
Receive a callback with the payment result when the payment processing is completed, . For more information, see Callbacks.
When the payment processing is completed, the customer is redirected to one of the return URLs specified in the request or the page with the result is displayed on Payment Page. For more information, see Options for redirecting customers to the web service.