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

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

Платёжная платформа 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 отображается страница ожидания. При необходимости проведения 3‑D Secure проверки происходит перенаправление пользователя. Также при необходимости поддерживаются каскадное проведение платежа, сбор данных о пользователе и дополнение информации о платеже.

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

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