Using embedded payment buttons for Apple Pay, Google Pay, and Express checkout payments

Overview

In certain processing scenarios merchants may need to use branded payment buttons that allow their customers to pay for orders with the Apple Pay and Google Pay payment methods. When working with the ecommpay payment platform, you can use a specialised version of Payment Page embedded into the web service in the form of payment buttons with specific brand identities. These embedded buttons allow you to process express checkout payments, with the collection of all required information, including shipping details, in the services of the payment methods used to make the purchase.

When this functionality is implemented, the interface of the web service displays branded buttons of specific payment methods clicking which redirects the customer to the relevant payment service without involvement of the Payment Page interface. However, if additional data is required for payment processing, the customer can be shown a modal window with the relevant pages of the payment form. To avoid such cases, you are recommended to ensure that all additional data is passed in the requests for invoking Payment Page as well as to use the capability to collect customer data in the Apple Pay and Google Pay services.

Embedded payment buttons functionality is supported for Apple Pay and Google Pay payments and can be combined with invoking Payment Page for other payment processing options including card payments with tokens, redirecting to other payment methods by preselection in the web service, and using all available payment methods on the form. The size of embedded buttons can be configured via parameters for invoking the payment form. As of now, it is not possible to use the Payment Page Designer in Dashboard to set up the design of these buttons; however, the designer tool can be useful if you need to customise those pages of the payment form that are shown to the customers if additional data is required.

Processing scenario

The basic steps of the customer payment scenario with the use of embedded payment buttons are the following:

1. The customer navigates to a page in the web service interface where embedded buttons are displayed and initiates a purchase using one of the payment methods.
2. The customer is redirected to the service of the selected method.
3. In the service, the customer provides a shipping address and selects the shipping option, if necessary, and performs other required actions.
4. The customer is notified about the payment result (how this information is communicated depends on the configuration of the web service).

Workflow

The interaction between the web service and the payment platform when the branded buttons are embedded requires the use of specialised libraries provided by ecommpay and includes the following steps.

The interaction between the web service and the payment platform when shipping information is provided in the service of the selected payment method (Google Pay or Apple Pay) includes the following steps.

Setup and configuration

To start working with the embedded payment buttons functionality:

1. On the client side, add the ecommpay CSS and JavaScript libraries available at https://paymentpage.ecommpay.com/shared/merchant.css and 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. On the client side, add the element for displaying embedded payment buttons.

   // Displaying each embedded payment button in a separate iframe element
   <div class = "container-one" >
       <div id= "widget-container-google-pay" ></div>
       <div id= "widget-container-apple-pay" ></div>
   </div>
   
   // Displaying two embedded payment buttons in a single iframe element
   </div>
       <div class = "container-two" >
       <div id= "widget-container-one-click-buttons" ></div>
   </div>

3. On the server side, set up data signing and sending signed data to the client side of the web service (use one of the specialised SDKs).
4. Implement invoking the payment form on the client side using the JavaScript library from ecommpay and the EPayWidget.runEmbedded method.
5. On the client side, implement functions for handling interface events. In addition to the functions described in this article, you can use event handlers described here.
6. If you plan to take Apple Pay payments, make sure to register production domains of your web service in the Apple Pay service.

Use

In general, to process a payment using embedded payment buttons, the following is required:

1. On the web service side, generate a request to open the payment form. The request must contain the configObj JavaScript object with the parameters for invoking the payment form and the signature for them.

   When creating a request for opening the payment form, consider the following:

   • The essential data set required for processing a payment in this case includes:
     • target_element—identifier of the iframe element in which the payment form should be opened
     • payment_id—payment identifier unique within the project
     • payment_amount—payment amount in the smallest currency unit
     • payment_currency—payment currency code in the ISO-4217 alpha-3 format
     • project_id—project identifier obtained from ecommpay during integration
     • merchant_domain—domain name of the web service in which the payment form should be opened
     • force_payment_group to display buttons for both methods (with the value one_click_buttons) or force_payment_method to display the button for only one of the methods (with the value apple_pay_core for the Apple Pay method or google_pay_host for the Google Pay method)
     • mode—Payment Page operation mode indicator with the value purchase
     • signature—request signature generated after all target parameters are specified
   • To initiate additional steps to be performed on the side of the Apple Pay and Google Pay services, specify the payment_methods_options parameter with:
     • a list of requested customer information in the billing_contact_fields array if collection of customer information is not configured for all payments within the project being used (details)
     • shipping information in the shipping object to enable shipping option selection by the customer

     The detailed list of information that can be passed in the payment_methods_options parameter can be found below.

   • To display each button in a separate iframe element, send a separate request for each of them.

   {
     "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. On the web service side, invoke the payment form using the EPayWidget.runEmbedded method, specifying the configObj JavaScript object and the onCheckSubmit handler function, following which the embedded payment button is displayed to the customer.

   The onCheckSubmit function is intended for registering and processing information about clicking the embedded button.

   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();
       },
   }, 'POST');

