Handling customer behaviour events on Payment Page

Payment Page can synchronously post to the web page the information about the customer actions on the page and allows you implement your own handler functions to act on specific events. Listed below are some customer actions you can handle by using custom handler functions:

  • Tab selection
  • Payment method selection
  • Selection of any option button, for example amount, saving payment account details
  • Changing values for any input field, for instance: accounts, phone numbers, prefixes, except confidential information
  • Request for payment or payout
Note: This feature is intended for retrieving information about page events and customer actions on it, but not about payment and operation statuses. Information about statuses should be obtained from callbacks.

The names and code of handler functions are specified in the widget invocation string. The following sections describe in more details how to pass implementations of event handler functions when invoking the widget.

Prerequisites

To capture customer events on your web page and handle them, you need to build Payment Page into your project web page. You also need to reference the following libraries in the page header:
<link rel="stylesheet" href="https://paymentpage.ecommpay.com/shared/merchant.css" />
<script type="text/javascript" src="https://paymentpage.ecommpay.com/shared/merchant.js"></script>

No further environment configuring is required.

Implementing handler functions

customer actions on the web page trigger events, and you can handle this events by using you custom handler functions. Once an event is fired, the runtime attempts to invoke the corresponding custom handler function, provided the code of the function was included in the widget invocation string. Here is an example of widget invocation string with the onResize handle function code included in the string:

EPayWidget.run({    
    payment_id: 'X03936',
    payment_amount: 2035,
    payment_currency: 'USD',
    project_id: 22,
    signature: 'YWb6Z20ByxpQ30hfTIjaCCsVIwVynXV',
 
    onResize: function (data) {
        site.resize({
            myWidth: data.width,
            myHeight: data.high
  }); 
 },
}, 'POST');
Note: The code of an event handler functions must be included in the widget invocation string.
In this code example, the code of the handler function which will be invoked each time the resize event is fired is highlighted with bold. Here is more detailed information about components of the onResize handler function:
  • onResize This is the name of the handler function that includes the event it handles (resize). The handler function code is shown in italic text. This code is automatically executed once the resize event fires.
  • data This is a JavaScript object which contains the data which is specific to the current event. In this example the data object contains two keys with values: the new width and the new height of the window. These values are assigned to the myWidth and myHight variables. For more information about the data the data objects contain depending on the event see the table further in this section.

Depending on the event, the data object may contain different data. For example, when customer selects a payment method on the page, the data object contains name, type, and code of the selected payment method. You can use this data in your implementation of the onPaymentMethodSelect handler function. Here is an example of the handler function implementation that sets the newPaymentsMethod variable to the name of the payment method the customer has selected on your web page:

EPayWidget.run({    
    payment_id: 'X03936',
    payment_amount: 2035,
    payment_currency: 'USD',
    project_id: 22,
    signature: 'YWb6Z20ByxpQ30hfTIjaCCsVIwVynXV',
   
    onPaymentMethodSelect: function (data) {
        site.resize({
            newPaymentMethod: data.name,
  });  
 },
}, 'POST');

Note that handler functions are not directly incorporated in the libraries you include into your web page but rather you include the code of these functions into the widget invocation string. In other words, to ensure that you handler function is called when the required event is fired, you need to include into the widget invocation string both the widget invocation code and the code of your handler function. In your implementation of a handler function, you can use the data passed in the data object that contains information relevant to the current event.

The following table lists the supported event handler functions along with descriptions of events and sample data contained in the data object.

