Integration using a microframe solution

Overview

Payment Page microframe is an embedded payment solution by ecommpay that allows merchants to use the essential functionality of the ecommpay payment form while retaining full control of the checkout experience for their customers with the least amount of setup effort. Payment Page microframe provides the capability necessary to establish a one-page checkout process with the minimalist payment form (which contains only three required fields) and the button for submitting the payment developed on the merchant side.

The basic steps of the customer payment scenario with the microframe solution are the following:

1. The customer indicates the readiness to pay in the merchant's web service. The microframe solution is invoked and the payment form is displayed to the customer.
2. The customer provides payment information by filling in the fields on the form and clicks the button to pay.
3. As the processing of the payment starts, the payment form can be hidden and a preloader element (configured on the web service side) can be shown to the customer.
4. Once the payment has been processed, the customer is redirected to the page with the payment result information.

Processing of the payment may also require performing additional steps. If the specified payment information is invalid or any of the fields is left empty, the customer can be notified via a message set up on the web service side and shown on the same page where the payment form is embedded. If the 3‑D Secure authentication with the challenge flow is required to process the payment, the customer is redirected to the ACS page. If, due to the payment method specifics, submitting additional customer information is required (their billing address, for example), this information should be collected before the microframe solution is invoked and should be specified in the initial request to open the solution.

Setup

To implement the ecommpay microframe solution:

1. Set up data signing using one of the specialised SDKs in the web service backend.
2. Set up the checkout page where the microframe is to be invoked. Use the following links to add ecommpay CSS and JavaScript libraries:
   • https://paymentpage.ecommpay.com/shared/merchant.css
   • https://paymentpage.ecommpay.com/shared/merchant.js
3. Make sure that all necessary parameters are collected before the ecommpay widget (EPayWidget) is run to invoke the microframe.

   The minimum set of required microframe invocation parameters to be used in the web service integration project is presented below. The comprehensive list of parameters used in requests for opening Payment Page can be found in this article.

   Keep in mind that you can use both the HTTP POST and GET methods for sending requests when you work with the widget.

There are two methods that can be used to run the EPayWidget to invoke the microframe:

• bind (EPayWidget.bind)—if the payment form should be opened with a button click.
• run (EPayWidget.run)—if the payment form should be opened upon any other event in the user interface.

Once the microframe has been invoked, there are two ways how you can set up the submission of the payment form to initialise the payment. You can:

• Set up sending the epframe.embedded_mode.submit message to the microframe.
• Use the data-epwidget="ep-run-transaction" attribute for your payment button.

As a rule, the payment form is submitted when the customer clicks the Pay button in the invoked microframe, but you can configure it differently, if need be.

The following are the steps to prepare the code to invoke the microframe.

1. Create a widget container:

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

2. On the server side of the web service, create an object containing parameters for opening the payment form (below) and signature (to simplify the process, use SDKs for data signing). The list of parameters must include the target_element with the identifier of the widget container.
3. Pass this object to the client side.
4. Depending on your needs, you can either add the microframe invocation event handler or set up processing of the epframe.loaded messages (the detailed description of the communication between the web service and the microframe with the use of the postMessage method can be found below).

   configObj.onLoaded = () => {console.log('Microframe is loaded')};

5. Set up sending the epframe.embedded_mode.submit message to the microframe to submit the payment form, or use the data-epwidget="ep-run-transaction" attribute for your payment button.
6. If you need to open the payment form by the button click, then use the EPayWidget.bind() method and specify the identifier of the button.

   EPayWidget.bind('showMicroframeButtonId', configObj)

   Otherwise, use the EPayWidget.run method to invoke the microframe.

   EPayWidget.run(configObj)

The following is an example of the HTML code for the web service frontend that runs the widget using merchant.js script.

<html>
<head>
    <!-- Adding ecommpay libraries -->
    <link rel="stylesheet" href="https://paymentpage.ecommpay.com/shared/merchant.css">
    <script src="https://paymentpage.ecommpay.com/shared/merchant.js"></script>
    <!-- Other parts -->
</head>
<body>
<!-- HTML Web page code to add the Payment Page widget -->
<div class="container">
    <div id="widget-container"></div>