3. On the Payment Page side, clicking the embedded payment button is registered, following which on the web service side you need to verify payment information (such as the payment amount and currency as well as other required data) and call one of the functions: resolve to confirm the payment or reject to decline it. If the payment is declined, the customer should be provided with the error information from the web service side.

   Along with the payment confirmation, at this stage you can pass the customer information if it was not passed when the payment form was initialised or if it needs to be changed and specify URLs for automatic customer redirection once the payment is complete. For this, use the additional_parameters object.

   {
   // General customer information
       customer_id:"customer_112",
       customer_first_name:"Arthur",
       customer_last_name:"McDonald",
       customer_phone:"447700900123",
       customer_email:"mcdonald@space.com",
    
   // Customer's address
       customer_country:"GB",
       customer_city:"Belfast",
       customer_address:"14A Cosmos Crescent, Flat 25",
       customer_zip:"BT99 0ZZ",
    
   // Customer's billing address
       billing_country:"GB",
       billing_city:"Belfast",
       billing_address:"14A Cosmos Crescent, Flat 25",
       billing_postal:"BT99 0ZZ",
    
   // Customer's address for the AVS check
       avs_street_address:"14A Cosmos Crescent, Flat 25",
       avs_post_code:"BT99 0ZZ",
    
   // Customer's redirection information
       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. If the request for opening the payment form contains shipping information (in the shipping object), proceed as follows:
   1. Once the customer enters the shipping address, which is registered with the onCheckShippingAddress function of the merchant.js library, ensure that the web service checks the availability of shipping to the specified address.

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

      Depending on the result of the availability check, call one of the following functions:

      • onCheckShippingAddress.resolve—for confirming shipping availability, with specifying the amount of the purchase with shipping being mandatory and specifying updated information about shipping details (in the shipping_methods array)—optional.
      • onCheckShippingAddress.reject—for notifying that shipping is unavailable, with an option to specify the error messages to be shown to the customer (both the general error message and the specific clarifications for each of the shipping details). It is recommended that you show extended error information for customers' convenience.

        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",
        }

      This step can be performed several times. It can also be performed before or after the step that follows as it depends on the actions of the customer and the specifics of the service.

   2. Once the customer selects the shipping option, which is registered with the onCheckShippingMethod function of the merchant.js library, ensure that the web service checks the availability of this shipping option.

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

      Depending on the result of the availability check, call one of the following functions:

      • onCheckShippingMethod.resolve—for confirming the shipping option availability, with specifying the amount of the purchase with shipping being mandatory.
      • onCheckShippingMethod.reject—for notifying that the shipping option is unavailable, with specifying the amount of the purchase with shipping being mandatory and the error message to be shown to the customer—optional. It is recommended that you show extended error information for customers' convenience.

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

      This step can be performed several times. It can also be performed before or after the step that follows as it depends on the actions of the customer and the specifics of the service.

   3. After the customer confirms the payment, which is registered with the onConfirmation function of the merchant.js library, ensure that the web service checks the details of the payment—specifically, the provided shipping address, the shipping option selected by the customer, and the updated purchase amount.

      {
        "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"
        }
      }

      Depending on the result of the availability check, call one of the following functions:

      • onConfirmation.resolve—for confirming the payment, with the essential payment information—project and payment identifiers, the payment amount and currency, and the signature (in the payment_update object).

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

        At this step, you can submit necessary customer data if it was not passed in the request to open the payment form or it needs changing in the additional_parameters object.

        {"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—for declining the payment, with the payment amount and the error message to be shown to the customer.

        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"
        }

      The information about the final purchase amount with the included shipping cost is passed in callbacks.

Additionally, on the merchant's web service side, it is possible to manage the display of the preloader page, as well as receive information about errors and payment processing results using the following functions for handling interface events:

• onShowLoader—for displaying the web service preloader
• onHideLoader—for hiding the web service preloader (if it is necessary to display the payment form pages to the customer)
• onPaymentSubmitResult—for receiving information about the request identifier (if it is necessary to check payment status information)
• onError—for receiving information about errors on the payment form side

The following is an example of the HTML code for the web service frontend that ensures the capability of performing purchases made with embedded payment buttons.

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();
        }
    },
});