«Мобильная коммерция»
Обзор
«Мобильная коммерция» — платёжный метод для проведения платежей с использованием счетов мобильной связи пользователей. Для работы с этим платёжным методом доступно проведение оплат через Payment Page и Gate, выплат и возвратов — через Gate и Dashboard.
Характеристика
Тип платёжного метода | мобильная коммерция |
---|---|
Регионы использования | |
Валюты платежей | |
Конвертация валют | – |
Оплаты | + |
Выплаты | + (доступны не для всех операторов мобильной связи) |
Оплаты по сохранённым данным | – |
Полные возвраты | + (доступны не для всех операторов мобильной связи) |
Частичные возвраты | – |
Опротестования | – |
Особенности | для подтверждения платежей пользователем может потребоваться процедура дополнения информации о платеже |
Организация и стоимость подключения | по согласованию с курирующим менеджером ECommPay |
Схема работы
При проведении платежа с использованием метода «Мобильная коммерция» задействуются веб-сервис мерчанта, один из интерфейсов и платёжная платформа ECommPay, а также сервис одного из операторов мобильной связи.
Основные операции
Интерфейсы | Время** | |||||
---|---|---|---|---|---|---|
Payment Page | CMS Plug-ins | Gate | Dashboard | базовое | предельное | |
Оплаты | + | – | + | – | * | * |
Выплаты | – | – | + | + | * | * |
Полные возвраты | – | – | + | – | * | * |
* Информацию необходимо уточнять у курирующего менеджера ECommPay.
** Базовое и предельное время определяются следующим образом:
- Базовое время — среднее расчётное время проведения платежа от момента его инициирования на стороне платёжной платформы до момента отправки инициатору оповещения о результате. Это время, определяемое для условий штатной работы всех технических средств и каналов связи, а также типичных действий со стороны пользователя (там, где они необходимы). Базовое время рекомендуется использовать для реагирования на отсутствие оповещений о результате платежа и выполнения опроса состояния платежа.
- Предельное время — максимально допустимое время проведения платежа от момента его инициирования на стороне платёжной платформы до момента отправки инициатору оповещения о результате. Если платёж не был проведён или отклонён за это время, он автоматически переводится в статус
decline
. Для индивидуальной настройки предельного времени следует обращаться к специалистам технической поддержки ECommPay.
Сценарии использования
Для проведения оплаты пользователь получает необходимую информацию от оператора мобильной связи и выполняет требуемые действия, чтобы подтвердить списание средств со счёта мобильной связи. При проведении выплат и возвратов пользователь лишь формирует заявку, при этом средства зачисляются на счёт мобильной связи пользователя.
Рис.: Оплата через Payment Page
Рис.: Оплата через Gate
Рис.: Возврат через Gate
Рис.: Выплата через Gate
Детальные сведения о том, что необходимо делать со стороны мерчанта для проведения платежей, а также о том, что можно использовать для проведения тестовых платежей и анализа информации о проведённых платежах и операциях, представлены в следующих разделах этой статьи.
Поддержка со стороны операторов
Платежи с использованием метода «Мобильная коммерция» проводятся через поддерживающие такие возможности сервисы операторов мобильной связи.
Оператор | Идентификатор | Страны | Валюты | Суммы | |
---|---|---|---|---|---|
минимум | максимум | ||||
«Билайн» | BEELINE |
RU, KZ | RUB, KZT | ||
«МТС» | MTS |
RU | RUB | Оплаты и выплаты: 1,00 RUB | |
Tele2 | TELE2 |
RU, KZ | RUB, KZT | ||
«МегаФон» | MEGAFON |
RU | RUB | Оплаты и выплаты: 1,00 RUB | |
Aitrtel | AIRTEL |
GH, RW, UG | GHS, RWF, UGX | * | * |
Activ | ACTIV |
KZ | KZT | ||
Altel | ALTEL |
KZ | KZT | ||
Econet | ECONET |
BI | BIF, USD | * | * |
Kcell | KCELL |
KZ | KZT | ||
MTN | MTN |
CI, CM, GH, RW, UG, ZM | GHS, RWF, UGX, USD, ZMW | * | * |
M-Pesa | MPESA |
KE | KES | * | * |
Orange | ORANGE |
CM | USD, XAF | * | * |
Tigo | TIGO |
GH | GHS | * | * |
Vodafone | VODAFONE |
GH | GHS | * | * |
* Данные ограничения следует уточнять у курирующего менеджера ECommPay.
Вместе с тем, список доступных операторов связи и стран можно получить через HTTP-POST-запрос к одной из конечных точек группы /v2/info/mobile/{operation_type}/list Gate API:
/v2/info/mobile/sale/list
— для получения списка операторов и стран, поддерживающих проведение оплат;/v2/info/mobile/payout/list
— для получения списка операторов и стран, поддерживающих проведение выплат.
Такой запрос должен содержать идентификатор проекта и подпись.
Рис.: Пример данных из запроса списка доступных операторов и стран
{ "general": { "project_id": 200, "signature": "K6jllym+PtObocZtr345st==" } }
Оплаты через Payment Page
Общая информация
Для оплаты через Payment Page с использованием метода «Мобильная коммерция» со стороны веб-сервиса необходимо отправить запрос, содержащий требуемые параметры и подпись, на рабочий URL ECommPay и принять оповещение о результате оплаты. При этом метод «Мобильная коммерция» можно сделать предварительно выбранным (подробнее — в разделе Предварительный выбор платёжных методов). Полная схема проведения оплаты выглядит следующим образом.
Рис.: Проведение оплаты через Payment Page. Описание шагов
- Пользователь на стороне веб-сервиса инициирует оплату.
- От веб-сервиса на заданный URL ECommPay передаётся запрос на проведение оплаты через Payment Page.
- Запрос на проведение оплаты поступает в платёжную платформу.
- Выполняется начальная обработка запроса, в рамках которой обеспечивается проверка наличия обязательных параметров и корректной подписи.
- Осуществляется формирование Payment Page согласно параметрам проекта и вызова.
- Пользователю отображается сформированная платёжная форма.
- Пользователь выбирает для оплаты метод «Мобильная коммерция».
- Пользователю отображается форма для ввода номера телефона.
- Пользователь выбирает оператора мобильной связи и вводит номер телефона абонента, чей счёт необходимо использовать для оплаты.
- Запрос на проведение оплаты с использованием метода «Мобильная коммерция» поступает в платёжную платформу.
- Выполняются дальнейшая обработка запроса и его отправка в сервис оператора мобильной связи.
- На стороне сервиса оператора выполняется обработка запроса на оплату.
- Пользователю отправляется SMS-сообщение с кодом подтверждения оплаты или отображается платёжная инструкция.
- Пользователь выполняет необходимые действия.
- На стороне сервиса оператора мобильной связи выполняется обработка платежа.
- Информация о результате оплаты отображается пользователю в сервисе оператора мобильной связи.
- Пользователь перенаправляется к Payment Page.
- От сервиса оператора мобильной связи к платёжной платформе направляется результат оплаты.
- От платёжной платформы к веб-сервису направляется оповещение о результате оплаты.
- От платёжной платформы к Payment Page направляется результат оплаты.
- Информация о результате оплаты отображается пользователю на Payment Page.
По умолчанию при работе с этим методом пользователь выбирает сначала метод «Мобильная коммерция», а затем — оператора мобильной связи. Вместе с тем, в платёжной платформе ECommPay поддерживается возможность предварительного выбора оператора мобильной связи или страны. При использовании этой возможности пропускается шаг 7 схемы проведения оплаты, а на 9-м шаге пользователю необходимо лишь ввести номер телефона.
При обработке запроса на оплату для подтверждения платежа в зависимости от специфики сервиса оператора связи может использоваться один из следующих способов:
- пользователь вводит в платёжную форму полученный в SMS-сообщении код подтверждения платежа;
- пользователь выполняет необходимые действия согласно отображаемой ему платёжной инструкции.
Для обеспечения подобных процедур используется возможность дополнения информации о платеже (подробнее).
Информация о формате запросов и параметрах вызова Payment Page при работе с методом «Мобильная коммерция», а также о формате оповещений о результатах оплат приведена далее; общая информация о работе с Payment Page API — в разделе Описание Payment Page API.
Формат запросов
При формировании запросов на открытие платёжной формы с применением метода «Мобильная коммерция» необходимо учитывать следующее:
- Должен использоваться базовый минимум параметров — параметры, обязательные для любого платёжного метода:
- project_id — идентификатор проекта, полученный от ECommPay при интеграции;
- payment_id — идентификатор платежа, уникальный в рамках проекта;
- customer_id — идентификатор пользователя, уникальный в рамках проекта;
- payment_currency — код валюты платежа в формате ISO-4217 alpha-3;
- payment_amount — сумма платежа в дробных единицах валюты.
- Валютой платежа может быть любая, указанная в таблице .
- Для предварительного выбора метода «Мобильная коммерция» необходимо указывать код
mobile
в параметре force_payment_method, а для предварительного выбора оператора мобильной связи или страны — дополнительно передавать объект payment_methods_options, содержащий следующие параметры:- enable_mobile_service — указатель предварительного выбора оператора связи и страны, следует передавать
1
при выборе оператора связи или страны на стороне веб-сервиса; - selected_operator — идентификатор выбранного оператора, в соответствии с таблицей Поддерживаемые мобильные операторы и их ограничения;
- selected_country — код страны в формате ISO 3166-1 alpha-2.
- enable_mobile_service — указатель предварительного выбора оператора связи и страны, следует передавать
- Дополнительно могут использоваться любые другие параметры из числа доступных для работы с Payment Page. Информация об этих параметрах приведена в разделе Параметры открытия платежной формы Payment Page.
- После определения всех параметров запроса необходимо составить подпись (подробнее).
Таким образом, корректный запрос на открытие платёжной формы с применением метода «Мобильная коммерция» должен содержать идентификаторы проекта и платежа, идентификатор пользователя, код валюты и сумму платежа и подпись, а также может содержать другие необходимые параметры:
Рис.: Пример данных из запроса на открытие Payment Page с возможностью выбора метода «Мобильная коммерция» пользователем
{ project_id: 1380, payment_id: '936', customer_id: 'customer1', payment_currency: 'KZT', payment_amount: 25000, signature: "jhfdudu4DqtVUkDJrOcZzUCwX6R\/ekpZhkIQg==" }
Рис.: Пример данных из запроса на открытие Payment Page с предварительным выбором метода и оператора мобильной связи
{ project_id: 1380, payment_id: '736', customer_id: 'customer1', payment_currency: 'KZT', payment_amount: 25000, force_payment_method: 'mobile', payment_methods_options: { "enable_mobile_service": 1, "selected_operator": "TELE2" }, signature: "kanfgwi8dtdxtEEyvk1Y4HASCQ9vySO\/RLCvhtT4DqtVUkDJrOcZzUCwsbbk8hkIQg==" }
Рис.: Пример данных из запроса на открытие Payment Page с предварительным выбором метода и страны
{ project_id: 1380, payment_id: '736', customer_id: 'customer1', payment_currency: 'KZT', payment_amount: 25000, force_payment_method: 'mobile', payment_methods_options: { "enable_mobile_service": 1, "selected_country": "KZ" }, signature: "awegiyqedxtEEyvk1Y4HASCQ9vySO\/RLCvhtT4DqtVUkDJrOcZzUCwX6R\/ekpZhkIQg==" }
Формат оповещений
Для оповещений о результатах оплат с применением метода «Мобильная коммерция» используется типовой формат, описание которого представлено в разделе Оповещения.
В следующем примере содержится информация о том, что в рамках проекта 382
проведена оплата в размере 800,00 RUB
со счёта мобильной связи пользователя с номером телефона 79821234567
.
Рис.: Пример данных из оповещения о проведении оплаты
{ "customer": { "id": "sc-997741" }, "payment": { "date": "2019-10-18T07:30:50+0000", "id": "e16d0d998485698c652f96f6b2ff8826", "method": "mobile", "status": "success", "sum": { "amount": 80000, "currency": "RUB" }, "type": "purchase", "account": { "number": "79821234567" }, "description": "" }, "project_id": 382, "operation": { "id": 7375000008886, "type": "sale", "status": "success", "date": "2019-10-18T07:30:50+0000", "created_date": "2019-10-18T07:29:08+0000", "request_id": "83a47d9a5f5677b55fe534d9a9c0335a18-00007376", "sum_initial": { "amount": 80000, "currency": "RUB" }, "sum_converted": { "amount": 80000, "currency": "RUB" }, "code": "0", "message": "Success", "provider": { "id": 1078, "payment_id": "118665991", "auth_code": "" } }, "account": { "type": "MTS" }, "signature": "gf5CBRhCgltK1fowqyrIQoqy76z1x5B9jwOkuJcrVEA==" } }
В следующем примере содержится информация об отклонении оплаты из-за недостатка средств на счёте пользователя.
Рис.: Пример данных из оповещения об отклонении оплаты
{ "project_id": 981, "payment": { "id": "93688696", "type": "purchase", "status": "decline", "date": "2019-10-18T07:32:26+0000", "method": "mobile", "sum": { "amount": 30000, "currency": "RUB" }, "description": "" }, "account": { "number": "79051234567", "type": "mBEELINE" }, "customer": { "id": "1028232202" }, "operation": { "id": 29839000009286, "type": "sale", "status": "decline", "date": "2019-10-18T07:32:26+0000", "created_date": "2019-10-18T07:08:26+0000", "request_id": "8ff0457e32ad81b524a807d7a307ffa9ae8f03aadb0b-00029840", "sum_initial": { "amount": 30000, "currency": "RUB" }, "sum_converted": { "amount": 30000, "currency": "RUB" }, "code": "20105", "message": "Insufficient funds on customer account", "provider": { "id": 1078, "payment_id": "118662791", "auth_code": "" } }, "signature": "ZdfYgsg02Mhd1c/43dOK8v2s3rnFr7I+2uqIZ==" } }
Дополнительные материалы
Для организации работы с оплатами через Payment Page также могут быть полезны следующие материалы:
Оплаты через Gate
Общая информация
Для оплаты через Gate с использованием метода «Мобильная коммерция» со стороны веб-сервиса необходимо:
- Отправить запрос, содержащий требуемые параметры и подпись, на рабочий URL ECommPay.
- При необходимости принять промежуточное оповещение с дополнительной информацией от платёжной платформы ECommPay и выполнить требуемые действия.
- Принять от платёжной платформы ECommPay оповещение о результате оплаты.
Полная схема проведения оплаты выглядит следующим образом.
Рис.: Проведение оплаты через Gate. Описание шагов
- Пользователь на стороне веб-сервиса инициирует оплату через сервис оператора мобильной связи.
- От веб-сервиса на заданный URL ECommPay передаётся запрос на проведение оплаты через Gate.
- Запрос на проведение оплаты поступает в платёжную платформу ECommPay.
- Выполняется начальная обработка запроса, в рамках которой обеспечивается проверка наличия обязательных параметров и корректной подписи.
- От платёжной платформы к веб-сервису направляется ответ с информацией о получении запроса и его корректности, подробнее — в разделе Формат ответа.
- В платёжной платформе выполняются дальнейшая обработка запроса и его отправка в сервис оператора мобильной связи.
- На стороне сервиса оператора выполняется обработка запроса на оплату.
- Пользователю отправляется SMS-сообщение с кодом подтверждения оплаты. Этот шаг не является обязательным для некоторых операторов мобильной связи. В некоторых случаях пользователю необходимо указать код на стороне веб-сервиса, тогда со стороны веб-сервиса необходимо отправить запрос с кодом подтверждения в платёжную платформу.
- Пользователь выполняет необходимые действия. В некоторых случаях на стороне веб-сервиса необходимо отобразить пользователю платёжную инструкцию, данные для отображения которой передаются в оповещении от платёжной платформы.
- На стороне сервиса оператора мобильной связи выполняется обработка платежа.
- Пользователю отображается информация о результате оплаты.
- От сервиса оператора мобильной связи к платёжной платформе направляется уведомление о результате оплаты.
- От платёжной платформы к веб-сервису направляется оповещение о результате оплаты.
- От веб-сервиса пользователю направляется информация о результате оплаты.
Информация о формате запросов и параметрах инициирования оплат методом «Мобильная коммерция» через Gate, а также о формате оповещений о результатах оплат приведена далее, общая информация о работе с Gate API — в разделе Работа с API.
Формат запросов
При работе с запросами на оплаты с использованием метода «Мобильная коммерция» необходимо учитывать следующее:
- Должен использоваться HTTP-POST-запрос к конечной точке /v2/payment/mobile/sale.
- В запросе должны использоваться следующие объекты и параметры:
- general — объект, содержащий основные сведения о запросе:
- project_id — идентификатор проекта, полученный от ECommPay при интеграции;
- payment_id — идентификатор платежа, уникальный в рамках проекта;
- signature — подпись запроса, составленная после указания целевых параметров (подробнее — в разделе Использование подписи к данным);
- customer — объект, содержащий сведения о пользователе:
- id — идентификатор пользователя, уникальный в рамках проекта;
- ip_address — IP-адрес устройства пользователя;
- account — объект, содержащий сведения о счёте пользователя:
- number — номер телефона для оплаты с использованием счёта мобильной связи, указывается с кодом страны, без знаков пунктуации и специальных символов (например,
79031234567
); - service_provider* — идентификатор оператора мобильной связи пользователя;
- number — номер телефона для оплаты с использованием счёта мобильной связи, указывается с кодом страны, без знаков пунктуации и специальных символов (например,
- payment — объект, содержащий сведения о платеже:
- amount — сумма в дробных единицах валюты;
- currency — код валюты платежа в формате ISO-4217 alpha-3;
- description* — описание платежа.
Прим.: * Данные параметры не являются обязательными для всех мобильных операторов. Рекомендуется настроить реагирование на ситуации с необходимостью дополнения информации о платеже. - general — объект, содержащий основные сведения о запросе:
- Валютой платежа может быть любая, указанная в таблице Характеристика.
- Дополнительно могут использоваться любые другие параметры, указанные в спецификации.
Таким образом, корректный запрос на оплату с применением метода «Мобильная коммерция» должен содержать идентификаторы проекта и платежа, подпись, идентификатор пользователя, IP-адрес устройства пользователя, номер телефона пользователя, сумму платежа и код валюты, а также может содержать другие необходимые параметры:
Рис.: Пример данных из запроса на оплату
{ "general": { "project_id": 382, "payment_id": "e16d0d998485698c652f96f6b2ff8826", "signature": "3zjYFq8JuRey87Q4OyuWs1KaaWIHaNUPcN4sF6x4Um+K4SAyamNnFVg==" }, "customer": { "id": "customer123", "ip_address": "127.0.0.1" }, "account": { "number": "79821234567", "service_provider": "TELE2" }, "payment": { "amount": 80000, "currency": "RUB" } }
Форматы оповещений и запросов для дополнения информации о платеже
В тех случаях, когда для подтверждения платежа пользователь должен указать проверочный код от оператора мобильной связи, от платёжной платформы к веб-сервису передаётся оповещение о необходимости дополнения информации о платеже. При приёме такого оповещения необходимо получить от пользователя проверочный код (в платёжном интерфейсе веб-сервиса), отправить POST-запрос с этим кодом к конечной точке /v2/payment/clarification и получить ответ о приёме этого запроса в обработку.
В оповещении о необходимости дополнения информации о платеже содержится массив clarification_fields
, содержащий в себе название параметра approval_code — кода подтверждения платежа, который пользователь должен получить в SMS-сообщении и указать на стороне веб-сервиса. Срок действия такого кода составляет 90 секунд с момента его формирования на стороне оператора, и в течение этого времени в сервисе оператора должна быть получена информация с кодом, указанным пользователем.
Рис.: Пример данных из оповещения о необходимости дополнения информации о платеже
{ "clarification_fields": [ "approval_code" ] }
Запрос на продолжение платежа с учётом дополнения данных отправляется методом POST к конечной точке /v2/payment/clarification и должен содержать следующие объекты и параметры:
- general — объект, содержащий основные сведения о запросе:
- project_id — идентификатор проекта, полученный от ECommPay при интеграции;
- payment_id — идентификатор платежа, уникальный в рамках проекта;
- signature — подпись, составленная после указания целевых параметров (подробнее — в разделе Работа с подписью к данным);
- additional_data — объект с запрошенными данными:
- approval_code — код подтверждения платежа, указанный пользователем на стороне веб-сервиса.
Таким образом, корректный запрос должен содержать идентификаторы проекта и платежа, подпись и код подтверждения платежа:
Рис.: Пример данных из запроса для продолжения платежа с учётом дополнения данных
{ "general": { "project_id": 11, "payment_id": "EPr-bf14", "signature": "v7KNMpfogAthg1ZZ5D/aZAeb0VMdeR+CqghwSm==" }, "additional_data": { "approval_code": "25845775XZnv1vDN" } }
Чтобы обеспечить своевременное подтверждение платежа на стороне оператора, рекомендуется отправлять запрос с кодом подтверждения в течение 80 секунд после получения оповещения с массивом clarification_fields
. При отправке этого запроса проведение платежа может продолжаться следующим образом:
- Если переданный код отправлен своевременно и является корректным, то проведение платежа продолжается на стороне платёжной платформы и сервиса оператора, после чего к веб-сервису отправляется итоговое оповещение.
- Если переданный код отправлен своевременно, но не является корректным, то со стороны платёжной платформы к веб-сервису повторно отправляется оповещение с массивом
clarification_fields
. В этом случае стоит повторно предоставить пользователю возможность ввести корректный код, после чего со стороны веб-сервиса отправить запрос с этим кодом в платёжную платформу (также до истечения исходных 80 секунд). - Если переданный код отправлен после истечения 80 секунд, то возможны следующие варианты:
- При своевременной передаче корректного кода оператору связи проведение платежа продолжается на стороне платёжной платформы и сервиса оператора, после чего к веб-сервису отправляется итоговое оповещение.
- При передаче оператору некорректного кода или кода с истёкшим сроком действия от платформы к веб-сервису повторно отправляется оповещение с массивом
clarification_fields
. В этом случае рекомендуется отправить в платформу запрос на повторную отправку кода подтверждения пользователю, получить от пользователя новый код и отправить запрос на продолжение платежа с этим кодом.
Запрос на повторную отправку кода подтверждения пользователю отправляется методом POST к конечной точке /v2/customer/action/resend
, относящейся к группе /v2/customer/action/{action_name}, и должен содержать следующие объекты и параметры:
- general — объект, содержащий основные сведения о запросе:
- project_id — идентификатор проекта, полученный от ECommPay при интеграции;
- payment_id — идентификатор платежа, уникальный в рамках проекта;
- signature — подпись, составленная после указания целевых параметров (подробнее — в разделе Работа с подписью к данным);
- customer — объект, содержащий сведения о пользователе:
- ip_address — IP-адрес устройства пользователя.
Таким образом, корректный запрос должен содержать идентификаторы проекта и платежа, подпись и IP-адрес устройства пользователя:
Рис.: Пример данных из запроса на повторную отправку кода подтверждения пользователю
{ "general": { "project_id": 382, "payment_id": "e16d0d998485698c652f96f6b2ff8826", "signature": "3zjYFqRhDsaTLF7FVv4yu+Ziereqwr4343x/wGFVg==" }, "customer": { "ip_address": "85.140.0.68" } }
В рамках одного платежа запрос на повторную отправку кода подтверждения пользователю может использоваться не более трёх раз. При этом срок действия каждого нового кода, как и в случае с первым кодом, составляет 90 секунд с момента формирования на стороне оператора.
Форматы данных для отображения платёжной инструкции
В некоторых случаях (в зависимости от провайдера, обрабатывающего платёж) необходимо, чтобы пользователь выполнил действия согласно платёжной инструкции. Данные для отображения такой инструкции отправляются от платёжной платформы к веб-сервису в оповещении с массивом display_data, в котором содержатся объекты со следующими параметрами:
- type — тип объекта (в значении всегда передаётся
add_info
); - title — указатель пункта инструкции;
- data — содержание пункта, указанного в параметре
title
.
Рис.: Пример данных из оповещения с платёжной инструкцией
"display_data": [ { "type": "add_info", "title": "step 1", "data": "Ensure that you have sufficient balance on your mobile money account" }, { "type": "add_info", "title": "step 2", "data": "Approve the payment request sent to your phone" } ]
В других случаях (с учётом особенностей работы сервисов операторов связи) для подтверждения платежа пользователю необходимо не указывать проверочный код, а выполнять иные действия, в соответствии с платёжной инструкцией. Данные для отображения такой инструкции отправляются от платёжной платформы к веб-сервису в оповещении с массивом display_data, в котором содержатся объекты со следующими параметрами:
- type — тип передаваемых данных (в значении всегда передаётся
add_info
); - title — язык платёжной инструкции;
- data — текст платёжной инструкции (при передаче значения
en
в параметре title текст указывается на английском, при значенииru
— на русском).
Далее в справочных целях приведён фрагмент оповещения, содержащего данные для отображения пользователю.
Формат оповещений
Для оповещений о результатах оплат с использованием метода «Мобильная коммерция» используется типовой формат, описание которого представлено в разделе Оповещения.
В следующем примере в оповещении содержится информация о том, что в рамках проекта 382
проведена оплата в размере 800,00 RUB
со счёта мобильной связи пользователя с номером телефона 79821234567
.
Рис.: Пример данных из оповещения о проведении оплаты
{ "customer": { "id": "sc-997741" }, "payment": { "date": "2019-10-18T07:30:50+0000", "id": "e16d0d998485698c652f96f6b2ff8826", "method": "mobile", "status": "success", "sum": { "amount": 80000, "currency": "RUB" }, "type": "purchase", "account": { "number": "79821234567" }, "description": "" }, "project_id": 382, "operation": { "id": 7375000008886, "type": "sale", "status": "success", "date": "2019-10-18T07:30:50+0000", "created_date": "2019-10-18T07:29:08+0000", "request_id": "83a47d9a5f5677b55fe534d9a9c0335a18-00007376", "sum_initial": { "amount": 80000, "currency": "RUB" }, "sum_converted": { "amount": 80000, "currency": "RUB" }, "code": "0", "message": "Success", "provider": { "id": 1078, "payment_id": "118665991", "auth_code": "" } }, "account": { "type": "MTS" }, "signature": "gf5CBRhCgltRUoXMUJ38qX/TK1fowqyrIQoqy76z1x5B9jwOkuJcrVEA==" } }
В следующем примере содержится информация об отклонении оплаты из-за недостатка средств на счёте пользователя.
Рис.: Пример данных из оповещения об отклонении оплаты
{ "project_id": 981, "payment": { "id": "93688696", "type": "purchase", "status": "decline", "date": "2019-10-18T07:32:26+0000", "method": "mobile", "sum": { "amount": 30000, "currency": "RUB" }, "description": "" }, "account": { "number": "79051234567", "type": "BEELINE" }, "customer": { "id": "1028232202" }, "operation": { "id": 29839000009286, "type": "sale", "status": "decline", "date": "2019-10-18T07:32:26+0000", "created_date": "2019-10-18T07:08:26+0000", "request_id": "8ff0457e32ad81b524a807d7a307ffa9ae8f03aadb0b-00029840", "sum_initial": { "amount": 30000, "currency": "RUB" }, "sum_converted": { "amount": 30000, "currency": "RUB" }, "code": "20105", "message": "Insufficient funds on customer account", "provider": { "id": 1078, "payment_id": "118662791", "auth_code": "" } }, "signature": "ZdfYgsg02Mhd1c/OK8v2s3rnFr7I+2uqIZCQ5Kc9Pr/qXZcGUyIvyu3 8yF0F7ZudmdYY3Thzh6Fpj9/kKHTWKQ==" } }
Дополнительные материалы
Для организации работы с оплатами через Gate также могут быть полезны следующие материалы:
Возвраты через Gate
Общая информация
«Мобильная коммерция» поддерживает проведение полных возвратов. Для проведения возврата через Gate с использованием метода «Мобильная коммерция» со стороны веб-сервиса необходимо отправить запрос, содержащий требуемые параметры и подпись, на рабочий URL ECommPay и принять оповещение о результате. Полная схема проведения возврата представлена далее.
Рис.: Проведение возврата через Gate
- Пользователь запрашивает возврат.
- От веб-сервиса на заданный URL ECommPay передаётся запрос на проведение возврата.
- Запрос на проведение возврата поступает в платёжную платформу ECommPay.
- Выполняется начальная обработка запроса, в рамках которой обеспечивается проверка наличия обязательных параметров и корректной подписи.
- От платёжной платформы к веб-сервису направляется ответ с информацией о получении запроса и его корректности. Подробнее см. в разделе Формат ответа.
- В платёжной платформе выполняются дальнейшая обработка запроса и его отправка в сервис оператора мобильной связи.
- На стороне сервиса оператора выполняется обработка платежа.
- От сервиса оператора мобильной связи к платёжной платформе направляется оповещение о результате.
- От платёжной платформы к веб-сервису направляется оповещение о результате.
- От веб-сервиса пользователю направляется результат возврата.
Информация о формате запросов и параметрах инициации возвратов методом «Мобильная коммерция» через Gate, а также о формате оповещений о результатах возвратов приведена далее, общая информация о работе с API см. в разделе Работа с API.
Формат запросов
При работе с запросами на возврат с применением метода «Мобильная коммерция» необходимо учитывать следующее:
- Должен использоваться запрос /v2/payment/mobile/refund, отправляемый методом POST.
- В запросе должны использоваться следующие объекты и параметры:
- general — объект, содержащий основные идентификационные сведения о запросе:
- project_id — идентификатор проекта;
- payment_id — идентификатор платежа;
- signature — подпись запроса, составленная после указания целевых параметров (подробнее — в разделе Использование подписи к данным);
- payment — объект, содержащий сведения о возврате:
- description — комментарий или описание возврата.
- general — объект, содержащий основные идентификационные сведения о запросе:
- Дополнительно могут использоваться все параметры, указанные в спецификации.
Таким образом, корректный запрос на полный возврат с применением метода «Мобильная коммерция» должен содержать идентификаторы проекта и платежа, подпись, описание возврата:
Рис.: Пример запроса на возврат
{ "general": { "project_id": 9999, "payment_id":"Test-refund-001", "signature": "52D7C03EA096CAB4F271F12FE96EBE3D47F5F0EC4280509D293D1094AA793BBC" }, "payment": { "description": "Test refund" } }
Формат оповещений
Для оповещений о результатах возврата с применением метода «Мобильная коммерция» используется стандартный формат, описание которого представлено в разделе Оповещения.
В следующем примере оповещение свидетельствует о том, что в рамках проекта 386
был успешно проведён возврат в размере 1,00 RUB
.
Рис.: Пример оповещения о проведении возврата
{ "project_id": 386, "payment": { "id": "ORDER_104149_36884701", "type": "purchase", "status": "refunded", "date": "2021-03-18T07:42:02+0000", "method": "mobile", "sum": { "amount": 0, "currency": "RUB" }, "description": "" }, "account": { "number": "1234" }, "operation": { "id": 919, "type": "refund", "status": "success", "date": "2021-03-18T07:42:02+0000", "created_date": "2021-03-18T07:41:59+0000", "request_id": "ac1142f91e68eaacdc70a90b...5bd22a75dbffe10-00000001", "sum_initial": { "amount": 100, "currency": "RUB" }, "sum_converted": { "amount": 100, "currency": "RUB" }, "code": "0", "message": "Success", "provider": { "id": 2993, "payment_id": "6ad094c24bdfab6b4ffd7e25765fd77c", "auth_code": "", "date": "2021-03-18T07:42:01+0000" } }, "signature": "iO4ywLw3OKHFrgklqilnzIHrSPbEf..wc2NTkrgKU4LMCrZ8itl/LiMA==" }
В следующем примере возврат был отклонён.
Рис.: Пример оповещения об отказе в проведении возврата
{ "project_id": 386, "payment": { "id": "ORDER_15989542", "type": "purchase", "status": "success", "date": "2021-03-18T07:47:27+0000", "method": "mobile", "sum": { "amount": 31500, "currency": "RUB" }, "description": "" }, "account": { "***mber": "***9999" }, "operation": { "id": 923, "type": "refund", "status": "decline", "date": "2021-03-18T07:47:27+0000", "created_date": "2021-03-18T07:47:25+0000", "request_id": "e22cb890d5a9b67ff7f4a97...a6248b988ad6579b30-00000001", "sum_initial": { "amount": 31500, "currency": "RUB" }, "sum_converted": { "amount": 31500, "currency": "RUB" }, "code": "20000", "message": "General decline", "provider": { "id": 2993, "payment_id": "e1c792fb5aa16b32e1c1d751f96d3129", "auth_code": "" } }, "signature": "T0/7s1JZAcwWlypP5Xnhz...7aP4Z3pSlgzsCBwZaXgUOk1hkX6cJEQ==" }
Дополнительные материалы
Для организации работы с возвратами через Gate также могут быть полезны следующие материалы:
Выплаты через Gate
Общая информация
Для выплаты через Gate с использованием метода «Мобильная коммерция» со стороны веб-сервиса необходимо отправить запрос, содержащий требуемые параметры и подпись, на рабочий URL ECommPay и принять от платёжной платформы оповещение о результате выплаты. Полная схема проведения выплаты выглядит следующим образом.
Рис.: Проведение выплаты через Gate. Описание шагов
- Пользователь на стороне веб-сервиса инициирует выплату через сервис оператора мобильной связи.
- От веб-сервиса на заданный URL ECommPay передаётся запрос на проведение выплаты через Gate.
- Запрос на проведение выплаты поступает в платёжную платформу ECommPay.
- Выполняется начальная обработка запроса, в рамках которой обеспечивается проверка наличия обязательных параметров и корректной подписи.
- От платёжной платформы к веб-сервису направляется ответ с информацией о получении запроса и его корректности, подробнее — в разделе Формат ответа.
- В платёжной платформе выполняются дальнейшая обработка запроса и его отправка в сервис оператора мобильной связи.
- На стороне сервиса оператора выполняется обработка платежа.
- От сервиса оператора мобильной связи к платёжной платформе направляется оповещение о результате выплаты.
- От платёжной платформы к веб-сервису направляется оповещение о результате выплаты.
- От веб-сервиса пользователю направляется результат выплаты.
Информация о формате запросов и параметрах инициирования выплат методом «Мобильная коммерция» через Gate, а также о формате оповещений о результатах выплат приведена далее, общая информация о работе с Gate API — в разделе Работа с API.
Формат запросов
При работе с запросами на выплаты с использованием метода «Мобильная коммерция» необходимо учитывать следующее:
- Должен использоваться POST-запрос к конечной точке /v2/payment/mobile/payout.
- В запросе должны использоваться следующие объекты и параметры:
- general — объект, содержащий основные сведения о запросе:
- project_id — идентификатор проекта, полученный от ECommPay при интеграции;
- payment_id — идентификатор платежа, уникальный в рамках проекта;
- signature — подпись запроса, составленная после указания целевых параметров (подробнее — в разделе Использование подписи к данным);
- customer — объект, содержащий сведения о пользователе:
- id — идентификатор пользователя, уникальный в рамках проекта;
- ip_address — IP-адрес устройства пользователя;
- first_name* — имя;
- last_name* — фамилия;
- account — объект, содержащий сведения о счёте пользователя:
- number — номер телефона, на счёт мобильной связи которого совершается выплата, номер указывается с кодом страны, без знаков пунктуации и специальных символов (например,
79031234567
); - service_provider* — идентификатор мобильного оператора пользователя;
- number — номер телефона, на счёт мобильной связи которого совершается выплата, номер указывается с кодом страны, без знаков пунктуации и специальных символов (например,
- payment — объект, содержащий сведения о платеже:
- amount — сумма платежа в дробных единицах валюты;
- currency — код валюты платежа в формате ISO-4217 alpha-3.
Прим.: * Данные параметры не являются обязательными для всех операторов мобильной связи. За более подробной информацией следует обращаться к курирующему менеджеру ECommPay. - general — объект, содержащий основные сведения о запросе:
- Валютой платежа может быть любая, указанная в таблице Характеристика.
- Дополнительно могут использоваться все параметры, указанные в спецификации.
Таким образом, корректный запрос на выплату с применением метода «Мобильная коммерция» должен содержать идентификаторы проекта и платежа, подпись, идентификатор пользователя, IP-адрес устройства пользователя, номер телефона пользователя, сумму платежа и код валюты, а также может содержать другие необходимые параметры:
Рис.: Пример данных из запроса на выплату
{ "general": { "project_id": 35, "payment_id": "payout_65", "signature": "akchavu5w7v8vwg467Zie3x/wG8NUPcN4sF6x4Um+K4SAyamNnFVg==" }, "customer": { "id": "customer_45", "ip_address": "127.0.0.1" }, "account": { "number": "79123456789", "service_provider": "MTN" }, "payment": { "amount": 10000, "currency": "KZT" } }
Формат оповещений
Для оповещений о результатах выплат с использованием метода «Мобильная коммерция» используется типовой формат, описание которого представлено в разделе Оповещения.
В следующем примере в оповещении содержится информация о том, что в рамках проекта 25
была проведена выплата в размере 724,00 KZT
на счёт мобильной связи пользователя с номером телефона 79891234567
.
Рис.: Пример данных из оповещения о проведении выплаты
{ "sum_request": { "amount": 72400, "currency": "KZT" }, "request_id": "f7cf554411e67d2598159361644bc02ba08f4d64-00063844", "transaction": { "id": 63843000000321, "date": "2019-10-31T07:00:08+0000", "type": "payout" }, "payment": { "id": "13614419800", "method": "mobile", "date": "2019-10-31T07:00:08+0000", "result_code": "0", "result_message": "Success", "status": "success", "is_new_attempts_available": false, "attempts_timeout": 0, "cascading_with_redirect": false, "provider_id": 14 }, "sum_real": { "amount": 72400, "currency": "KZT" }, "customer": { "id": "1000000000946308" }, "account": { "number": "79891234567" }, "rrn": "", "general": { "project_id": 25, "payment_id": "13614419800", "signature": "efy09xOugbWMreW0T6I3VCz7rlRCqHTA2SiIm4X2H0fl804sB3VDZPEdK7r0 O/kR349nj7KcokTGpi23kiJlQ==" }, "description": "payout", "operations": [ { "id": 63843000000371, "type": "payout", "status": "success", "date": "2019-10-31T07:00:08+0000", "processing_time": null, "request_id": "f7cf554411e67d2598159361644bc02ba08f4d64-00063844", "sum": { "amount": 72400, "currency": "KZT" }, "code": "0", "message": "Success" } ] }
В следующем примере содержится информация об отклонении выплаты из-за недоступности аккаунта пользователя.
Рис.: Пример данных из оповещения об отказе в проведении выплаты
{ "sum_request": { "amount": 650000, "currency": "KZT" }, "request_id": "647c8ea772328e5df288344b5e6c57b207fda92-00013521", "transaction": { "id": 13520000009331, "date": "2019-10-31T08:44:02+0000", "type": "payout" }, "payment": { "id": "13612847900", "method": "mobile", "date": "2019-10-31T08:44:02+0000", "result_code": "20106", "result_message": "Customer account is no longer available", "status": "decline", "is_new_attempts_available": false, "attempts_timeout": 0, "cascading_with_redirect": false, "provider_id": 14 }, "sum_real": { "amount": 650000, "currency": "KZT" }, "customer": { "id": "1000000000930682" }, "account": { "number": "79531234567" }, "rrn": "", "general": { "project_id": 131, "payment_id": "13612847900", "signature": "V5bloYlpjQrL9PUBUJug9i8jb30vdC411W/le6AFZXLUuX5HQH1zYxWe 4n2hAj0CSM1Ew/HuQ8ivuLOFwEpJ2A==" }, "description": "payout", "operations": [ { "id": 13520000010671, "type": "payout", "status": "decline", "date": "2019-10-31T08:44:02+0000", "processing_time": null, "request_id": "647c8ea772328e51c289ea2a5387157b207fda92-00013521", "sum": { "amount": 650000, "currency": "KZT" }, "code": "20106", "message": "Customer account is no longer available" } ] }
Дополнительные материалы
Для организации работы с выплатами через Gate также могут быть полезны следующие материалы:
Выплаты через Dashboard
- как единичную выплату — в этом случае для каждой выплаты необходимо указать доступные для данного метода валюту и сумму, выбрать метод и заполнить все поля, отображаемые в интерфейсе с учётом выбранного метода;
- в рамках массового платежа — в этом случае все параметры выплат необходимо задать в файле формата CSV с учётом требований, представленных в разделе Выплаты через Gate (кроме пункта о подписи).
Информация о проведении выплат отображается в разделах Платежи и Мануальные платежи интерфейса Dashboard.
Более подробная информация о проведении выплат через Dashboard представлена в разделе Проведение выплат.
Тестирование
Общая информация
Для метода «Мобильная коммерция» доступно тестирование оплат через Payment Page и Gate, а также выплат через Gate. Тестирование может выполняться в рамках тестового проекта, и для подключения и отключения этой возможности необходимо обращаться к специалистам технической поддержки ECommPay.
При проведении тестовых платежей следует учитывать, что в запросах должен указываться идентификатор тестового проекта, в качестве валюты может использоваться только RUB, а оформление платёжной формы Payment Page может отличаться от используемого в рабочей среде.
Статусы тестовых платежей
Итоговые статусы тестовых оплат определяются исходя из сумм, указанных в запросах:
decline
— при указании суммы40000
или40400
,success
— при указании любой другой суммы.
Итоговые статусы тестовых выплат определяются исходя из сумм, указанных в запросах:
decline
— при указании суммы40000
или40400
,success
— при указании любой другой суммы.
При тестировании возвратов их итоговые статусы определяются исходя из сумм, указанных в запросах:
decline
— при указании суммы50000
или50500
,success
— при указании любой другой суммы.
Оплаты через Payment Page
Для проведения тестовой оплаты через Payment Page необходимо:
- Отправить в платёжную платформу корректный тестовый запрос на открытие Payment Page.
- Если в запросе не был указан метод
mobile
— выбрать метод «Мобильная коммерция». - Указать в поле ввода произвольный номер телефона из 11 цифр с корректным кодом страны (например,
79031234567
) и щёлкнуть кнопку Оплатить. - Убедиться в запуске обратного отсчёта времени и в отображении информации о результате оплаты по истечении 20 секунд.
- Принять оповещение с информацией о результате оплаты.
Информация о проведении оплат с использованием метода «Мобильная коммерция» через Payment Page представлена в пункте Оплаты через Payment Page этой статьи.
Оплаты через Gate
Для проведения тестовой оплаты через Gate необходимо отправить в платёжную платформу корректный тестовый запрос и принять оповещение с информацией о результате. Информация о проведении оплат с использованием метода «Мобильная коммерция» через Gate представлена в пункте Оплаты через Gate этой статьи.Выплаты через Gate
Для проведения тестовой выплаты через Gate необходимо отправить в платёжную платформу корректный тестовый запрос и принять оповещение с информацией о результате. Информация о проведении выплат с использованием метода «Мобильная коммерция» через Gate представлена в пункте Выплаты через Gate этой статьи.
Анализ результатов проведения платежей
Как и при работе с другими платёжными методами, которые предоставляет ECommPay, при использовании метода «Мобильная коммерция» доступны разные способы анализа информации о платежах и операциях с применением этого метода — как в отдельности, так и в совокупности с другими методами.
Всю необходимую информацию можно получать и анализировать средствами Dashboard, в том числе с помощью аналитических панелей в разделе Аналитика.
Также можно выгружать необходимую информацию для последующего анализа с помощью специализированных аналитических средств сторонних разработчиков:
- Dashboard позволяет выгружать данные в формате CSV с помощью инструментов в разделе Отчёты. При этом можно выполнять разовые и периодические выгрузки информации на локальный компьютер.
- Data API позволяет получать информацию в формате JSON и отправлять ее на заданный URL — для этого применяются запросы к конечной точке /operations/get.
С любыми вопросами о возможностях анализа результатов можно обращаться в службу технической поддержки ECommPay.