Interaction concepts

The Payment Page payment form supports multiple usage scenarios to perform payments and other target activities. For instance, you can call Payment Page API, use an ecommpay library, or open the form either in a new browser tab or inside the web service page. Different Payment Page usage scenarios are covered in the Overview section while the current section describes the order and technical aspects of integration by using Payment Page.

Disregarding any technical solution you may use, the basic requirements for using Payment Page include the following:

• The payment form can be invoked by using HTTP version 1.1 or higher and TLS version 1.2 or higher.
• All the request and callback data must use UTF-8 encoding.
• The requests should be sent to the following basic address: https://paymentpage.ecommpay.com.
• The following browsers are supported: Chrome, Safari, Opera, Firefox, Microsoft Edge, QQ, MIUI, Samsung Internet, 360 and some others.

This section describes integration options, operation workflows, and request formats. For more information regarding Payment Page operation in various environments, refer to ecommpay support service.

To integrate with the ecommpay payment platform by using Payment Page, merchants should do the following:

1. Address the following organisational issues of interaction with ecommpay:

   1. If the company has not obtained the project identifier or a secret key from ecommpay, submit the application for connecting to the ecommpay payment platform.
   2. For processing payments made with the Visa and Mastercard cards, provide the ecommpay key account manager with the documents of compliance with the PCI DSS requirements. The following documents are required:
      • From all merchants—the ASV scan report.

        ASV scanning must be performed by the authorised scanning service providers (PCI SSC Approved Scanning Vendor, ASV) quarterly and after every significant change in the network infrastructure. The ecommpay merchants can select these providers on their own and, if relevant, involve a provider that is in partnership with ecommpay. To have the scanning services via the partner organised, contact the key account manager.

      • From the merchants processing over 6 million operations annually (Level 1)—the Attestation of Compliance, AOC.
      • From the merchants processing to 6 million operations annually (Levels 2, 3, and 4)—the Self-Assessment Questionnaire, SAQ.

        With questions on completing the questionnaire, contact the ecommpay key account manager.

   3. If the payment form customisation is needed, contact the ecommpay key account manager to discuss the usage of the design builder or other customisation means.
   4. Coordinate the procedures of integrating with the payment platform, testing (including testing various payment methods), and launching the functionality with the ecommpay technical support specialists.
2. Complete preliminary technical tasks by using either your in-house resources or the specialised components offered by ecommpay:
   1. If customising the payment form with the use of the design builder is relevant, get the access to the Dashboard user account with the corresponding rights via the technical support specialists and configure the payment form design. If another customisation means has been discussed and accepted, address the corresponding issues in cooperation with the key account manager and the technical support specialists.
   2. Install and link all the necessary libraries and/or plugins.
   3. On the client side of the web service, implement collecting the parameters necessary for performing the required actions; also implement forming and sending requests for opening Payment Page.
   4. On the server side of the web service, implement signature generation and callback response processing.

3. Test the required actions and launch the integration solution in coordination with the ecommpay technical support specialists.

   Upon testing and monitoring, when the required actions are performed correctly, the ecommpay technical support specialists interact with the web service in the full-time support mode.

With any questions about working via Payment Page, contact the ecommpay key account manager and the technical support specialists (support@ecommpay.com).

Every target activity on Payment Page requires interaction of three sides: the customer, your web service, and Payment Page. The interaction proceeds as follows:

• Interaction between the web service and Payment Page uses HTTP messages and follows the “request-response” model in which client part of the web service issues requests while Payment Page synchronously responds to the web service back end and asynchronous responses to the web service back end. In most cases, Payment Page responds with callbacks that contain processing result; though in some cases, Payment Page may respond with intermediate callbacks, for example when customer attempts to enter data more than once. Also, you web service may listen to events fired by Payment Page.
• Interaction between the customer and Payment Page is based on payment form GUI and under the hood, it is implemented as “request-response” exchange of HTTP messages between customer's browser and Payment Page.

