Integration using a microframe solution


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.

Notice: 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 1. 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)


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.

    Warning: Starting February 12, 2024, Visa Rules will be updated to expand the set of parameters mandatory for processing Visa card payments with the 3‑D Secure authentication. Parameters that will be required in such cases are listed below.

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.
<!-- Adding ecommpay libraries -->
  <link rel="stylesheet" href="">
  <script src=""></script>
  <script type="text/javascript">var EP_HOST = '';</script>
<!-- Other parts -->
  <!-- HTML Web page code to add the Payment Page widget -->
  <div class="container">
      <div id="widget-container"></div>
  <!-- JS command to open Payment Page -->
  <script type="text/javascript">{ 
                       // 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: '',
                       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: '',
                       signature: 'YWb6Z20ByxpQ30hfTI',
                       // event handler functions that can be used in UX/UI interaction
                       onValidationStatusChange: function(data) {
                       onReceivedServerErrors: function(data) {
 <!-- Other parts -->

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.{baseUrl:''})

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.


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 Once the microframe loads, it sends an epframe.loaded message (to signify that the contents of the microframe is loaded).

    Figure 2. 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.payment.success]
    • []
    Figure 3. 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: ""
    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) {


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

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

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

Message Description and example


Event: microframe is loaded


Event: the card verification is complete
{const redirect_success_url = "";

Event: the card verification has failed
{const redirect_fail_url = "";


Event: the final status is delivered, the payment is complete
{const redirect_success_url = "";

Event: the final status is delivered, the payment is declined
{const 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 identifier assigned by ecommpay at the stage of integration.
Example: 35


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


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


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


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


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


First name of the customer.
Example: Samuel


Last name of the customer.
Example: Johnson


Email of the customer.


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


The URL for the customer to be redirected to when the payment has been completed.


The URL for the customer to be redirected to when the payment is declined.


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


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


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

Starting February 12, 2024, requests for Visa card payments must contain the following parameters.

Parameter Description


Customer's email.


Customer's phone number.


Country of the customer's billing address in the ISO 3166-1 alpha-2 format (learn more).


Postal code of the customer's billing address.


City of the customer's billing address.


Street of the customer's billing address.