Контроль интерфейсных событий

Общая информация

При использовании любой платёжной формы может быть полезным контролировать работу пользователей с её интерфейсом — чтобы оперативно реагировать на разные события и подстраивать под них работу сервиса. Например, можно проверять загрузку формы и давать пояснения пользователю, если по каким-либо причинам она не открылась, или напоминать пользователю о необходимости указания данных для завершения оплаты, если он перешёл на другие страницы сервиса, не закончив работу с формой, и так далее. Для платёжной формы Payment Page такая функциональность поддерживается за счёт служебных библиотек от ecommpay, которые позволяют получать информацию об определённых событиях и автоматически реагировать на эти события с помощью функций по обработке, определяемых при вызове формы (JavaScript callbacks).

Для платёжной формы Payment Page такая функциональность поддерживается за счёт служебных библиотек от ecommpay, которые позволяют получать непосредственно в клиентской части веб-сервиса актуальную информацию об определённых событиях и автоматически реагировать на эти события с помощью функций по обработке, определяемых при вызове формы (JavaScript callbacks). Такая функциональность может дополнять получение информации через серверные оповещения, но её всё же не рекомендуется использовать для их замены.

Использование

Для подключения и использования возможностей контроля событий в платёжной форме Payment Page не требуется никаких согласований и организационных действий — только технические.

Во-первых, в клиентской части веб-сервиса должны быть подключены служебные библиотеки от ecommpay. 
<link rel="stylesheet" href="https://paymentpage.ecommpay.com/shared/merchant.css" />
<script type="text/javascript" src="https://paymentpage.ecommpay.com/shared/merchant.js"></script>

Во-вторых, в веб-сервисе должна быть реализована функциональность по обработке тех событий, на которые необходимо реагировать с учётом специфики сервиса и пользовательских сценариев. Это могут быть, например, функции, касающиеся отображения статуса платежа в карточке заказа или работы с токенами платёжных карт, используемых пользователем.

В-третьих, в каждом вызове Payment Page, для которого необходим контроль интерфейсных событий, должен передаваться код соответствующих функций. Он должен определяться на языке JavaScript непосредственно в запросах, вместе с параметрами вызова платёжной формы. При этом допустимо определять любое число функций из числа поддерживаемых для Payment Page и использовать обращения к объектам data, в которых содержится информация о целевых событиях, когда это применимо (подробнее далее).

Так, при тестировании интеграции с платёжной платформой ecommpay через Payment Page можно фиксировать идентификаторы запросов на проведение платежей и использовать их в дальнейшем для контроля и анализа проведения платежей. Определение функции onPaymentSubmitResult, в рамках которой можно выводить значение переменной request_id в консоль браузера, может выглядеть следующим образом.

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');

Другой пример — определение функции В следующем примере определена функция onResize, которая должна автоматически вызываться при изменении размера страницы, отображаемой в элементе iframe, и использовать параметры объекта data для задания новых значений ширины и высоты фрейма.

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');

В этом примере функция onResize использует параметры объекта data для задания новых значений ширины и высоты в параметрах frameWidth и frameHeight.

Функции и события

Открытие формы

onLoaded

Открытие платёжной формы (с полноценной загрузкой всех элементов интерфейса и началом сеанса работы с учётом параметров вызова).

При регистрации этого события можно зафиксировать скорость открытия формы на конечном устройстве и ждать следующих действий пользователя.

Рис. 1. Пример объекта data
{
"width":900,
"height":640
}
onFailLoading

Ошибка при попытке открытия платёжной формы (без возможности начать сеанс работы с учётом параметров вызова).

При регистрации этого события можно проверить корректность параметров вызова и отправить повторный запрос (при этом допустимо повторно использовать тот же идентификатор платежа, если он корректен и до этого не использовался при проведении платежей в рамках проекта).

Рис. 2. Пример объекта data
{
"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"
    }
}

Переход к целевому действию

onPaymentMethodSelect

Выбор платёжного метода. В случаях, когда пользователь переходит между вкладками разных методов, событие регистрируется при каждом таком переходе.

При регистрации этого события можно зафиксировать, какой метод выбрал пользователь — на основании полученной информации, которая включает в себя название, код типа платежа (1 для оплат, 2 для выплат) и код метода (согласно справочнику).

Рис. 3. Пример объекта data
{
"name":"Bank cards",
"payment_method_type":"1",
"payment_method_code":"card"
}
onWalletSelect

Выбор сохранённых платёжных данных (платёжной карты или другого платёжного инструмента).

При регистрации этого события можно зафиксировать, какой платёжный инструмент выбрал пользователь (на основании маскированных данных об этом инструменте), и, если актуально, использовать эту информацию в работе веб-сервиса, например для последующего проведения платежей с применением токенов (подробнее).