Overall interaction model is shown on the following figure.

Overview

Before you start using Payment Page, you need to implement the following functionality in your web service:

• Collection of payment parameters
• Signature generation
• Submission of Payment Page invocation requests
• Processing callbacks
• Acknowledgement of callbacks reception

You can either develop your own custom solution or use the components ecommpay offer which include: JavaScript library, specialised SDK for numerous languages, and plug-ins for most popular CMS. The ecommpay components make integration much easier and allow you to minimise or even eliminate the need for custom development.

The following table describes functionality supported by different components offered by ecommpay.

The following section covers various aspects of setting up your web service by using custom solution or specialised components offered by ecommpay.

Custom solution

If you choose to set up your web service interaction with Payment Page by using you own custom solution, you need to implement all the functionality both on front end and back end of you web service.

1. On the web service front end:
   • Implement a web page for collecting data required to invoke the payment form. The minimum required data set includes project ID, payment ID, customer ID, and payment amount and currency.

   • If you intend to open Payment Page in modal window or in an iframe, you need to add link to CSS stylesheet (https://paymentpage.ecommpay.com/shared/merchant.css) to your HTML page.

     <head>
     ...
     <!-- Linking CSS stylesheet -->
     <link rel="stylesheet" href="https://paymentpage.ecommpay.com/shared/merchant.css" />
     ...
     </head>

     This stylesheet is required for correct rendering of the payment form. If you choose to open Payment Page in a separate tab, you will not need to link this stylesheet.

   • If you choose to open Payment Page in a modal window, you can define CSS styles to customise look and feel of your modal window to comply with your corporate design. If you choose to open Payment Page in an iframe or in a separate tab, you cannot customise design by using the CSS styles.

   • Implement submission of collected data to the back end and implement accepting and processing responses from the back end.
   • Implement invoking Payment Page by using the selected method: in a separate tab, in a modal window, or in an iframe.
   • If you open Payment Page in a modal window or in an iframe, you can handle some events in by implementing the corresponding event handler functions. For more information, see Handling customer behaviour events on Payment Page.
2. On the web service back end:
   • Implement accepting and processing responses from the front end.
   • Implement request signature generation.
   • Implement submission of signed parameters set to the front end.
   • Implement accepting—including signature verification and submission of acknowledgements—and processing callbacks from Payment Page.

JavaScript library

The JavaScript library is linked to your web service front end and allows you to open Payment Page in a modal window or in an iframe. The library also allows you to handle customer behaviour events on Payment Page. For more information, see Handling customer behaviour events on Payment Page.

When using the JavaScript library, you can develop your own custom solution or use web service SDK. You are required to make the following on the web service front end:

• Implement a web page for collecting data required to invoke the payment form. The minimum required data set includes project ID, payment ID, customer ID, and payment amount and currency.

• Add link to CSS stylesheet (https://paymentpage.ecommpay.com/shared/merchant.css) and the JavaScript library (https://paymentpage.ecommpay.com/shared/merchant.js) to your HTML page.

  <head>
  ...
  <!-- Linking CSS stylesheet -->
  <link rel="stylesheet" href="https://paymentpage.ecommpay.com/shared/merchant.css" /> 
  <!-- Linking JavaScript library -->
  <script type="text/javascript" src="https://paymentpage.ecommpay.com/shared/merchant.js">
  </script>
  ...
  </head>

• If you choose to open Payment Page in a modal window, you can define CSS styles to customise look and feel of your modal window to comply with your corporate design. If you choose to open Payment Page in an iframe or in a separate tab, you cannot customise design by using the CSS styles.

• Implement submission of collected data to the back end and implement accepting and processing responses from the back end.
• Implement invoking Payment Page by clicking a button or command using the selected method: in a modal window and/or in an iframe. In this case, invocation is implemented through the EPayWidget JavaScript object.
• If you open Payment Page in a modal window or in an iframe, you can handle some events in by implementing the corresponding event handler functions. For more information, see Handling customer behaviour events on Payment Page.

Web service SDK

After you build these SDKs in your web service back end, you will be able to generate signatures for requests and process callbacks. When using web service SDK, you can develop your own custom solution and use mobile SDK and the JavaScript library. You are required to make the following on the web service back end:

• Implement accepting and processing responses from the front end.
• Implement request signature generation by using the SDK libraries.
• Implement submission of signed parameters set to the front end.
• Implement accepting—including signature verification and submission of acknowledgements—and processing callbacks from Payment Page by using web service SDK.

For more information about linking and using this component in all available SDKs, see Integration using SDK.

Mobile SDK

The mobile SDK are build in mobile client apps and allow them to interact with the payment form adapted for mobile interfaces. When using mobile SDK, you can develop your own custom solution and use web service SDK. You are required to make the following on the web service front end:

• Implement a web page for collecting data required to invoke the payment form. The minimum required data set includes project ID, payment ID, customer ID, and payment amount and currency.
• Implement other functionality by using the SDK libraries.

For more information about linking and using all available SDKs, see Integration using SDK.

Using CMS Plug-ins

CMS plug-ins are linked by using administration interface of the corresponding CMS and provide the complete functionality for using Payment Page. If you choose to use a CMS plug-in, custom development is not required.

For information on how to use CMS Plug-ins for web services for different CMS, see Integration using plug-ins.

The interaction between your web service and Payment Page begins with issuing a request to open Payment Page to perform specific target action. After the payment platform receives a request, it does the following:

• After the payment platform receives a request, it checks whether all the necessary parameters are available in the request and the signature is correct.
  • If the request is correct, the request processing starts and the corresponding acknowledgement is sent out.
  • If the payment platform encounters errors, the request handling is stopped and the corresponding error message is displayed to the customer. In this situation, no callback is submitted to the web service.
• On the request processing stage, the payment platform prepares Payment Page in accordance with project settings and request parameters. Then, the Payment Page interacts with the customer through the payment form.
  • If the customer confirms the target activity, the request moves to the processing stage. On this stage, the payment platform registers a payment for all target activities (except for token generation) by creating a payment object.
  • If the customer does not confirm the target activity, the request is cancelled. No payment is registered and no callback is sent to the web service.
• The request processing stage involves performing all the actions to obtain the target result.
  • If the payment platform has successfully processed the request, it returns the result to the web service.
  • If the payment platform has failed to process the request, it stops request handling and returns error result to the web service.

Overview

When using Payment Page, you pass all data from web service in requests which are HTTP-messages with special structure. The data format and addressing differ depends on how you want to open the payment form.

This section describes supported methods for submitting requests to open Payment Page, data formats, and addressing.

Submission methods

Both POST and GET methods are supported for all Payment Page invocation method. The payment in no way restricts invocation method and it is up to the web service to choose Payment Page invocation method. If an HTTP request does not specify request method it defaults to GET. Though, it is recommended to use POST method because of limitations imposed by some browsers on length of address string.

The main properties of POST and GET methods are presented in the following table.

*Data size is limited by URL length.

GET /payment?payment_currency=EUR&project_id=42&payment_amount=1000&customer_id=123&payment_id=4438&signature=AE5hmtzdP0Dt7qGTg... HTTP/1.1
Host: https://paymentpage.ecommpay.com

POST /payment HTTP/1.1
Host: https://paymentpage.ecommpay.com

{
  "payment_currency": EUR,
  "project_id": 42,
  "payment_amount": 1000,
  "customer_id": 123,
  "payment_id": "4438",
  "signature": "AE5hmtzdP0Dt7qGTg..."
}  

Addressing parameters

When you plan to open Payment Page in a new tab, the Payment Page URL is created as follows:

• If you use the GET method, use Payment Page base URL as the domain name (https://paymentpage.ecommpay.com) while the relative URL consists the target URL, question sign (?) and parameter “name-value” pairs delimited by ampersand sign (&). Name and value in each “name-value” pair are separated by an equal sign (=).

  // Target URL for Payment Page
  /payment
  
  // Data string
  payment_currency=EUR&project_id=42&payment_amount=1000&customer_id=123&payment_id=4438&signature=AE5hmtzdP0Dt7qGTg%3D%3D
  
  // Complete URL
  https://paymentpage.ecommpay.com/payment?payment_currency=EUR&project_id=42&payment_amount=1000&customer_id=123&payment_id=4438&signature=AE5hmtzdP0Dt7qGTg%3D%3D

• If you use the POST method, use Payment Page base URL as the domain name (https://paymentpage.ecommpay.com) while the relative URL consists of the target URL used to initiate target activities in Payment Page. The parameters are located in request body.

You do not need to specify any URL when you open Payment Page in an iframe element or in a modal window.

Payment Page acknowledges receiving request by synchronously responding with appropriately structured HTTP response. The response may contain the following data:

• The information that request is accepted for processing. The response is sent out only if the payment platform successfully accepts the request for processing.
• An extended error description. The response is sent out, if the payment platform cannot handle the request.

The following table lists status codes along with their descriptions.

In asynchronous interaction model, the ecommpay payment platform returns callbacks with intermediate and final request processing results. From the technical point of view, callbacks are HTTP requests the payment platform sends by using POST method to the merchant web address. This section covers the structure of callbacks; for detailed information about using callbacks, see Callbacks.

Each callback from the payment platform includes the following elements (in this order):

• The start line which contains the following: the HTTP method which always is POST, the web service URL for callbacks with results (for instance, /notify/success), and the protocol and its version (HTTP/1.1).
• The header fields including Host field that contains the domain name of the web service (for instance, webservice.com).
• An empty separator line between the message header and the body.
• The message body with JSON string in the UTF-8 format with result data and the signature.

Below you will find a sample callback with payment result. JSON string is formatted for better readability.

POST /notify/success HTTP/1.1
Content-Length: 1237
User-Agent: GuzzleHttp/6.3.3 curl/7.47.0 PHP/7.0.32-0ubuntu0.16.04.1
Content-Type: application/json
Host: webservice.com

{
  "account":{
    "number":"431422******0056 ",
    "token":"1234567890",
    "type":"visa",
    "card_holder":"TEST TEST",
    "id":1234,
    "expiry_month":"**",
    "expiry_year":"****"
  },
  "customer":{
    "id":"12345",
    "phone":"***********"
  },
  "payment":{
    "date":"2019-06-07T11:38:31+0000",
    "id":"1234567890",
    "method":"card",
    "status":"success",
    "sum":{
      "amount":17500,
      "currency":"EUR"
    },
    "type":"purchase",
    "description":"Deposit to 1234567890"
  },
  "project_id":25,
  "processingDateTime":"2019-06-07T11:38:30+0000",
  "country":"GB",
  "product_name":"Visa",
  "issuer_name":"",
  "operation":{
    "id":1234567890,
    "type":"sale",
    "status":"success",
    "date":"2019-06-07T11:38:32+0000",
    "created_date":"2019-06-07T11:37:56+0000",
    "request_id":"1234567890-1234567890",
    "sum_initial":{
      "amount":17500,
      "currency":"EUR"
    },
    "sum_converted":{
      "amount":17500,
      "currency":"EUR"
    },
    "provider":{
      "id":11,
      "payment_id":"098765432",
      "date":"2019-06-07T11:38:30+0000",
      "auth_code":"",
      "endpoint_id":1
    },
    "code":"0",
    "message":"Success",
    "eci":"05"
  },
  "signature":"qwertyuioiuytrewqwertyuu123434"
}