Встраивание кнопок для платежей с использованием методов Apple Pay и Google Pay

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

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

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

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

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

Со стороны пользователя проведение оплаты в этом случае может выглядеть следующим образом.

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

Схема работы

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

Взаимодействие при указании сведений о доставке на стороне сервиса выбранного метода (Apple Pay или Google Pay) может осуществляться следующим образом.

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

Чтобы начать работу со встроенными кнопками, следует:

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>

2. Добавить в клиентской части элемент, предназначенный для отображения в нём кнопок заданных методов.

   // Отображение двух кнопок в разных элементах iframe
   <div class = "container-one" >
       <div id= "widget-container-google-pay" ></div>
       <div id= "widget-container-apple-pay" ></div>
   </div>
   
   // Отображение двух кнопок в одном элементе iframe
   </div>
       <div class = "container-two" >
       <div id= "widget-container-one-click-buttons" ></div>
   </div>

3. Обеспечить в серверной части сбор и подписывание параметров запросов на открытие Payment Page (в том числе с применением SDK для работы с подписью, если это актуально), а также отправку подписанных данных в клиентскую часть веб-сервиса.
4. Обеспечить в клиентской части вызов платёжной формы с использованием JavaScript-библиотеки от ecommpay и метода EPayWidget.runEmbedded.
5. Реализовать в клиентской части функции для обработки интерфейсных событий. Вместе с функциями, информация о которых представлена в этой статье, могут использоваться и другие (подробнее).
6. Для работы с платёжным методом Apple Pay — предварительно зарегистрировать рабочие домены веб-сервиса в сервисе Apple Pay.

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

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

1. На стороне веб-сервиса необходимо сформировать запрос на открытие платёжной формы. В запросе должен указываться JavaScript-объект configObj с параметрами вызова платёжной формы и с подписью к ним.

   При формировании таких запросов необходимо учитывать следующее:

   • К базовому минимуму параметров, обязательному для проведения платежа, в этом случае относятся:
     • target_element — идентификатор того элемента iframe, в котором необходимо открыть платёжную форму;
     • payment_id — идентификатор платежа, уникальный в рамках проекта;
     • payment_amount — сумма платежа в дробных единицах валюты;
     • payment_currency — буквенный код валюты платежа в формате ISO-4217 alpha-3;
     • project_id — идентификатор проекта, полученный от ecommpay при интеграции;
     • merchant_domain — доменное имя веб-сервиса, в котором необходимо открыть платёжную форму;
     • force_payment_group для отображения кнопок обоих методов (со значением one_click_buttons) или force_payment_method для отображения кнопки только одного из методов (со значением apple_pay_core для метода Apple Pay или google_pay_host для метода Google Pay);
     • mode — указатель режима работы Payment Page со значением purchase;
     • signature — подпись запроса, составленная после указания всех целевых параметров.

   • Для инициирования дополнительных действий на стороне сервисов Apple Pay и Google Pay дополнительно можно указывать параметр payment_methods_options и включать в него следующее:

     • перечень запрашиваемых сведений о пользователе в виде массива billing_contact_fields для сбора определённых сведений о пользователе, если сбор этих сведений не настроен для всех платежей в рамках используемого проекта (подробнее);
     • сведения о доставке товара или услуги пользователю в составе объекта shipping для выбора пользователем способа доставки.

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

   • Для отображения кнопок в разных элементах iframe для каждого из них необходимо сформировать отдельный запрос.

   {
     "target_element":"widget-container-one-click-buttons",
     "payment_id":"X03936",
     "payment_amount":131960,
     "payment_currency":"USD",
     "project_id":22,
     "merchant_domain":"cosmoshop.jupiter.example",
     "force_payment_group":"one_click_buttons",
     "mode":"purchase",
     "signature":"YWb6Z20ByxpQ30hfTIjaCCsVIwVynXV"
   }

   {
     "google_pay_host":{
       "billing_contact_fields":[
         "email",
         "name",
         "phone",
         "billing_address",
         "postal_code"
       ],
       "shipping":{
         "shipping_fields":[
           "shipping_address",
           "name",
           "phone"
         ],
         "allowed_country_codes":[
           "GB",
           "IE"
         ],
         "shipping_methods":[
           {
             "label":"Speed of sound shipping",
             "detail":"Express shipping (1 hour)",
             "amount":199,
             "identifier":"cosmo-shipping-009"
           },
           {
             "label":"Warp drive shipping",
             "detail":"Instant shipping",
             "amount":2999,
             "identifier":"cosmo-shipping-012"
           }
         ]
       }
     },
     "apple_pay_core":{
       "billing_contact_fields":[
         "email",
         "name",
         "phone",
         "billing_address",
         "postal_code"
       ],
       "shipping":{
         "shipping_fields":[
           "shipping_address",
           "name",
           "phone"
         ],
         "shipping_methods":[
           {
             "label":"Speed of sound shipping",
             "detail":"Express shipping (1 hour)",
             "amount":199,
             "identifier":"cosmo-shipping-009"
           },
           {
             "label":"Warp drive shipping",
             "detail":"Instant shipping",
             "amount":2999,
             "identifier":"cosmo-shipping-012"
           }
         ]
       }
     }
   }

