Handling events in Payment Page
Overview
When using a payment form, you may need to monitor customer interactions with the form, so that your web service can respond to different events in a timely and efficient manner. For example, if a payment form fails to load, the customer can be provided with an appropriate explanation, or if the customer abandons the order, they can be reminded to enter payment details to complete the purchase.. With Payment Page, you can use libraries from ecommpay that support listening to events and responding to them by executing JavaScript event handlers that are defined in the requests for opening Payment Page.
With Payment Page, you can use libraries from ecommpay that support listening to events which occur in the front end of your web service and responding to them by executing JavaScript event handlers that are defined in the requests for opening Payment Page. Note that the information about events can only complement information obtained from callbacks; hence, it is not recommended that you use event handlers exclusively as a replacement for callbacks.
Use
To implement event handling within Payment Page in your web service, you only need to complete technical steps (that is, using this option does not require you to contact the ecommpay technical support for additional assistance with this matter).
Firstly, make sure to link the following libraries from ecommpay to the front end of your web service.
<link rel="stylesheet" href="https://paymentpage.ecommpay.com/shared/merchant.css" /> <script type="text/javascript" src="https://paymentpage.ecommpay.com/shared/merchant.js"></script>
Secondly, configure your web service to process the data received from triggered event handlers according to the specifics of the web service and customer scenarios. For example, you may implement functions for updating the payment status on the checkout page or for accepting payments with card tokens.
Thirdly, in each request for opening Payment Page that requires listening to interface events, define necessary event handlers from the table below in JavaScript. Event handlers must be specified in JavaScript and placed after the list of required parameters and signature. You can add any number of functions to an event handler and use the data object that contains data associated with certain events (not all event handlers support the data object).
When testing the integration with the ecommpay payment platform via Payment Page, you can log payment request identifiers in a browser console for the purpose of testing and debugging your web service and use the logged request identifiers for monitoring and analysing payment processing. The following is the example of the onPaymentSubmitResult event handler function that logs the request_id variable value to the browser console.
EPayWidget.run({
payment_id: 'payment_443',
payment_amount: 1000,
payment_currency: 'EUR',
project_id: 57123,
signature: 'YWb6Z20ByxpQ30hfTIjaCCsVIwVynXV',
onPaymentSubmitResult: async function (data) {
console.log(data.request_id);
}
}, 'POST');
The following is the example of the onResize event handler function that is executed when the page contained in an iframe is resized. Once the event occurs, the event handler is triggered and automatically updates the iframe dimensions using the data object values.
EPayWidget.run({
payment_id: 'payment_443',
payment_amount: 1000,
payment_currency: 'EUR',
project_id: 57123,
signature: 'YWb6Z20ByxpQIjaCCsVIwVynXV',
onResize: function (data) {
site.resize({
frameWidth: data.width,
frameHeight: data.height
});
}
}, 'POST');
In this example, when the onResize event handler is triggered, it updates the iframe width and height based on the frameWidth and frameHeight values from the data object.
Event handlers
Form load
onLoaded |
Triggered when Payment Page is successfully loaded (all UI elements are fully rendered and the Payment Page session is initialised according to the request parameters). When using this event handler, you can measure the payment form load speed on a customer device. {
"width":900,
"height":640
}
|
onFailLoading |
Triggered when Payment Page fails to load (the Payment Page session cannot be initialised). When using this event handler, you can check the parameters in the request for opening the payment form and then resend the request. You can reuse the same payment identifier if it is valid and has not been used within the project beforehand. {
"message": "Application error",
"config":
{
"customer_id": "1",
"frame_mode": "iframe",
"payment_amount": "1000",
"payment_currency": "EUR",
"payment_id": "payment_443",
"project_id": "57123",
"signature": "YWb6Z20ByxpQIjaCCsVIwVynXV",
"target_element": "iframe-holder"
}
}
|
Payment submission
onPaymentMethodSelect |
Triggered when a customer selects a payment method. The event is raised whenever the customer switches between payment method tabs on the form. When using this event handler, you can record which payment method the customer has selected. The data includes the payment method name, the code of the payment type ( {
"name":"Bank cards",
"payment_method_type":"1",
"payment_method_code":"card"
}
|
onWalletSelect |
Triggered when a customer selects saved payment data (a card or another payment instrument). When using this event handler, you can record which payment instrument the customer has selected (based on masked details of this payment instrument). If needed, this information can be used in your web service further on to initiate requests for payments with card tokens (details). {
"code":"card",
"id":"37489",
"pan":"541333******0019",
"month":"12",
"year":"2028",
"type":"mastercard",
"pan_first6":"541333",
"pan_last4":"0019",
"expired":"0",
"cvv_required":"1",
"holder":"JOHN SMITH",
"token":"503hyugfe7874f5utrdub1f671667hvyufxyd2341ce",
"field_values":{
"country":"",
"phone":"",
"email":"",
"card[expiry]":"12/28",
"card[holder]":"JOHN SMITH",
"card[type]":"mastercard",
"card[country]":"GB",
"card[product_name]":"Mastercard Gold",
"card[bank_name]":"Citibank",
"recurring_enable":"0"
}
}
|
onWalletRemove |
Triggered when a customer selects to delete saved payment data (a card or another payment instrument). When using this event handler, you can record which payment instrument the customer has selected to delete (based on masked details of this payment instrument). {
"code":"card",
"id":"37489",
"pan":"541333******0019",
"month":"12",
"year":"2028",
"type":"mastercard",
"pan_first6":"541333",
"pan_last4":"0019",
"expired":"0",
"cvv_required":"1",
"holder":"JOHN SMITH",
"token":"503hyugfe7874f5utrdub1f671667hvyufxyd2341ce",
"field_values":{
"country":"",
"phone":"",
"email":"",
"card[expiry]":"12/28",
"card[holder]":"JOHN SMITH",
"card[type]":"mastercard",
"card[country]":"GB",
"card[product_name]":"Mastercard Gold",
"card[bank_name]":"Citibank",
"recurring_enable":"0"
}
}
|
onPaymentSent |
Triggered when a customer confirms the payment (after all required fields in the payment form have been filled) and the preloader page is shown to the customer. When using this event handler, you can capture the time the customer spent interacting with Payment Page and then, if needed, set the time limit for working with the form (details). You can also display the message that the web service is waiting for the payment result. The |
onPaymentSubmitResult |
Triggered when the payment request is received in the ecommpay platform. When using this event handler, you can save the identifier of the request for opening Payment Page and use it to monitor the payment status in the case of incidents, for example, when there is a loss of connection with the customer's device, or callbacks from ecommpay are not delivered (learn more about callbacks).
{
"request_id": "bc4-5a032482802f-00002836"
}
|
Customer redirection
onShowClarificationPage |
Triggered when the page to submit additional information is displayed to a customer (details). When using this event handler, you can record that additional data was requested from the customer and capture the event’s timestamp. Afterwards, you can check if the customer provides the required information (use the The |
onSubmitClarificationForm |
Triggered when a customer has submitted additional information. When using this event handler, you can capture the time the customer spent providing additional data and check if the payment is completed with the The |
onRedirectIframe |
Triggered when a customer is redirected from your web service to a third-party service in the iframe element (according to the project settings and the request parameters; details). When using this event handler, you can capture the event’s timestamp when the customer is redirected to another service. Afterwards, you can check if the customer returns to Payment Page (use the The |
onResize |
Triggered when an HTML page opened in the iframe element is resized. When using this event handler, you can determine the dimensions of the HTML page where the customer is redirected to. Then you can check if the original size of the iframe element allows the page to be displayed properly in it and, if needed, resize the iframe element. {
"width":1080,
"height":660
}
|
onRedirectIframeComplete |
Triggered when a customer returns to Payment Page from a third-party service displayed in the iframe element. When using this event handler, you can capture the time the customer spent in the third-party service. The |
Payment result
onTokenizeSuccess |
Triggered when the final page is displayed with the message that the payment instrument has been saved (according to the parameters of the request for opening the payment form in the When using this event handler, you can save the created token and use it in your web service. {
"general":{
"project_id":57123,
"customer_id":"1",
"signature":"Lqj0B3ue5tG33F9NV
qkVbjXHXNZj3x1o/5q7r8/rY+O5MC64iW3k77tg=="
},
"request":{
"id":"a748130e0350895d71bd8154342e0c261e30e086-558
3739b323907d9d61a5ffbf4118afeec695552",
"action":"tokenize",
"status":"success"
},
"token":"503hyugfe7874f5utrdub1f671667hvyufxyd2341ce",
"customer":{
"ip_address":"102.129.155.0",
"id":"1"
},
"token_created_at":"2025-09-28T11:25:30+0000",
"token_status":"active"
}
|
onCardVerifySuccess |
Triggered when the final page is displayed with the message that the payment instrument has been verified (according to the parameters of the request for opening the payment form in the When using this event handler, you can record the information that the payment instrument was verified and proceed with the next steps (for example, register a card token or initiate a payout).
{
"request_id": "bbeef4d51e6ae4aadcb86d-00003158",
"transaction": {
"id": 3157000012768,
"date": "2025-10-29T14:15:02+0000",
"type": "account_verification"
},
"payment": {
"method": "card",
"date": "2025-10-29T14:15:02+0000",
"result_code": "0",
"result_message": "Success",
"status": "success",
"is_new_attempts_available": false,
"attempts_timeout": 0,
"id": "EP1120-3e48",
"cascading_with_redirect": false,
"is_cascading": false,
"remaining_refund": 0,
"split_with_redirect": false,
"method_id": 1,
"provider_id": 3
},
"sum_real": {
"amount": 0,
"currency": "GBP"
},
"customer": {
"id": "123"
},
"account": {
"number": "424242******4242",
"type": "visa",
"id": 70256633,
"card_holder": "HENRY FORD",
"expiry_month": "12",
"expiry_year": "2028"
},
"avs_result": "X",
"rrn": "000047769105",
"sum_request": {
"amount": 0,
"currency": "GBP"
},
"company": {
"id": 1,
"title": "My store"
},
"terminal": {
"method_code": "card",
"mode_code": "card_verify",
"name": "v5"
},
"cashout_data": {
"account_number": "424242******4242",
"customer_first_name": "Henry",
"customer_last_name": "Ford"
},
"general": {
"project_id": 291451,
"payment_id": "EP1120-3e48",
"signature": "fZKqrch...3//pDDJUaJ8R/7Yi5A=="
},
"description": "",
"operations": [
{
"id": 3157000013487,
"type": "account verification",
"status": "success",
"date": "2025-10-29T14:15:02+0000",
"processing_time": "2025-10-29T14:15:01+0000",
"request_id": "12a469296f-00003158",
"sum": {
"amount": 0,
"currency": "GBP"
},
"code": "0",
"message": "Success",
"provider": {
"id": 3,
"payment_id": "17616663016501"
}
}
],
"return_url": "https://mystore.com/redirect/au80n3l6krq80"
}
|
onCardVerifyFail |
Triggered when the final page is displayed with the message that the payment instrument has not been verified (according to the parameters of the request for opening the payment form in the When using this event handler, you can record the information that the payment instrument was not verified, check the reason for decline, and display it to the customer. {
"sum_request": {
"amount": 0,
"currency": "GBP"
},
"request_id": "bbeef40ef99a6cd-00003158",
"transaction": {
"id": 3157000012768,
"date": "2025-10-29T14:15:02+0000",
"type": "account_verification"
},
"payment": {
"method": "card",
"date": "2025-10-29T14:15:02+0000",
"result_code": "100",
"result_message": "General decline",
"status": "decline",
"is_new_attempts_available": false,
"attempts_timeout": 0,
"id": "EP1120-3e48",
"cascading_with_redirect": false,
"is_cascading": false,
"split_with_redirect": false,
"method_id": 1,
"provider_id": 3
},
"sum_real": {
"amount": 0,
"currency": "GBP"
},
"customer": {
"id": "123"
},
"account": {
"number": "424242******4242",
"type": "visa",
"card_holder": "HENRY FORD",
"expiry_month": "12",
"expiry_year": "2034"
},
"avs_result": "X",
"rrn": "000047769105",
"company": {
"id": 1,
"title": "My store"
},
"terminal": {
"method_code": "card",
"mode_code": "card_verify",
"name": "v5"
},
"cashout_data": {
"account_number": "424242******4242",
"customer_first_name": "Henry",
"customer_last_name": "Ford"
},
"general": {
"project_id": 291451,
"payment_id": "EP1120-3e48",
"signature": "fZPTytEOwT1Z8...BB3//pDDJUaJ8R/7Yi5A=="
},
"description": "",
"operations": [
{
"id": 3157000013487,
"type": "account verification",
"status": "decline",
"date": "2025-10-29T14:15:02+0000",
"processing_time": "2025-10-29T14:15:01+0000",
"request_id": "70-18a296f-00003158",
"sum": {
"amount": 0,
"currency": "GBP"
},
"code": "100",
"message": "General decline",
"provider": {
"id": 3,
"payment_id": "17617473016501"
}
}
],
"return_url": "https://mystore.com/redirect/baun3l6krq80"
}
|
onPaymentSuccess |
Triggered when the final page is displayed with the message that the payment is completed. When using this event handler, you can record the information that the payment was completed and proceed to process the paid order and communicate with the customer if needed. You can also capture the total time of processing the payment. {
"sum_request":{
"amount":1000,
"currency":"EUR"
},
"request_id":"f68d1288e3e37b0ded8763d94588dd2915c5dfadb5024",
"transaction":{
"id":2000000004,
"date":"2025-10-08T11:14:49+0000",
"type":"purchase"
},
"payment":{
"method":"card",
"date":"2025-10-08T11:14:49+0000",
"result_code":"0",
"result_message":"Success",
"status":"success",
"is_new_attempts_available":false,
"attempts_timeout":0,
"id":"payment_443",
"provider_id":3
},
"sum_real":{
"amount":1000,
"currency":"EUR"
},
"customer":{
"id":"1"
},
"status":"success",
"account":{
"number":"541333******0019",
"type":"mastercard",
"card_holder":"JOHN SMITH",
"id":37489,
"expiry_month":"12",
"expiry_year":"2028"
},
"rrn":"000047769105",
"auth_code":"563253",
"general":{
"project_id":57123,
"payment_id":"payment_443",
"signature":"EjYXLJpvDBPtbwQSQ0ukti9B
Y1m73+0SrRCCQGB5QXHzxTu7Fory/XQaZTtNz2Vm33AA=="
},
"description":"",
"operations":[{
"id":2000000004,
"type":"sale",
"status":"success",
"date":"2025-10-08T11:14:49+0000",
"processing_time":"2025-10-08T11:14:49+0000",
"sum":{
"amount":1000,
"currency":"EUR"
},
"code":"0",
"message":"Success"
}
],
"return_url":"http://pp/process/complete-redirect?0ebeqgdcgbsj3d278b46"
}
|
onPaymentFail |
Triggered when the final page is displayed with the message that the payment is declined. When using this event handler, you can record the information that the payment was declined, check the reason for decline, and display it to the customer. If needed, you can resend a request for opening Payment Page with a new payment identifier. {
"sum_request":{
"amount":1000,
"currency":"EUR"
},
"request_id":"f68d1288e3e37b0ded8763d94588dd2915c5dfadb5024",
"transaction":{
"id":2000000004,
"date":"2025-10-08T11:14:49+0000",
"type":"purchase"
},
"payment":{
"method":"card",
"date":"2025-10-08T11:14:49+0000",
"result_code":"10106",
"result_message":"expired",
"status":"decline",
"is_new_attempts_available":false,
"attempts_timeout":0,
"id":"payment_443",
"provider_id":3
},
"sum_real":{
"amount":1000,
"currency":"EUR"
},
"customer":{
"id":"1"
},
"status":"decline",
"account":{
"number":"541333******0019",
"type":"mastercard",
"card_holder":"JOHN SMITH",
"id":37489,
"expiry_month":"12",
"expiry_year":"2028"
},
"rrn":"000047769105",
"auth_code":"563253",
"general":{
"project_id":57123,
"payment_id":"payment_443",
"signature":"EjYXLJpvDBPtbwQSQ0ukti9BY1m73+0
SrRCCQGB5QXHzxTu7Fory/XQaZTtNz2Vm33AA=="
},
"description":"",
"operations":[{
"id":2000000004,
"type":"sale",
"status":"decline",
"date":"2025-10-08T11:14:49+0000",
"processing_time":null,
"sum":{
"amount":1000,
"currency":"EUR"
},
"code":"10106",
"message":"expired"
}
],
"return_url":"http://pp/process/complete-redirect?0ebeqgdcgbsj3d278b46"
}
|
Form close
onDestroy |
Triggered when Payment Page is closed before the payment result page is displayed. When using this event handler, you should take appropriate steps in the front end of your web service (for example, notify the customer that the payment status is being checked), check the current payment status (details), and decide on the subsequent course of action based on the payment status. The |
onExit |
Triggered when Payment Page is closed after the payment result page is displayed (according to the specified parameters). When using this event handler, you can record that the Payment Page session was completed and proceed with the next steps in your web service. You may also capture the total time the customer spent interacting with the payment form. The |