</div>
<!-- This button invokes microframe. --> 
<!-- It is relevant if you have a 2-step checkout page, for example -->
<button id="showMicroframeButtonId">Invoke microframe</button>
<!-- This button automatically submits the microframe when a customer clicks the button. --> 
<!-- Alternatively, you can send a postmessage to submit the microframe -->
<button data-epwidget="ep-run-transaction">Pay</button>
<!-- JS command to open Payment Page -->
<script type="text/javascript">
    // This object with parameters is received from the backend using SDK
    const configObj = {
        // identifier of the element
        target_element: 'widget-container',
        // payment parameters
        project_id: 12345,
        payment_id: '18641868',
        payment_amount: 3500,
        payment_currency: 'GBP',
        customer_id: '17008',
        customer_first_name: 'SAMUEL',
        customer_last_name: 'JOHNSON',
        customer_email: 's.johnson@mail.com',
        customer_phone: '441223262463',
        billing_country: 'GB',
        billing_postal: 'BS23 1XF',
        billing_city: 'Weston-super-Mare',
        billing_address: 'Walliscote Road',
        force_payment_method: 'card',
        redirect_success_url: 'https://www.ilovebigbooks.com/',
        signature: 'YWb6Z20ByxpQ30hfTI'
    };
    // Add event handler functions that can be used in UX/UI interaction
    configObj.onLoaded = () => { console.log('Microframe is loaded') };
    configObj.onValidationStatusChange = (data) => {
        handleErrors(data)
        // data object example:
        // {"pan": "Card number required.", "month_year": "Expiry date required.",
        // "cvv": "CVV2/CVC2 required.", "card_holder": "Cardholder name required."}
    };
    configObj.onReceivedServerErrors = (data) => { handleErrors(data) };

    // Use it to invoke the microframe by the button click
    EPayWidget.bind('showMicroframeButtonId', configObj, 'POST');
    // Or use it to invoke the microframe immediately
    EPayWidget.run(configObj, 'POST');
    <!-- Other parts -->
</script>
</body>
</html>

If necessary, you can customise the appearance of the payment form using the Payment Page Designer in Dashboard. You can modify the colour of different elements and the texts on the form (for a detailed guide on how to work with the Payment Page Designer, go to Customisation).

Once you set up the solution, you can test payment processing using test cards details (use 4000 0000 0000 0077 for a purchase to be processed and 4111 1111 1111 1111 for a purchase to be declined) and proceed to taking real payments using the microframe.

Workflow

By default, using the ecommpay microframe solution allows processing one-step purchases. This type of checkout works right out-of-the-box and requires no additional setup. The communication between the ecommpay microframe and the merchant web service is handled with the use of the postMessage method. The event handler functions necessary to establish the interaction are included in the merchant.js library and are enough to ensure essential communication. The messages sent from the microframe to the merchant web service are intended more for informational purposes rather than functional use: that is, the way they are utilised on the web service side is at the discretion of the merchant. However, the epframe.embedded_mode.submit message sent from the merchant web service to the microframe has functional use and is necessary for ensuring proper initiation of payment processing. The description of messages and the events that trigger them can be found in the table below.

If the payment request is submitted and no additional steps are required for payment processing, the payment status information is sent in a message from the microframe to the checkout page and directly to the web service backend (via callbacks) after the payment is completed. If the 3‑D Secure authentication is required, the customer is redirected to the 3‑D Secure authentication page automatically.

The following is a step-by-step description of the payment flow with the communication between the web service and the ecommpay microframe with the use of the postMessage method:

1. When the customer is ready to pay, invoke EPayWidget.run. Once the microframe loads, it sends an epframe.loaded message (to signify that the contents of the microframe is loaded).

   {message: 'epframe.loaded', data: {…}, guid: '6372-eefb-8223-2127'}
   data: {width: 390, height: 150}
   guid: "6372-eefb-8223-2127"
   message: "epframe.loaded"

2. Once the customer confirms the payment, the merchant web service sends the epframe.embedded_mode.submit message to the microframe to submit the payment form.

   {message: 'epframe.embedded_mode.submit', from_another_domain: true}
   from_another_domain: true
   guid: "6372-eefb-8423-2127"
   message: "epframe.embedded_mode.submit"

