Встраивание облегчённой редакции Payment Page для карточных платежей

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

В некоторых случаях может быть актуальным встраивать в пользовательский интерфейс веб-сервиса максимально лаконичную платёжную форму и обеспечивать своим пользователям более быстрый и „бесшовный“ сервис по сравнению с типовыми решениями, по крайней мере для наиболее востребованных вариантов платежей. В платёжной платформе ecommpay для таких ситуаций предусмотрена облегчённая редакция платёжной формы Payment Page — с минимальным количеством полей ввода и без кнопки подтверждения (чтобы оставлять реализацию такой кнопки или иного элемента управления на стороне веб-сервиса).

Облегчённая редакция сконфигурирована для проведения классических карточных платежей с поддержкой наиболее актуальных при этом процедур и возможностей. Для поддержки расширенных сценариев работы, как и для использования альтернативных платёжных методов, предусмотрены другие редакции Payment Page. При этом можно комбинировать применение различных редакций и подстраивать их оформление и возможности под специфику веб-сервиса. Так, для платежей с прямым использованием карт можно использовать облегчённую редакцию, для оплат с глубокой интеграцией сервисов Apple Pay и Google Pay — специализированную редакцию для этих сервисов (подробнее), а для работы с другими методами — основную редакцию Payment Page.

Возможности

При работе с облегчённой редакцией Payment Page можно:

• Настраивать вид формы с помощью конструктора оформления, встроенного в интерфейс Dashboard (подробнее).
• Настраивать состав отображаемых полей, с возможностями. В рамках такой настройки можно исключать поле для указания имени держателя карты (если такая возможность настроена для используемого проекта) и добавлять поля для сбора информации о пользователе (подробнее).
• Предоставлять пользователям возможности сохранения, использования и удаления реквизитов карт при работе с формой (эта возможность по умолчанию доступна, но может быть отключена по согласованию с курирующим менеджером ecommpay).
• Проводить классические карточные разовые оплаты (в одну и две стадии) и проверки действительности карт, с возможностью регистрировать при этом повторяемые оплаты — с выполнением актуальных вспомогательных процедур, включая аутентификацию 3‑D Secure, проверку адресов пользователей (Address Verification Service) и дополнение информации о платежах.

Пользовательский сценарий

Со стороны пользователя проведение оплаты с использованием облегчённой редакции Payment Page может выглядеть следующим образом.

1. Пользователь инициирует в интерфейсе веб-сервиса оплату, после чего ему предоставляется возможность указать данные актуальной карты.

   На этом шаге в платёжной форме могут отображаться панели выбора карты (если ранее для этого пользователя были сохранены реквизиты какой-либо карты), поля для ввода данных актуальной карты, а также дополнительные поля и флажок для согласия на сохранение указанных данных (если это настроено для используемого проекта).

2. Пользователь указывает необходимые данные и подтверждает оплату.

   В случае, если данные не указаны или указаны некорректно, непосредственно в платёжной форме пользователю отображаются соответствующие уведомления.

3. Пользователю отображается информация об ожидании результата оплаты.

   Это может выполняться как в интерфейсе платёжной формы, так и в интерфейсе веб-сервиса — с учётом того, как это настроено на стороне веб-сервиса.

4. Если это необходимо для проведения платежа, пользователю отображаются формы для дополнительных действий и он выполняет эти действия.

   Такими дополнительными формами могут выступать модальное окно с полями для ввода дополнительных сведений, отображаемое в рабочей области веб-сервиса (поверх платёжной формы), и страница аутентификации 3‑D Secure, отображаемая в используемом элементе iframe вместо платёжной формы.

5. Пользователю отображается информация о результате оплаты.

   Для этого задействуются платёжная форма и, если это настроено в веб-сервисе, то и его интерфейс.

Схема работы

При проведении оплаты с использованием облегчённой редакции платёжной формы Payment Page взаимодействие между веб-сервисом и формой строится с применением специализированных библиотек ecommpay. В типовом случае, когда на стороне веб-сервиса обеспечивается отображение собственной страницы ожидания, такое взаимодействие может осуществляться следующим образом.