2. Со стороны веб-сервиса необходимо вызвать платёжную форму с помощью метода EPayWidget.runEmbedded, с указанием JavaScript-объекта configObj и функции-обработчика onCheckSubmit, после чего пользователю отображается кнопка.

   Функция onCheckSubmit предназначена для регистрации и обработки информации о щёлчке кнопки.

   const checkoutButtonsWidget = EPayWidget.runEmbedded({
       ...configObj,
       onCheckSubmit: async function (data, resolve, reject) {
           if (!await merchantPage.validateCheckoutPage()) {
               return reject() // Отклонение оплаты
           }
           if (!await merchantAPI.validateCartAmount(checkoutButtonsWidget.configObj.payment_amount, checkoutButtonsWidget.configObj.payment_currency)) {
               return reject() // Отклонение оплаты
           };
           return resolve(); // Подтверждение оплаты, с возможностью указать объект additional_parameters в качестве аргумента
       },
   }, 'POST');

3. На стороне Payment Page регистрируется щелчок кнопки, после чего на стороне веб-сервиса следует проверить сведения об оплате (такие как сумма и валюта платежа, а также другие обязательные сведения) и вызвать одну из функций, 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",
   };

4. Если в запросе на открытие платёжной формы были указаны сведения о доставке товара или услуги пользователю (в составе объекта shipping), дополнительно необходимо следующее:
   1. После указания пользователем адреса доставки, регистрируемого с помощью функции onCheckShippingAddress библиотеки merchant.js, на стороне веб-сервиса следует проверить возможность доставки на указанный адрес.

      {
        "region":"Belfast City",
        "city":"Belfast",
        "country_code":"GB",
        "postal_code":"BT99 0ZZ"
      }

      Далее в зависимости от результата проверки следует вызвать одну из функций:

      • onCheckShippingAddress.resolve для подтверждения возможности доставки, с обязательным указанием суммы платежа с учётом этой доставки и необязательным указанием обновлённых сведений о параметрах доставки (в массиве shipping_methods);
      • onCheckShippingAddress.reject для её отклонения, с необязательным указанием текстов сообщений, которые необходимо отобразить пользователю — как общего сообщения об ошибке, так и отдельных пояснений для любых указанных параметров доставки (рекомендуется указывать подробные сведения об ошибках для повышения удобства пользователей).

        errors = {
            "fields": {
                "country_code": "Supported shipping countries: GB, DE, IT",
                "region": "This region is not supported",
                "city": "Only Dublin is available",
                "postal_code": "The range of postal address 10060 - 100150",
            },
            "message": "Cannot ship to the provided address"
        }

      Этот шаг может выполняться несколько раз, а также может выполняться до или после следующего шага, в зависимости от порядка действий пользователя и особенностей используемого сервиса.

   2. После выбора пользователем способа доставки, регистрируемого с помощью функции onCheckShippingMethod библиотеки merchant.js, на стороне веб-сервиса следует проверить доступность этого способа.

      {
        "identifier":"cosmo-shipping-012"
      }

      Далее в зависимости от результата проверки следует вызвать одну из функций:

      • onCheckShippingMethod.resolve для подтверждения возможности доставки, с обязательным указанием суммы платежа с учётом этой доставки;
      • onCheckShippingMethod.reject для её отклонения, с обязательным указанием суммы платежа без учёта доставки и необязательным указанием текста сообщения об ошибке, которое необходимо отобразить пользователю (рекомендуется указывать подробные сведения об ошибках для повышения удобства пользователей).

        errors = {
            "message": "This shipping option cannot be selected for this address",
        }

      Этот шаг может выполняться несколько раз, а также может выполняться до или после предыдущего шага, в зависимости от порядка действий пользователя и особенностей используемого сервиса.

   3. После подтверждения пользователем оплаты, регистрируемого с помощью функции onConfirmation библиотеки merchant.js, на стороне веб-сервиса следует проверить сведения об оплате с учётом указанных пользователем способа и адреса доставки, в том числе актуальную сумму платежа.

      {
        "customer":{
            "email":"mcdonald@space.com",
            "first_name":"Arthur",
            "last_name":"McDonald",
            "phone":"447700900123"
         },
        "billing_address":{
            "address":"14A Cosmos Crescent, Flat 25",
            "city":"Belfast",
            "region":"Belfast City",
            "country_code":"GB",
            "postal_code":"BT99 0ZZ"
        },
        "shipping_address":{
          "address":"Dock 7, Innovation Hangar",
          "city":"Belfast",
          "region":"Belfast City",
          "country_code":"GB",
          "postal_code":"BT99 1XY",
          "first_name":"Arthur",
          "last_name":"McDonald",
          "phone":"447700900321"
        }
      }

      Далее в зависимости от результата проверки следует вызвать одну из функций:

      • onConfirmation.resolve для подтверждения оплаты, с основными сведениями об оплате — идентификаторами проекта и платежа, а также суммой и валютой платежа — и с подписью к ним (в объекте payment_update).

        {
          "payment_id":"X03936",
          "project_id":22,
          "payment_amount":134959,
          "payment_currency":"USD",
          "signature":"a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u"
        }

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

        {"billing_country": "GB", "customer_email": "mcdonald@space.com", "avs_post_code": "BR1 1AA", "redirect_success_url":"https://cosmoshop.jupiter.example/order?id=123"}
        

      • onConfirmation.reject для её отклонения, с указанием суммы платежа и того текста сообщения об ошибке, который необходимо отобразить пользователю.

        errors = {
            "fields": {
                "country_code": "Supported shipping countries: GB, DE, IT",
                "region": "This region is not supported",
                "city": "Only Dublin is available",
                "postal_code": "The range of postal address 10060 - 100150",
            },
            "message": "Cannot ship to the provided address"
        }

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

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