3. The microframe responds with the result of the accuracy check in an epframe.validation.status.change postMessage.

   {message: 'epframe.validation.status.change', data: {…}, guid: '6372-eefb-8223-2127'} 
   data: 
       pan: "Card number required." 
       month_year: "Expiry date required."
       cvv: "CVV2/CVC2 required."     
   guid: "6372-eefb-8423-2127"
   message: "'epframe.validation.status.change"

4. If there is insufficient payment data, the missing data can be submitted via the epframe.embedded_mode.submit postMessage.
5. If the customer is redirected to an ACS page for 3‑D Secure authentication, once all actions on the redirection page are completed, the customer is redirected to one of the URLs passed as a value of the redirect_success_url or redirect_fail_url parameter depending on the final payment status.
6. Whenever the microframe receives a callback indicating the final payment status, it sends one of the following messages containing the payment status:
   • [epframe.card.verify.success]
   • [epframe.card.verify.fail]
   • [epframe.payment.success]
   • [epframe.payment.fail]

   {message: 'epframe.payment.success', data: {…}, guid: '6372-eefb-8223-2127'}
   data: AuthCode: "563253"
   account: {number: '400000******0077', type: 'visa', card_holder: 'SAMUEL JOHNSON', expiry_month: '12', expiry_year: '2025'}
   company: {id: 1, title: 'CosmoCompany'}
   customer: {id: 'customer_110'}
   description: ""
   general: {project_id: 75721, payment_id: 'PAYMENT_298893', signature: 'hZBDMkWFiFwCcmu4niWZYk000EMl6pvvx9/RRD8Gacj4EtudojHjBV7JvljzESaeo3cI9KyQ0D/4qyDMAtw=='}
   operations: [{…}]
   payment: {method: 'card', date: '2023-08-22T06:28:36+0000', result_code: '0', result_message: 'Success', status: 'success', …}
   received_at: 1692685717.532238
   request_id: "821d43d8b78a198bf806b2c468ae122efd7aa8ad-6f45471da9afb1659cf0d7dbe9c91c4f938db452-00000001"
   return_url: "http://success.url.com/process/complete-redirect/k6i81qsnmh40o9b8i4o9147kvr/8d7b07b3f4241aff"
   rrn: "000047769105"
   status: "success"
   sum_real: {amount: 10000, currency: 'USD'}
   sum_request: {amount: 10000, currency: 'USD'}
   transaction: {id: 49, date: '2023-08-22T06:28:36+0000', type: 'purchase'}
   guid: "6372-eefb-8223-2127"
   message: "epframe.payment.success"

In addition to receiving messages with the payment status, you can monitor up-to-date payment processing information at the API level—through callbacks sent automatically according to a set of specified conditions (to learn more, see Callbacks) and responses to payment status requests (to learn more, see Checking current payment information). You can also view consolidated payment processing data in the Dashboard interface.

Message handling

The following is an example of the JavaScript code that can be used to work with the postMessage method.

function handleErrors(errors) {
    if (!Object.values(errors).length) {
        $errorsContainer.classList.add('invisible')
        return;
    }

    clearErrorContainer()
    $errorsContainer.classList.remove('invisible')

    Object.values(errors).forEach((item) => {
        let li = document.createElement('li')
        li.textContent = item
        $errorsContainer.appendChild(li)
    })
}

function clearErrorContainer() {
    $errorsContainer.innerHTML = '';
};

loader.hide(); iframe.show()

var message = {"message":"epframe.embedded_mode.submit"};
message.from_another_domain = true;
window.postMessage(JSON.stringify(message))

(data) => {var errors = [];
jQuery.each(data.data, function( key, value ) {errors.push(value);});}

{const redirect_success_url = "https://ur_success_url.com";
window.location.replace(redirect_success_url);}

{const redirect_fail_url = "https://ur_failed_url.com";
window.location.replace(redirect_fail_url);}

{const redirect_success_url = "https://ur_success_url.com";
window.location.replace(redirect_success_url);}

{const redirect_fail_url = "https://ur_failed_url.com";
window.location.replace(redirect_fail_url);}

Required parameters

This is a common list of parameters necessary for using the solution. It can sometimes be expanded depending on the specifics of the merchant's project. Contact your account manager for more details.

In addition, keep in mind that requests for card payments must contain either the customer_email or the customer_phone parameter. It is also recommended that for 3‑D Secure you pass the information about the customer's billing address using the following parameters.