Подключение, настройка и тестирование

Чтобы начать работу с облегчённой редакцией платёжной формы, следует:

1. Если ранее не были решены общие организационные вопросы, касающиеся взаимодействия с ecommpay — решить эти вопросы, подав заявку и предоставив необходимую информацию (подробнее).
2. Если ранее не были выполнены общие технические работы по интеграции Payment Page с применением специализированных библиотек — выполнить такие работы:
   1. Подключить в клиентской части CSS- и JavaScript-библиотеки от ecommpay, расположенные по адресам https://paymentpage.ecommpay.com/shared/merchant.css и https://paymentpage.ecommpay.com/shared/merchant.js соответственно.

      <link rel="stylesheet" href="https://paymentpage.ecommpay.com/shared/merchant.css" />
      <script type="text/javascript" src="https://paymentpage.ecommpay.com/shared/merchant.js"></script>

      Внимание: CSS- и JavaScript-библиотеки от ecommpay должны подключаться только через сеть доставки содержимого (Content Delivery Network, CDN). Локальное использование этих библиотек может приводить к критичным ошибкам в работе с формой.
   2. Обеспечить в серверной части сбор и подписывание параметров запросов на открытие Payment Page (автоматизировав соответствующие алгоритмы или используя SDK), а также отправку подписанных данных в клиентскую часть веб-сервиса.
3. Обеспечить в клиентской части веб-сервиса технические возможности для работы с облегчённой редакцией Payment Page:
   1. Возможность использования элемента для отображения формы.

      <div class="card-container">
          <div id="widget-container-card-embedded"></div>
      </div>

   2. Возможность вызова платёжной формы с использованием JavaScript-библиотеки от ecommpay и метода EPayWidget.runEmbedded (подробнее далее).
   3. Определение функций для обработки целевых интерфейсных событий (подробнее далее).
4. Если актуально, согласовать с курирующим менеджером ecommpay состав отображаемых полей и использование настраиваемых возможностей. В рамках такой настройки могут согласовываться:
   • скрытие поля для указания имени держателя карты, с условием включения в каждый запрос на открытие платёжной формы параметров customer_first_name и customer_last_name (и дальнейшим автоматическим заполнением имени держателя карты исходя из указанных в этих запросах сведений) или с полным отсутствием сведений о держателе карты (и возможным снижением проходимости платежей);
   • отображение дополнительных полей для сбора данных о пользователях, например номеров их телефонов и адресов электронной почты (подробнее);
   • предоставление пользователям возможностей сохранения, использования и удаления реквизитов карт при работе с формой (такая возможность по умолчанию доступна, но может быть отключена).
5. Если актуально, настроить оформление платёжной формы с помощью конструктора, встроенного в интерфейс Dashboard (подробнее).
6. Протестировать проведение платежей (с использованием тестовых проектов и карт, если это актуально) и запустить решение в работу. При этом для тестирования можно использовать тестовые проекты и номера платёжных карт (подробнее).

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

Работа с функциями обратного вызова

Использование облегчённой редакции Payment Page подразумевает работу с функциями обратного вызова, определяемыми со стороны веб-сервиса при вызове формы.

Прежде всего, для корректного проведения платежей должна определяться функция onCheckSubmit. В дополнение к этой функции могут быть актуальны следующие:

• onShowLoader — для отображения страницы ожидания веб-сервиса;
• onHideLoader — для скрытия страницы ожидания веб-сервиса (и возвращения пользователя к интерфейсу платёжной формы);
• onPaymentSubmitResult — для получения информации о регистрации запроса на проведение платежа;
• onError — для получения информации об ошибках на стороне платёжной формы.

Помимо этого, могут определяться и другие актуальные функции, позволяющие контролировать работу пользователей с интерфейсом платёжной формы (подробнее).

Определение актуальных функций в клиентской части веб-сервиса может выглядеть следующим образом.