Table 1. Event handler functions and sample data conveyed inside the data object
Name of event handler function Event description Sample data inside the data object
onResize Event is fired when document size changes within iframe inside widget
ShowHide
{
"width":1080,
"height":660
}
onPaymentMethodSelect Event is fired when a payment method is selected
ShowHide
{
"name":"Bank cards",
"payment_method_type":"1",
"payment_method_code":"card"
}
onLoaded Event is fired when the widget content download is finished
ShowHide
{
"width":100,
"height":100
}
onPaymentSuccess Event is fired on successful payment
ShowHide
{
"sum_request":{
    "amount":99,
    "currency":"EUR"
},
"request_id":"f68d1288e3e37b0ded8763d94588dd2915c5dfadb5024",
"transaction":{
    "id":2000000004,
    "date":"2019-02-28T11:14:49+0000",
    "type":"purchase"
},
"payment":{
    "method":"card",
    "date":"2019-02-28T11:14:49+0000",
    "result_code":"0",
    "result_message":"Success",
    "status":"success",
    "is_new_attempts_available":false,
    "attempts_timeout":0,
    "id":"EP394c-56d4",
    "provider_id":3
},
"sum_real":{
    "amount":99,
    "currency":"EUR"
},
"customer":{
    "id":"1"
},
"status":"success",
"account":{
    "number":"555555******4444",
    "type":"mastercard",
    "card_holder":"FG FG",
    "id":37489,
    "expiry_month":"07",
    "expiry_year":"2021"
},
"rrn":"000047769105",
"auth_code":"563253",
"general":{
    "project_id":140,
    "payment_id":"EP394c-56d4",
    "signature":"EjYXLJpvDBPtbwQSQ0ukti9BY1m73+
             0SrRCCQGB5QXHzxTu7Fory/XQaZTtNz2Vm33AA=="
},
"description":"",
"operations":[{
    "id":2000000004,    
    "type":"sale",
    "status":"success",
    "date":"2019-02-28T11:14:49+0000",
    "processing_time":"2019-02-28T11:14:49+0000",
    "sum":{
        "amount":99,
        "currency":"EUR"
        },
    "code":"0",
    "message":"Success"
}
],
"return_url":"http://pp/process/complete-redirect?0ebeqgdcgbsj3d278b46"
}
onPaymentFail Event is fired when payment fails
ShowHide
{
"sum_request":{
    "amount":99,
    "currency":"EUR"
},
"request_id":"f68d1288e3e37b0ded8763d94588dd2915c5dfadb5024",
"transaction":{
    "id":2000000004,
    "date":"2019-02-28T11:14:49+0000",
    "type":"purchase"
},
"payment":{
    "method":"card",
    "date":"2019-02-28T11:14:49+0000",
    "result_code":"10106",
    "result_message":"expired",
    "status":"decline",
    "is_new_attempts_available":false,
    "attempts_timeout":0,
    "id":"EP39456d4",
    "provider_id":3
},
"sum_real":{
    "amount":99,
    "currency":"EUR"
},
"customer":{
    "id":"1"
},
"status":"success",
"account":{
    "number":"555555******4444",
    "type":"mastercard",
    "card_holder":"FG FG",
    "id":37489,
    "expiry_month":"07",
    "expiry_year":"2021"
},
"rrn":"000047769105",
"auth_code":"563253",
"general":{
    "project_id":140,
    "payment_id":"EP394c-56d4",
    "signature":"EjYXLJpvDBPtbwQSQ0ukti9BY1m73+0Sr
                   RCCQGB5QXHzxTu7Fory/XQaZTtNz2Vm33AA=="
},
"description":"",
"operations":[{
    "id":2000000004,    
    "type":"sale",
    "status":"decline",
    "date":"2019-02-28T11:14:49+0000",
    "processing_time":null,
    "sum":{
        "amount":99,
        "currency":"EUR"
        },
    "code":"10106",    
    "message":"expired"
}
],
"return_url":"http://pp/process/complete-redirect?0ebeqgdcgbsj3d278b46"
}
onExit Event is fired when customer closes widget, no data included -
onPaymentSent Event is fired when sending payment data by clicking the Pay button, no data included -
onWalletSelect Event is fired when customer selects saved payment account
ShowHide
{
"code":"card",
"id":"37489",
"pan":"555555******4444",
"month":"7","year":"2021",
"type":"mastercard",
"pan_first6":"555555",
"pan_last4":"4444",
"expired":"0",
"cvv_required":"1",
"holder":"FG FG",
"token":"503596ab84feeef727745344e7874f53363fab1f67166776dde10813202341ce",
"field_values":{
    "country":"",
    "phone":"",
    "email":"",
    "card[expiry]":"07/21",
    "card[holder]":"FG FG",
    "card[type]":"mastercard",
    "card[country]":"RU",
    "card[product_name]":"MLF - MasterCard Agro",
    "card[bank_name]":"Super Test Bank XXX",
    "recurring_enable":"0"
}
}
onWalletRemove Event is fired when the saved payment account is deleted
ShowHide
{
"code":"card",
"id":"37490",
"pan":"555555******4444",
"month":"4","year":"2020",
"type":"mastercard",
"pan_first6":"555555",
"pan_last4":"4444",
"expired":"0",
"cvv_required":"1",
"holder":"FG FG",
"token":"3c45c90d447aea21bd391e1f19453d94253ff9651f8c3bd8261b25e0c48a5a85",
"field_values":{
    "country":"",
    "phone":"",
    "email":"",
    "card[expiry]":"07/21",
    "card[holder]":"FG FG",
    "card[type]":"mastercard",
    "card[country]":"RU",
    "card[product_name]":"MLF - MasterCard Agro",
    "card[bank_name]":"Super Test Bank XXX",
    "recurring_enable":"0"
}
}
onTokenizeSuccess Event is fired when a token is generated for a bank card
ShowHide
{
"general":{
    "project_id":140,
    "customer_id":"1",
    "signature":"Lqj0B3ue5tG33F9NnfEs0RhjvU9AwkofHFKGQVq
                   kVbjXHXNZj3x1o/5q7r8/rY+O5MC64iW3k77tg=="
    },
"request":{
    "id":"a748130e0350895d71bd8154342e0c261e30e086-5583739b323907d9d61a5ffbf4118afeec695552",
    "action":"tokenize",
    "status":"success"
},
"token":"9547420d22e411ae19aeb94565079542031bb736dc8f5daeddf13a3c26758217",
"customer":{
    "ip_address":"192.168.15.1",
    "id":"1"
},
"token_created_at":"2019-02-28T11:25:30+0000",
"token_status":"active"
}
onFailLoading Event is fired when an error occurs while widget loading
ShowHide
{
"message": "Application error",
"config":

{ "css_modal_wrap": "standart", "customer_id": "Jablonskiy", "frame_mode": "iframe", "payment_amount": "1000", "payment_currency": "USD", "payment_id": "EP753c-bfb7", "project_id": "666", "signature": "qwerty", "target_element": "iframe-holder" }
}
onPaymentSubmitResult Event is fired when a payment request is registered in the payment platform
ShowHide

{
 "request_id": "bc6195a61ac65e1b08b039e7a47bc2d07750d454-5a03248280c624d2afe2045c4e954aca63ceee2f-00002836"
}
onShowClarificationPage Event is fired when a page for entering additional payment information opens -
onSubmitClarificationForm Event is fired when a customer submits the additional payment information -