const expressButtons = EPayWidget.runEmbedded({
    payment_amount: 131960,
    payment_currency: "USD",
    project_id: "22",
    payment_id: "X03936",
    force_payment_group: "one_click_buttons",
    payment_methods_options: {"google_pay_host": {"billing_contact_fields": ["name", "email", "phone", "billing_address"]}},
    target_element: "widget-container-one-click-buttons",
    merchant_domain: cosmoshop.jupiter.example,
    signature: "abcYWb6Z30hfTIjaCCsVIDEF123",
 
    onShowLoader: merchantPage.showMerchantLoader,
    onHideLoader: merchantPage.hideMerchantLoader,
    onCheckSubmit: async function (data, resolve, reject) {
        if (await merchantAPI.canStartPayment(merchantPage.cart)) {
            return resolve();
        }
        return reject();
    },
    onCheckShippingAddress: async function (data, resolve, reject) {
        const {addressIsAvailable, newPaymentAmount, newShippingMethods, errors} = await merchantAPI.validateShippingAddress(data);
        if (addressIsAvailable) {
            return resolve({payment_amount: newPaymentAmount, shipping_methods: newShippingMethods});
        } else {
            return reject({payment_amount: newPaymentAmount, errors});
        }
    },
    onCheckShippingMethod: async function (data, resolve, reject) {
        const {addressIsAvailable, newPaymentAmount} = await merchantAPI.saveShippingMethod(orderId, data.identifier);
        if (addressIsAvailable) {
            return resolve({payment_amount: newPaymentAmount});
        } else {
            return reject({payment_amount: newPaymentAmount});
        }
    },
    onConfirmation: async function (data, resolve, reject) {
        const { orderId, paymentUpdate, additionalParameters, errors } = await merchantAPI.placeOrder(merchantPage.cart, merchantPage.customerInfo);
         
        if (orderId) {
            return resolve({payment_update: paymentUpdate, additional_parameters: additionalParameters});
        } else {
            return reject({errors})
        }
    },
    onPaymentSubmitResult: async function (data) {
        await merchantAPI.saveTransactionId(data.request_id)
    },
    onError: async function ({ messages }) {
        await merchantAPI.log("Payment error occurred " + messages)
        if (messages.includes("invalid payment_id")) {
            merchantPage.redirectToContactSupportPage();
        }
    },
});