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.

Restriction: The microframe payment solution is currently supported for card payments. If you need to work with alternative payment methods, you can explore other options of integrating with the payment platform (see the list of guides to determine what options cater to the specifics of your business and your web service best).

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 phone number, 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.

Figure: Payment scenario steps with the microframe solution (where the fields to enter card data are part of the microframe solution while the button to submit payment and the error message are part of the merchant web service)

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:
  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. Along with that, you can pass a JavaScript object with the list of parameters including the signature or with the baseUrl parameter that contains the absolute (full) URL for opening Payment Page.

The following is an example of the HTML code for the web service frontend that uses the script to run the widget via an HTTP POST method.
<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>
  <script type="text/javascript">var EP_HOST = 'https://paymentpage.ecommpay.com';</script>
<!-- Other parts -->
</head>
<body>
  <!-- HTML Web page code to add the Payment Page widget -->
  <div class="container">
      <div id="widget-container"></div>
  </div>
  <!-- JS command to open Payment Page -->
  <script type="text/javascript">
      EPayWidget.run({ 
                       // 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',
                       force_payment_method: 'card',
                       redirect_success_url: 'https://www.ilovebigbooks.com/',
                       signature: 'YWb6Z20ByxpQ30hfTI',
                       // event handler functions that can be used in UX/UI interaction
                       onValidationStatusChange: function(data) {
                           handleErrors(data)
                       },
                       onReceivedServerErrors: function(data) {
                           handleErrors(data)
                       }
      },'POST');
 <!-- Other parts -->
 </script>
</body>
</html>

The following example of code to run the widget illustrates the structure of the request sent via an HTTP GET method. This URL can be generated with the help of SDKs for data signing.

EPayWidget.run({baseUrl:'https://paymentpage.ecommpay.com/payment?project_id=42&customer_id=123&payment_id=4438...'})

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

    Figure: Message example

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

  2. 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.
  3. 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]

    Figure: Message example

    {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 = '';
};

This table contains information about messages sent from the ecommpay microframe to the web service.

Message Description and example

epframe.loaded
inbound

 Event: microframe is loaded
loader.hide(); iframe.show()

epframe.card.verify.success
inbound

 Event: the card verification is complete
{const redirect_success_url = "https://ur_success_url.com";
window.location.replace(redirect_success_url);}

epframe.card.verify.fail
inbound

 Event: the card verification has failed
{const redirect_fail_url = "https://ur_failed_url.com";
window.location.replace(redirect_fail_url);}

epframe.payment.success
inbound

 Event: the final status is delivered, the payment is complete
{const redirect_success_url = "https://ur_success_url.com";
window.location.replace(redirect_success_url);}

epframe.payment.fail
inbound

 Event: the final status is delivered, the payment is declined
{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.

Note: Refer to Parameters for opening payment form for the full list of all the supported parameters.
Parameter Description

project_id
integer

Project identifier assigned by ecommpay at the stage of integration.
Example: 35

payment_id
string

Payment identifier unique within the merchant's project.
Example: payment_536231.

signature
string

Request signature generated after all required parameters have been specified (for more information, see Signature generation and verification)
Example: YWb6Z20ByxpQ30hfTI

payment_amount
integer

Payment amount in the smallest currency units.
Example: 1905 for 19.05 and 190500 for 1905

payment_currency
string

Payment currency code in the ISO 4217 alpha-3 format.
Example: EUR

customer_id
string

Identifier of the customer within the merchant's project.
Example: customer313

customer_first_name
string

First name of the customer.
Example: Samuel

customer_last_name
string

Last name of the customer.
Example: Johnson

customer_email
string

Email of the customer.
Example: test@mail.com

payment_methods_options
string

A string containing the specific display options for the payment page opening or the payment method selection. Required for hiding the Pay button of ecommpay.
The exact value must be
{"additional_data":{"embeddedMode":true}}

redirect_success_url
string

The URL for the customer to be redirected to when the payment has been completed.
Example: https://your_success_url.com

redirect_fail_url
string

The URL for the customer to be redirected to when the payment is declined.
Example: https://your_fail_url.com

avs_post_code
string

Customer's postal code passed in case of the AVS check. Required for customers with a UK issued card (can be submitted in a clarification message).
Example: WS13 6LG

avs_street_address
string

Customer's street address passed in case of the AVS check. Required for customers with a UK issued card (can be submitted in a clarification message).
Example: Breadmarket Street

force_payment_method
string

Identifier of the payment method that is opened to customers without an option to select another one.
The exact value must be card