Рис. 4. Пример объекта data
{
"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

Удаление сохранённых платёжных данных (платёжной карты или другого платёжного инструмента).

При регистрации этого события можно зафиксировать, какой платёжный инструмент исключил пользователь (на основании маскированных данных об этом инструменте), и, если актуально, использовать эту информацию в работе веб-сервиса.

Рис. 5. Пример объекта data
{
"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

Подтверждение целевого действия (после указания всех необходимых сведений в платёжной форме) и переход к странице ожидания.

При регистрации этого события можно зафиксировать время, понадобившееся пользователю для работы с платёжной формой, и, если актуально, использовать его в дальнейшем, например для настройки допустимого времени работы (подробнее). Также после регистрации этого события можно отображать в интерфейсе веб-сервиса информацию об ожидании результата платежа и ждать следующих событий.

Для этого события предоставление информации в объекте data не предусмотрено
onPaymentSubmitResult

Регистрация запроса в платёжной платформе.

При регистрации этого события можно зафиксировать идентификатор запроса на проведение платежа и использовать этот идентификатор для контроля состояния платежа в нештатных ситуациях, например при обрыве связи с пользовательским устройством и отсутствии серверных оповещений о проведении платежа (подробнее о контроле состояния платежей через программные запросы — в отдельной статье).

Рис. 6. Пример объекта data
{
 "request_id": "bc4-5a032482802f-00002836"
}

Выполнение требуемых процедур

onShowClarificationPage

Отображение страницы для ввода дополнительных сведений, необходимых для выполнения целевого действия (подробнее).

При регистрации этого события можно зафиксировать факт запроса дополнительных сведений у пользователя и время этого события, после чего отследить, перешёл ли пользователь к следующим шагам (по событию onSubmitClarificationForm) и был ли проведён платёж (с итоговым статусом Success).

Для этого события предоставление информации в объекте data не предусмотрено
onSubmitClarificationForm

Подтверждение отправки запрошенных сведений.

При регистрации этого события можно зафиксировать время, понадобившееся пользователю для предоставления запрошенных дополнительных сведений, и отследить, был ли проведён платёж (с итоговым статусом Success). При регулярной фиксации событий onSubmitClarificationForm с последующим отклонением платежей можно обращаться к специалистам технической поддержки ecommpay и настраивать передачу необходимых сведений в запросах или их сбор в платёжной форме (подробнее).

Для этого события предоставление информации в объекте data не предусмотрено
onRedirectIframe

Перенаправление к стороннему сервису с использованием элемента iframe (согласно параметрам проекта и вызова, подробнее).

При регистрации этого события можно зафиксировать время такого перехода и отследить, вернулся ли пользователь к платёжной форме (по событию onRedirectIframeComplete) и был ли проведён платёж (с итоговым статусом Success). При выявлении проблем с такими переходами и возвращениями пользователей можно обращаться к специалистам технической поддержки ecommpay.

Для этого события предоставление информации в объекте data не предусмотрено
onResize

Изменение размера HTML-страницы, отображаемой в элементе iframe.

При регистрации этого события можно зафиксировать актуальные размеры страниц, используемых в рамках выполнения пользователем целевых действий, проверить, что исходный размер элемента iframe позволяет полноценно отображать эти страницы, и при необходимости скорректировать размеры элемента iframe.

Рис. 7. Пример объекта data
{
"width":1080,
"height":660
}
onRedirectIframeComplete

Возвращение от стороннего сервиса, открытого в элементе iframe, к платёжной форме.

При регистрации этого события можно зафиксировать время работы пользователя со сторонним сервисом и ожидать завершения сеанса работы с платёжной формой.

Для этого события предоставление информации в объекте data не предусмотрено

Отображение итоговой информации

onTokenizeSuccess

Отображение итоговой страницы с информацией о сохранении платёжных данных (в результате вызова и использования формы в режиме card_tokenize).

При регистрации этого события можно сохранить созданный токен и использовать его для последующих действий на стороне веб-сервиса.

Рис. 8. Пример объекта data
{
"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

Отображение итоговой страницы с информацией о том, что проверка действительности платёжного инструмента проведена (в результате вызова и использования формы в режиме card_verify).

При регистрации этого события можно зафиксировать, что платёжный инструмент признан действительным, и перейти к последующим действиям на стороне веб-сервиса (например, к регистрации токена платёжной карты и инициированию выплаты).

Рис. 9. Пример объекта data
{
    "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

Отображение итоговой страницы с информацией о том, что проверка действительности платёжного инструмента отклонена (в результате вызова и использования формы в режиме card_verify).

При регистрации этого события можно зафиксировать, что платёжный инструмент не признан действительным, уточнить причину отклонения и отобразить пользователю соответствующее сообщение.

Рис. 10. Пример объекта data
{
    "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

Отображение итоговой страницы с информацией о проведении платежа.

При регистрации этого события можно зафиксировать итоговый статус платежа и перейти к последующим действиям на стороне веб-сервиса (с выполнением оплаченного заказа и соответствующей коммуникацией с пользователем). Также в таком случае можно зафиксировать общее время проведения платежа.

Рис. 11. Пример объекта data
{
"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

Отображение итоговой страницы с информацией об отклонении платежа.

При регистрации этого события можно зафиксировать, что платёж отклонён, уточнить причину отклонения, отобразить пользователю соответствующее сообщение и, если актуально, отправить повторный запрос (с новым идентификатором платежа).

Рис. 12. Пример объекта data
{
"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"
}

Закрытие формы

onDestroy

Закрытие платёжной формы до отображения итоговой страницы.

При регистрации этого события стоит принять соответствующие действия в клиентской части веб-сервиса (например, с уведомлением об уточнении информации), проверить статус платежа (подробнее) и перейти к последующим действиям, исходя из статуса платежа.

Для этого события предоставление информации в объекте data не предусмотрено
onExit

Закрытие платёжной формы после отображения итоговой страницы (в соответствии с заданными параметрами).

При регистрации этого события можно зафиксировать, что сеанс работы с формой закончен, и перейти к последующим действиям на стороне веб-сервиса. Также в таком случае можно зафиксировать общее время работы пользователя с формой.

Для этого события предоставление информации в объекте data не предусмотрено