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

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

Платёжная платформа 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. Подробную информацию см. в разделе Способы возврата пользователя в проект после оплаты.