Скрипт шифрования карточных данных

Общая информация

Платёжная платформа ECommPay позволяет проводить оплаты по картам и проверки действительности карты с использованием платёжной формы вашего веб-сервиса. Такой способ помогает избежать дополнительных перенаправлений пользователей и самостоятельно настраивать маршрутизацию платежей. Для настройки функциональности необходимо установить скрипт шифрования в исходный код платёжной страницы вашего веб-сервиса, который собирает необходимые параметры, шифрует данные карты и создаёт токен для этой карты.

Для проведения платежей с использованием платёжных карт необходимо предоставить курирующему менеджеру ECommPay документ о соответствии требованиям PCI DSS. Это может быть копия сертификата соответствия (при его наличии) или лист самооценки. С вопросами о подключении функциональности и заполнении листа самооценки можно обращаться к курирующему менеджеру ECommPay.

Функциональность доступна в режимах работы Payment Page: Purchase и Card Verify. Для проведения оплаты или проверки действительности карты с помощью такого токена необходимо отобразить пользователю платёжную форму с обязательными для заполнения полями, затем получить ответ от платёжной платформы со сгенерированным токеном карты с помощью скрипта, отправить запрос на проведение оплаты или проверки с помощью токена в платёжную платформу и получить оповещение о результате оплаты. Полный сценарий проведения оплаты представлен далее.

Настройка шифрования данных и проведение оплаты

Для проведения оплаты с использованием зашифрованных данных со стороны мерчанта потребуется:
  1. Получить API key — уникальный ключ для проекта, используемый для идентификации мерчанта, а также публичный ключ сертификата шифрования, используемого для шифрования и дешифрования переданных в запросе данных и выдаваемого для каждого отдельного проекта. Эти данные предоставляются при интеграции с платёжной платформой ECommPay, или их необходимо запросить у сотрудников технической поддержки по адресу support@ecommpay.com. API key действует бессрочно, сертификат действителен в течение 1 года.
  2. Установить скрипт шифрования данных в исходный код платёжной страницы веб-сервиса, учитывая следующее:
    • в исходном коде страницы или в скрипте должны быть указаны значения API key, публичного ключа, идентификаторы проекта и пользователя,
    • на платёжной форме необходимо запросить данные карты пользователя:
      • pan — номер карты,
      • year — год истечения срока действия карты в формате ГГГГ,
      • month — месяц истечения срока действия карты в формате ММ,
      • card_holder — имя держателя карты,
      • cvv — код проверки подлинности карты.

    Рис.: Пример встраиваемого скрипта шифрования

    <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>
    После ввода данных, когда пользователь нажимает Оплатить, скрипт шифрует все полученные данные и отправляет запрос в платёжную платформу на генерацию токена карты. В запросе передаются следующие параметры:
    • project_id — идентификатор проекта, в рамках которого осуществляется платёж, указывается для проверки ключа сертификата шифрования,
    • crypto_message — строка, содержащая в зашифрованном виде все параметры, переданные мерчантом, обязательными среди которых являются идентификатор пользователя, API key и данные карты.

    Рис.: Пример запроса

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

    Платёжная платформа отправляет синхронный ответ на запрос со сгенерированным токеном и данными карты.

    Рис.: Пример ответа со сгенерированным токеном

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

    В случае если во время обработки запроса возникли ошибки, они передаются в ответе в массиве 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"}
        ]
    }
  3. Отправить запрос на открытие платежной формы Payment Page с указанием токена в параметре account_token и с параметром checkout_script, который определяет возможность проведения оплаты или проверки действительности карты с помощью токена, сгенерированного скриптом шифрования. Вызов Payment Page позволяет избежать дополнительных обработок ответов и оповещений со стороны платёжной платформы во время обработки платежа.

    Рис.: Пример запроса на открытие Payment Page для проведения оплаты

    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...=='
        }
    )

    Рис.: Пример запроса на открытие Payment Page для проверки карты

    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...=='
        }
    )

    Полный список параметров, поддерживаемых Payment Page, приведен в разделе Параметры открытия платежной формы Payment Page.

    В процессе обработки платежа на Payment Page пользователю отображается страница ожидания, а также в случае необходимости проведения 3-D Secure проверки, происходит перенаправление пользователя.

  4. Получить оповещение о результате оплаты после завершения обработки платежа Подробнее см. в разделе Оповещения.

    После обработки платежа пользователь перенаправляется на один из указанных в запросе URL для возврата или отображается страница с результатом на Payment Page. Подробную информацию см. в разделе Способы возврата пользователя в проект после оплаты.