const checkoutButtonsWidget = EPayWidget.runEmbedded({
    ...configObj,
 
    // Определение функции для отображения страницы ожидания веб-сервиса
    onShowLoader: merchantPage.showMerchantLoader,

    // Определение функции для скрытия страницы ожидания веб-сервиса
    onHideLoader: merchantPage.hideMerchantLoader,

    // Определение функции для проверки возможности оплаты
    onCheckSubmit: async function (data, resolve, reject) {
        try {
            // Проверка корректности заказа
            if (!await merchantPage.validateCheckoutPage()) {
                return reject() // Отклонение оплаты из-за некорректного состава заказа
            }
 
            if (!await merchantAPI.validateCartAmount(checkoutButtonsWidget.configObj.payment_amount, checkoutButtonsWidget.configObj.payment_currency)) {
                return reject() // Отклонение оплаты из-за ошибок с суммой и валютой платежа
            }
 
            // Регистрация заказа на стороне веб-сервиса
            const { orderId, additionalParameters } = await merchantAPI.placeOrder(merchantPage.cart, merchantPage.customerInfo);
 
            if (!orderId) {
                return reject() // Отклонение оплаты из-за ошибок с регистрацией заказа
            }
         
            // Подтверждение оплаты со стороны веб-сервиса с указанием дополнительных сведений
            return resolve({ additional_parameters: additionalParameters});
 
        } catch (error) {
            console.error('onCheckSubmit error:', error);
            return reject();
        }
    },

    // Определение функции для получения информации о регистрации запроса в платёжной платформе
    onPaymentSubmitResult: async function (data) {
        await merchantAPI.saveTransactionId(orderId, data.request_id)
    },

    // Определение функции для отображения пользователю сообщений об ошибках
    onError: async function ({ messages }) {
        await merchantAPI.log("Payment error occurred " + messages)
        if (messages.includes("invalid payment_id")) {
            merchantPage.redirectToContactSupportPage();
        }
    },
}, 'POST');
 
    // Вызов функции trySubmit при подтверждении пользователем оплаты (щелчком по кнопке)
    document.getElementById('placeOrderBtn').addEventListener('click', function() {
        checkoutButtonsWidget.trySubmit();
    });

Использование

В целом для проведения платежа с использованием облегчённой редакции платёжной формы со стороны веб-сервиса необходимо следующее.

1. Сформировать запрос на открытие платёжной формы. В таком запросе должен указываться JavaScript-объект configObj с параметрами вызова формы и с подписью к ним. К базовому минимуму параметров, обязательному для проведения платежа, в этом случае относятся:
   • target_element — идентификатор используемоготого элемента iframe, в котором необходимо открыть платёжную форму;
   • payment_id — идентификатор платежа, уникальный в рамках проекта;
   • payment_amount — сумма платежа в дробных единицах валюты;
   • payment_currency — буквенный код валюты платежа в формате ISO-4217 alpha-3;
   • project_id — идентификатор проекта, полученный от ecommpay при интеграции;
   • merchant_domain — доменное имя веб-сервиса, в котором необходимо открыть платёжную форму;
   • force_payment_method — служебный код платёжного метода, который следует использовать в качестве предварительно выбранного, со значением card;
   • mode — указатель режима работы Payment Page со значением purchase для любой из разовых оплат или card_verify для проверки действительности карты;
   • signature — подпись запроса, составленная после указания всех целевых параметров.

   const configObj = {
       target_element: "widget-container-card-embedded",
       payment_id: "X03937",
       payment_amount: 1960,
       payment_currency: "EUR",
       project_id: 22,
       merchant_domain: "cosmoshop.jupiter.example",
       force_payment_method : "card",
       signature: "0ByxpQ30hfTIjaCCsVIwVyabcDEF123"
   };

