Using embedded buttons for Apple Pay and Google Pay 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 appearance 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.

Special aspects

When using embedded Apple Pay and Google Pay buttons from ecommpay, consider the following special aspects:

• Embedding branded payment buttons directly into the web service of the merchant can improve user experience and increase conversion rates: firstly, the buttons of these global payment services are easily recognised and enhance customer trust, and, secondly, with the use of these buttons the number of steps in the standard user scenario is kept to a minimum, without any additional redirections and confirmations. To compare, opening Payment Page with the Apple Pay or Google Pay method preselected adds at least one more step to a similar user scenario.
• The design of the branded buttons is customised according to the guidelines of Apple and Google and can be configured by the merchant as long as the style is consistent with their recommendations.
• The minimalist design of the embedded buttons can be useful in different cases, namely, for interfaces with high information density or for mobile purchases.
• Processing a payment with the use of embedded buttons implies native collection of necessary additional customer data (including the customer's billing address, shipping address and shipping option, and other details) directly in the Apple Pay and Google Pay services, within the payment session. It spares merchants the effort of collecting these data on the side of the web service or in Payment Page, as well as prevents increasing the number of steps in user scenarios and eliminates the need to take more action in order to configure this functionality.
• When the customer has been authenticated in the Apple Pay or Google Pay service, and this service already has relevant information, the customer's payment can be processed according to the express checkout flow. This processing workflow implies that all necessary customer data (card details, billing address, and shipping information) is automatically collected and specified. In addition, the relevant shipping information and billing address can be available to the merchant through the payment session of this service. The express checkout flow can be useful for unregistered customers, as it enables guest checkout, without the need to create a user account in the web service.
• The Apple Pay and Google Pay buttons can be embedded into any page of the web service (for example, the product page or the section of the product catalogue) and into almost any structural element of the web page (including menus, various panels and containers), which ensures high level of flexibility and allows implementation of various ways to guide customers to payment.

Processing scenario

Below is a user scenario of making a purchase with embedded buttons.

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).

Button design styles

The merchant can customise different aspects of the branded button's appearance, including the button's colour, contents (i.e. the caption and the logo), placement, size, and corner radius, with the help of the following parameters for opening the payment form.

When working with the parameters for customising the appearance of branded buttons, consider the following:

• You must comply with the requirements and guidelines of Apple (details) and Google (details).
• Values that you specify for parameters determining the placement and the size of the buttons apply to all buttons used, whereas other parameters can be passed to customise each branded button individually.
• If you specify the layout option for the buttons, it will be applied only when the width of the element where the buttons are embedded exceeds 1047 pixels. In all other cases, the buttons will be vertically stacked.
• To resize the buttons, you can specify their height, but not their width. The width is determined automatically and is adjusted depending on the width of the element where the buttons are embedded and the number of buttons in one row. The minimum allowed width of each button is 160 pixels, and the maximum allowed corresponds to the width of the element where the buttons are embedded. The default height of the buttons is 44 pixels.

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.
   Warning: Keep in mind that to ensure correct behaviour of the payment form, you must link the ecommpay CSS library via the CDN (Content Delivery Network). Storing this library locally is not allowed.

   <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="row">
     <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 id="widget-container-one-click-buttons"></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 made with the use of embedded payment buttons, you need to:

1. Generate requests to display the required buttons.
2. Invoke the payment form displayed as branded buttons.
3. Confirm the transition to payment when the customer clicks a specific button.
4. Confirm the availability of the shipping option selected by the customer.
5. Confirm processing the payment with the finalised set of parameters.

Here is a more detailed description of these steps:

1. Generate the required number of requests to open a payment form displayed as branded buttons.

   It can be one request to display both buttons in a single iframe element, two separate requests to display each button in separate iframe elements, or one separate request to display just one of the buttons. Each of the requests 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 parameters have been specified

   • To initiate additional steps to be performed on the side of the Apple Pay and Google Pay services, use the payment_methods_options parameter and specify the following:

     • 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)
     • information about the available shipping options in the shipping object—so that the customer can select one

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

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

   {
     "express_checkout":{
       "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"
           }
         ]
       },
         "buttons":{
            "max_column":1,
            "height": 40,
            "border_radius": 100
         }
     },
      "google_pay_host":{
         "shipping":{
            "allowed_country_codes":[
               "GB",
               "IE"
            ]
         },
         "button":{
            "color":"black",
            "type":"checkout",
            "border_type":"no_border"
         }
      },
     "apple_pay_core":{
         "button":{
            "theme":"black",
            "type":"buy"
         }
      }
   }

2. Invoke the payment form using the EPayWidget.runEmbedded method.

   When invoking the form, specify the configObj JavaScript object and declare necessary event handler functions, such as onCheckSubmit (used for handling button click information; more details below).

   const checkoutButtonsWidget = EPayWidget.runEmbedded({
       ...configObj,
       onCheckSubmit: async function (data, resolve, reject) {
           if (!await merchantPage.validateCheckoutPage()) {
               return reject() // Decline of purchase
           }
           if (!await merchantAPI.validateCartAmount(checkoutButtonsWidget.configObj.payment_amount, checkoutButtonsWidget.configObj.payment_currency)) {
               return reject() // Decline of purchase
           };
           return resolve(); // Purchase confirmation, with the option to specify the additional_parameters object as an argument
       },
   }, 'POST');

