Interaction concepts

Overview

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, Internet Explorer, Yandex Browser, 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.

Integration steps

To get access to the ECommPay payment platform by using Payment Page, you need to complete the following tasks:

  1. Address the following organisational interaction issues with ECommPay:

    1. If your company has not yet obtained any ID or secret key from ECommPay, you need to submit an application for connecting to the ECommPay payment platform at https://ecommpay.com/apply-now/.
    2. You also need to have a ready copy of your PCI DSS compliance certificate or, if your company is not PCI DSS-compliant, complete Self-Assessment Questionnaire. Consult with your key account manager at ECommPay, if you need any assistance in completing Self-Assessment Questionnaire.
    3. If you need your own customised payment form design, consult with your key account manager at ECommPay to learn how to implement custom design and how to launch it.
    4. Coordinate with the ECommPay technical support the process and timing of the integration, testing, and going live. When coordinating the process of testing, you can coordinate the possibility of testing procedures involving usage of payment cards, as well as usage of some alternative payment methods.
  2. Complete preliminary technical tasks by using either your in-house resources or components offered by ECommPay:
    1. If custom payment form design is required, develop design layout in compliance with requirements described in Customisation and coordinate with technical support.
    2. Install and link all the necessary libraries and/or plugins.
    3. On web service client, implement collection of all the parameters required for requests to open Payment Page.
    4. On your web service backend, implement signature generation and callback response processing.
  3. Test and put in production mode the customised solution with help from specialists at the ECommPay technical support.

    Once testing and active monitoring phase is successfully complete, specialists from the ECommPay technical support provide regular support.

With any questions regarding usage of Payment Page on steps 2 and 3, feel free to contact ECommPay technical support service at support@ecommpay.com.

Interaction models

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.


Interaction model

Figure: Interaction workflow

  1. The customer uses the web service front end to initiate target activity.
  2. On the web service front end, the parameters required for the request to open Payment Page are collected and passed to the web service back end.
  3. The back end processed the request by doing the following:
    • Parameters check
    • Extending the parameters with the information available on the back end, if necessary
    • Signature generation for the para,eters set
  4. The back end sends response to the request to the front end.
  5. The front end receives the response, and then generates and submits request to open Payment Page to specific ECommPay URL.
  6. The request to open Payment Page enters the payment platform.
  7. The payment platform performs initial request processing which includes inspection whether all the required parameters are available and the signature is correct.
  8. Payment Page is prepared in according with project settings and request parameters.
  9. The complete payment form is displayed to the customer.
  10. The customer completes all required steps.
  11. The payment request enters the payment platform.
  12. The payment platform processes the request and forwards it to the payment environment.
  13. The payment environment processes the payment.
  14. The payment environment sends the payment processing result notification to the payment platform.
  15. The payment platform sends the payment processing result to the web service.
  16. The payment platform sends the payment processing result to Payment Page.
  17. The payment processing result is displayed to the customer on Payment Page.

Web service setup

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

  JavaScript library SDKs for web services Mobile SDKs CMS plugins
Parameter collection + +
Signature generation + +
Submitting request + + +
Processing callbacks + +
Callback acknowledgement +

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 and use web service SDK and . 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 liberalities.
  • 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 the SDK liberalities.

For more information about linking and using this component in all available SDKs, see 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 SDK.

Using CMS plugins

CMS plugin are linked by using administration interface of the corresponding CMS and provide the complete functionality for using Payment Page. If you choose to use CMS plugin, virtually no custom development will be required.

For information on how to use CMS plugins for web services for different CMS, see Integration via CMS.

Request handling

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.

Request format

Overview

When using Payment Page, you pass all the 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.

  POST GET
Security More secure because parameters are contained in request body Less secure because parameters are included in URL string
Submission of all possible parameters supported by the Payment Page API + *
Submission as a link +
Request parameters modification in address string +

*Data size is limited by URL length.

Figure: Sample GET request to open Payment Page

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

Figure: Sample POST request to open Payment Page

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 basic address as the domain name (https://paymentpage.ecommpay.com) while the relative address 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 address
    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 basic address as the domain name (https://paymentpage.ecommpay.com) while the relative address 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 modal window.

Response format

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.

Status code Description
200 OK

The request has been successfully accepted. The response body has the requested result. You can expect callbacks with intermediate or final results.

Payment form is displayed for the customer.

400 Bad Request

The request cannot be accepted because one or more required parameters are missing from the request, for example project identifier, or signature is incorrect.

Error message is displayed for the customer.

404 Not Found

Cannot process request because of incorrect value of project_id or urlBase.

Error message is displayed for the customer.

500 Internal Error

Cannot process request because of payment platform failure.

Error message is displayed for the customer.

Callback format

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.

Figure: Sample callback

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":"421234******1234",
    "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":175000,
      "currency":"RUB"
    },
    "type":"purchase",
    "description":"Deposit to 1234567890"
  },
  "project_id":25,
  "processingDateTime":"2019-06-07T11:38:30+0000",
  "country":"RU",
  "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":175000,
      "currency":"RUB"
    },
    "sum_converted":{
      "amount":175000,
      "currency":"RUB"
    },
    "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"
}