2. Вызвать платёжную форму с помощью метода EPayWidget.runEmbedded. При вызове платёжной формы необходимо указать, указав при этом JavaScript-объект configObj и определитьопределив целевые функции обратного вызова, такие как onCheckSubmit, onShowLoader и onHideLoader (подробнее далее).
3. При подтверждении пользователем оплаты, например при щелчке по кнопке подтверждения, вызвать метод trySubmit используемого экземпляра класса EPayWidget. В результате вызова этого метода на стороне Payment Page выполняется первичная проверка указанных пользователем сведений, после чего автоматически выполняется одна из функций:
   • onCheckSubmit — при отсутствии ошибок, без предоставления информации в объекте data;
   • onValidationError — при наличии ошибок, с указанием в объекте data информации об этих ошибках.

   "{\"message\":\"epframe.embedded_mode.validation_error\",\"data\":{\"pan\":\"Invalid card number.\",\"month_year\":\"Expiry date required.\",\"cvv\":\"CVV2/CVC2 required.\",\"card_holder\":\"Cardholder name required.\"},\"guid\":\"288d-f68c-e53d-3890\"}"
   

4. Проверить сведения об оплате (включая сумму и валюту платежа, а также другие обязательные сведения) и обеспечить вызов актуального метода для функции onCheckSubmit:
   • resolve — для подтверждения оплаты (при отсутствии ошибок);
   • reject — для отклонения оплаты (при наличии ошибок).

   Вместе с подтверждением платежа на этом этапе можно указать в объекте additional_parameters дополнительные сведения о пользователе, если они не были переданы при вызове платёжной формы или их необходимо изменить, а также адреса веб-сервиса для автоматического итогового перенаправления пользователя при проведении и отклонении оплаты.

   {
   // Общие сведения о пользователе
       customer_id:"customer_112",
       customer_first_name:"Arthur",
       customer_last_name:"McDonald",
       customer_phone:"447700900123",
       customer_email:"mcdonald@space.com"
    
   // Сведения об адресе проживания пользователя
       customer_country:"GB",
       customer_city:"Belfast",
       customer_address:"14A Cosmos Crescent, Flat 25",
       customer_zip:"BT99 0ZZ",
    
   // Сведения о расчётном адресе пользователя
       billing_country:"GB",
       billing_city:"Belfast",
       billing_address:"14A Cosmos Crescent, Flat 25",
       billing_postal:"BT99 0ZZ",
    
   // Сведения об адресе пользователя, используемом для проверки Address Verification Service
       avs_street_address:"14A Cosmos Crescent, Flat 25",
       avs_post_code:"BT99 0ZZ",
    
   // Сведения для отображения пользователю актуальной страницы веб-сервиса по итогам оплаты
       redirect_success_url:"https://cosmoshop.jupiter.example/pages/success",
       redirect_success_mode:"parent_page",
       redirect_fail_url:"https://cosmoshop.jupiter.example/pages/failed",
       redirect_fail_mode:"parent_page"
   }

Используемые параметры

При вызове облегчённой редакции платёжной формы могут использоваться следующие параметры.

{
    "register": true,
    "type": "U"
}

Дополнительные материалы

При работе с платёжной платформой через облегчённую редакцию платёжной формы Payment Page могут быть полезны следующие материалы:

• Индивидуальное оформление — статья о работе с конструктором оформления Payment Page.
• Сбор данных о пользователях — статья о возможности получать и использовать дополнительную информацию о пользователях.
• Повторные попытки проведения платежей — статья о возможности предоставлять пользователям дополнительные попытки проведения платежей.
• Работа с подписью к данным — статья о порядке создания и проверки подписи в программных запросах и оповещениях при взаимодействии с платёжной платформой.
• SDK для работы с подписью — материалы о порядке применения SDK для работы с подписью.
• Контроль интерфейсных событий — статья о возможностях получать и обрабатывать информацию о различных интерфейсных событиях, связанных с платёжной формой и действиями пользователя в ней.
• Работа с информацией о платежах — раздел со статьями о способах получения информации, которая может быть актуальна для контроля проведения платежей и анализа результатов при работе с платёжной платформой.
• Тестовые карты — статья об актуальных номерах карт для тестирования различных сценариев проведения платежей.