3. When the customer confirms the payment (via the embedded button), check the payment details (including the amount and currency, as well as other important parameters) and call the relevant function: resolve to confirm the purchase or reject to decline it.

   At this stage, along with the payment confirmation, you can specify additional information if it was not specified when the payment form was invoked or if the information needs to be changed. You can pass:

   • customer information and redirect URLs—in the additional_parameters object
   • the customer identifier, information about the purchased items, and extended purchase data to be used on the web service side—in the payment_update object (in which you also specify the project identifier, the payment identifier, amount, and currency, as well as the signature for the parameters in this object)

   If the payment is declined, the customer should be provided with information about the error on the web service side.

   {
   // General customer information
       customer_first_name:"Arthur",
       customer_last_name:"McDonald",
       customer_phone:"447700900123",
       customer_email:"mcdonald@space.com"
    
   // Customer's residential 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 used 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",
   };

   {
      "project_id":22,
      "payment_id":"X03936",
      "payment_amount":131960,
      "payment_currency":"USD",
      "customer_id":"customer_112",
      "receipt_data":"eyJwb3NpdGlvbnMiOiBbeyJxdWFudGl0eSI6IDMsICJhbW91bnQiOiAxMDAwMCwgInRheCI6IDE4LCAidGF4X2Ftb3VudCI6IDE4MDAsICJkZXNjcmlwdGlvbiI6ICJEZXNpZ24gZnJhbWUifV0sICJ0b3RhbF90YXhfYW1vdW50IjogMTgwMCwgImNvbW1vbl90YXgiOiAxOH0=",
      "merchant_data":"{\"items\":[{\"sku\":\"GM12-CC\", \"description\":\"10 Copper Coins\",\"count\":1}, {\"sku\":\"GM12-GC\",\"description\":\"Golden Coin\", \"count\":2}],\"total_count\":3,\"user_id\":\"122\"",
      "signature":"OoyvuCort6RIe8jofbUwZMWhkTaIIr7iIDFwry3bKc0iWGRMqPB1/8jVK4yJX+dv2AZDrNU7Ip4TMcqMG8AD8w=="
   }

4. If the request to open a payment form included information about available shipping options for goods or services in the shipping object, verify and confirm (or decline) the shipping availability.

   Use the onCheckShippingAddress and onCheckShippingMethod functions of the merchant.js library to respond to the customer's input of a shipping address and shipping option, respectively. When using these functions, keep in mind that the order in which the shipping address and shipping option are specified may vary depending on the specifics of the service being used, and that checking the shipping availability is repeated whenever the customer's input changes. You are also recommended to ensure that the error messages related to shipping availability are structured to provide sufficient information and convenience to customers and prevent future errors.

   To check shipping availability, each time the customer changes shipping parameters, follow these steps:

   • Regarding the shipping address, check the availability of shipping to the address specified by the customer and call the relevant function:
     • onCheckShippingAddress.resolve—to confirm shipping availability, with the mandatory passing of the payment amount with shipping included and, if applicable, with updated shipping parameters (specified in the shipping_methods array).
     • onCheckShippingAddress.reject—to notify that shipping is unavailable, with the mandatory passing of the payment amount excluding shipping and, if applicable, with the messages to be displayed to the customer, including a general error message and specific clarifications for each of the shipping details.

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

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

   • Regarding the shipping option, check the availability of the shipping option selected by the customer and call the relevant function:

     • onCheckShippingMethod.resolve—to confirm shipping availability, with the mandatory passing of the payment amount with shipping included.
     • onCheckShippingMethod.reject—to notify that shipping is unavailable, with the mandatory passing of the payment amount excluding shipping and, if applicable, with the messages to be displayed to the customer.

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

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

5. If you need to confirm the payment (with the selected shipping address and shipping option, or other details provided by the customer), check whether the finalised payment information is accurate.

   Use the onConfirmation function of the merchant.js library to obtain this information. After verifying, call the relevant function:

   • onConfirmation.resolve—to confirm the payment, with final details provided by the web service. This information includes:
     • the project identifier, the identifier, amount, and currency of the payment, and other relevant information (as needed, including information about the purchased items and extended purchase data for subsequent use on the web service side) and the signature for these parameters in the payment_update object
     • customer information and redirect URLs (if such information needs to be specified or updated) in the additional_parameters object
   • onConfirmation.reject—to decline the payment, with the mandatory passing of the payment amount and, if applicable, with the error message to be displayed to the customer.

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

   {
      "project_id":22,
      "payment_id":"X03936",
      "payment_amount":131960,
      "payment_currency":"USD",
      "customer_id":"customer_112",
      "receipt_data":"eyJwb3NpdGlvbnMiOiBbeyJxdWFudGl0eSI6IDMsICJhbW91bnQiOiAxMDAwMCwgInRheCI6IDE4LCAidGF4X2Ftb3VudCI6IDE4MDAsICJkZXNjcmlwdGlvbiI6ICJEZXNpZ24gZnJhbWUifV0sICJ0b3RhbF90YXhfYW1vdW50IjogMTgwMCwgImNvbW1vbl90YXgiOiAxOH0=",
      "merchant_data":"{\"items\":[{\"sku\":\"GM12-CC\", \"description\":\"10 Copper Coins\",\"count\":1}, {\"sku\":\"GM12-GC\",\"description\":\"Golden Coin\", \"count\":2}],\"total_count\":3,\"user_id\":\"122\"",
      "signature":"OoyvuCort6RIe8jofbUwZMWhkTaIIr7iIDFwry3bKc0iWGRMqPB1/8jVK4yJX+dv2AZDrNU7Ip4TMcqMG8AD8w=="
   }

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

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

Additionally, on the merchant's web service side, it is possible to manage the display of the preloader page and 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

You can also use callbacks to monitor payment processing results.

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