«Мобильная коммерция»
Обзор
«Мобильная коммерция» — платёжный метод для проведения платежей по номеру телефона пользователя. Оплаты осуществляются через Payment Page и Gate, выплаты — через Gate и Dashboard (Old Dashboard).
Характеристика
Тип платёжного метода | мобильная коммерция |
---|---|
Регионы использования |
подробная информация об ограничениях для мобильных операторов представлена в таблице Поддерживаемые мобильные операторы и их ограничения |
Валюты платежей |
подробная информация об ограничениях для мобильных операторов представлена в таблице Поддерживаемые мобильные операторы и их ограничения |
Конвертация валют | – |
Оплаты | + |
Выплаты | + (доступны не для всех мобильных операторов) |
Оплаты по сохранённым данным | – |
Полные возвраты | – |
Частичные возвраты | – |
Опротестования | – |
Особенности |
|
Организация и стоимость подключения | по согласованию с курирующим менеджером ECommPay |
Схема работы
В проведении отдельного платежа с использованием метода «Мобильная коммерция» задействуются веб-сервис мерчанта, один из интерфейсов и платёжная платформа ECommPay, а также технические средства мобильных операторов.
Основные операции
Интерфейсы | Время** | |||||
---|---|---|---|---|---|---|
Payment Page | CMS Plug-ins | Gate | Dashboard (Old Dashboard) | базовое | предельное | |
Оплаты | + | – | + | – | * | * |
Выплаты | – | – | + | + | * | * |
* Информацию необходимо уточнять у курирующего менеджера ECommPay.
** Базовое и предельное время определяются следующим образом:
- Базовое время — среднее расчётное время проведения платежа от момента его инициирования на стороне платёжной платформы до момента отправки инициатору оповещения о результате. Это время, определяемое для условий штатной работы всех технических средств и каналов связи, а также типичных действий со стороны пользователя (там, где они необходимы). Базовое время рекомендуется использовать для реагирования на отсутствие оповещений о результате платежа и выполнения опроса состояния платежа.
- Предельное время — максимально допустимое время проведения платежа от момента его инициирования на стороне платёжной платформы до момента отправки инициатору оповещения о результате. Если платёж не был проведён или отклонён за это время, он автоматически переводится в статус
decline
. Для индивидуальной настройки предельного времени следует обращаться к специалистам технической поддержки ECommPay.
Сценарии использования
Проведение оплат осуществляется со счёта мобильного телефона пользователя, проведение выплат — на счёт мобильного телефона пользователя.
Рис.: Оплата через Payment Page
Рис.: Оплата через Gate
Рис.: Выплата через Gate
Поддержка со стороны мобильных операторов
Проведение платежей с применением метода «Мобильная коммерция» осуществляется через мобильных операторов, поддерживающих работу с этим методом.
/v2/info/mobile/sale/list
— для уточнения списка мобильных операторов и стран, поддерживающих проведение оплат;/v2/info/mobile/payout/list
— для уточнения списка мобильных операторов и стран, поддерживающих проведение выплат.
Мобильный оператор | Идентификатор | Страны | Валюты | Суммы | |
---|---|---|---|---|---|
минимум | максимум | ||||
«Билайн» | BEELINE |
RU, KZ | RUB, KZT | ||
«МТС» | MTS |
RU | RUB | Оплаты и выплаты: 1,00 RUB | |
Tele2 | TELE2 |
RU, KZ | RUB, KZT | ||
«МегаФон» | MEGAFON |
RU | RUB | Оплаты и выплаты: 1,00 RUB | |
Altel | ALTEL |
KZ | KZT | Оплаты: 5,00 KZT | Оплаты: 60 000,00 KZT или 200 000,00 KZT * |
MTN** | MTN |
GH | GHS | * | * |
M-Pesa** | MPESA |
KE | KES | * | * |
Tigo** | TIGO |
GH | GHS | * | * |
Vodafone** | VODAFONE |
GH | GHS | * | * |
* Ограничения по суммам для данных мобильных операторов необходимо уточнять у курирующего менеджера ECommPay.
** В запросах на выплаты через Gate с использованием мобильных операторов MTN, M-Pesa, Tigo и Vodafone используются числовые идентификаторы, значения которых представлены в таблице Идентификаторы мобильных операторов.
Детальные сведения о том, что необходимо делать со стороны мерчанта для проведения платежей, а также о том, что можно использовать для анализа информации о проведённых платежах и операциях, представлены далее.
Оплаты через Payment Page
Общая информация
Для оплаты через Payment Page с использованием метода «Мобильная коммерция» со стороны веб-сервиса необходимо отправить запрос, содержащий требуемые параметры и подпись, на рабочий URL ECommPay и принять оповещение о результате оплаты. При этом метод «Мобильная коммерция» можно сделать предварительно выбранным (подробнее — в разделе Предварительный выбор платежного метода). Полная схема проведения оплаты представлена далее.
Рис.: Проведение оплаты через Payment Page
- Пользователь на стороне веб-сервиса инициирует оплату.
- От веб-сервиса на заданный URL ECommPay передаётся запрос на проведение оплаты через Payment Page.
- Запрос на проведение оплаты поступает в платёжную платформу.
- Выполняется начальная обработка запроса, в рамках которой обеспечивается проверка наличия обязательных параметров и корректной подписи.
- Осуществляется генерация Payment Page согласно настройкам проекта и параметрам вызова.
- Пользователю отображается сгенерированная платёжная форма.
- Пользователь выбирает для оплаты метод «Мобильная коммерция».
- Пользователю отображается форма для ввода номера телефона.
- Пользователь вводит номер телефона, с которого он хочет оплатить, и выбирает мобильного оператора.
- Запрос на проведение оплаты с использованием метода «Мобильная коммерция» поступает в платёжную платформу.
- Выполняются дальнейшая обработка запроса и его отправка в сервис «Мобильная коммерция».
- На стороне «Мобильная коммерция» выполняется обработка запроса на оплату.
- Пользователю отправляется СМС-сообщение с кодом подтверждения оплаты или отображается платёжная инструкция.
- Пользователь выполняет необходимые действия.
- На стороне сервиса «Мобильная коммерция» выполняется обработка платежа.
- Результат оплаты отображается пользователю в сервисе «Мобильная коммерция».
- Пользователь перенаправляется к Payment Page.
- От сервиса «Мобильная коммерция» к платёжной платформе направляется результат оплаты.
- От платёжной платформы к веб-сервису направляется оповещение о результате оплаты.
- От платёжной платформы к Payment Page направляется результат проведения оплаты.
- Результат оплаты отображается пользователю на Payment Page.
Информация о формате запросов и параметрах вызова Payment Page при работе с методом «Мобильная коммерция», а также о формате оповещений о результатах оплат приведена далее; общая информация о работе с API см. в разделе Описание Payment Page API.
Формат запросов
При формировании запросов на открытие платёжной формы с применением метода «Мобильная коммерция» необходимо учитывать следующее:
- Должен использоваться базовый минимум параметров — параметры, обязательные для любого платёжного метода:
- project_id — идентификатор проекта, полученный от ECommPay при интеграции;
- payment_id — идентификатор платежа, уникальный в рамках проекта;
- payment_currency — валюта платежа в формате ISO-4217 alpha-3;
- payment_amount — сумма платежа в минорных единицах;
- customer_id — идентификатор пользователя в рамках проекта.
- Валютой платежа может быть любая, указанная в таблице Характеристика.
- Для предварительного выбора метода «Мобильная коммерция» необходимо указывать код платёжного метода в параметре force_payment_method —
mobile
. - Если в запросе на открытие Payment Page используется параметр customer_phone, то номер телефона в значении параметра необходимо указывать с кодом страны, без знаков пунктуации и специальных символов (например,
79031234567
). - Дополнительно могут использоваться любые другие параметры из числа доступных для работы с Payment Page. Детальная информация обо всех параметрах приведена в разделе Параметры открытия платежной формы Payment Page.
- После определения всех параметров необходимо составить подпись. Подробную информацию см. в Работа с подписью к данным.
Таким образом, корректный запрос на открытие платёжной формы с применением метода «Мобильная коммерция» должен содержать идентификаторы проекта и платежа, а также валюту и сумму платежа и подпись:
{ payment_id: 'test936', payment_amount: 25000, payment_currency: 'KZT', project_id: 1380, customer_id: 'customer1', signature: "jhfdudu58dtdxtEEyvk1Y4HASCQ9vySO\/RLCvhtT4DqtVUkDJrOcZzUCwX6R\/ekpZhkIQg==" }
Дополнительные возможности
По умолчанию все мобильные операторы объединены в группу и отображаются при нажатии на кнопку «Мобильная коммерция», поэтому выбор мобильного оператора происходит в два этапа: пользователь выбирает метод, а затем выбирает мобильного оператора.
Возможно использование дополнительной настройки (мобильного сервиса), которая позволяет настроить предварительный выбор определённого мобильного оператора или страны. Чтобы использовать эту настройку, необходимо обратиться в службу технической поддержки ECommPay для добавления её в настройки проекта.
- enable_mobile_service — признак использования мобильного сервиса, необходимо передавать
1
; - selected_operator — идентификатор оператора для предварительного выбора, который указан в таблице Поддерживаемые мобильные операторы и их ограничения.
- selected_country — код страны в соответствии с ISO 3166-1 alpha-2.
Рис.: Пример запроса на открытие Payment Page с предварительно выбранным мобильным оператором
{ payment_id: 'test736', payment_amount: 25000, payment_currency: 'KZT', project_id: 1380, force_payment_method: 'mobile', payment_methods_options = {"enable_mobile_service":1, "selected_operator": "TELE2"}, signature: "kanfgwi8dtdxtEEyvk1Y4HASCQ9vySO\/RLCvhtT4DqtVUkDJrOcZzUCwsbbk8hkIQg==" }
Рис.: Пример запроса на открытие Payment Page с предварительно выбранной страной
{ payment_id: 'test936', payment_amount: 25000, payment_currency: 'KZT', project_id: 1380, force_payment_method: 'mobile', payment_methods_options = {"enable_mobile_service":1,"selected_country": "KZ"}, signature: "awegiyqedxtEEyvk1Y4HASCQ9vySO\/RLCvhtT4DqtVUkDJrOcZzUCwX6R\/ekpZhkIQg==" }
Формат оповещений
Для оповещений о результатах оплат с применением метода «Мобильная коммерция» используется стандартный формат, описание которого представлено в разделе Оповещения.
В следующем примере оповещение свидетельствует о том, что в рамках проекта 382
для пользователя sc-997741
была успешно проведена оплата в размере 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": "test payment" }, "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": "mMTS" }, "signature": "gf5CBRhCgltRUoXMUJ38qX/T1jhDE1kOvJFfD/iKk7x+hWE01bmFeT K1fowqyrIQoqy76z1x5B9jwOkuJcrVEA==" } }
В следующем примере оплата была отклонена из-за недостатка средств на счёте пользователя.
Рис.: Пример оповещения об отказе в проведении оплаты
{ "project_id": 981, "payment": { "id": "invoice_93688696", "type": "purchase", "status": "decline", "date": "2019-10-18T07:32:26+0000", "method": "mobile", "sum": { "amount": 30000, "currency": "RUB" }, "description": "test payment" }, "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/OK8v2s3rnFr7I+2uqIZCQ5Kc9Pr/qXZcGUyIvyu3 8yF0F7ZudmdYY3Thzh6Fpj9/kKHTWKQ==" } }
Дополнительные материалы
Для организации работы с оплатами через Payment Page также могут быть полезны следующие материалы:
Оплаты через Gate
Общая информация
Для оплаты через Gate с использованием метода «Мобильная коммерция» со стороны веб-сервиса необходимо:
- Отправить запрос, содержащий требуемые параметры и подпись, на рабочий URL ECommPay.
- Принять оповещение от платежной платформы ECommPay о результате оплаты.
Полная схема проведения оплаты представлена далее.
Рис.: Проведение оплаты через Gate
- Пользователь на стороне веб-сервиса инициирует оплату через «Мобильная коммерция».
- От веб-сервиса на заданный URL ECommPay передаётся запрос на проведение оплаты через Gate.
- Запрос на проведение оплаты поступает в платёжную платформу ECommPay.
- Выполняется начальная обработка запроса, в рамках которой обеспечивается проверка наличия обязательных параметров и корректной подписи.
- От платёжной платформы к веб-сервису направляется ответ с информацией о получении запроса и его корректности. Подробнее см. в разделе Формат ответа.
- В платёжной платформе выполняются дальнейшая обработка запроса и его отправка в сервис «Мобильная коммерция».
- На стороне «Мобильная коммерция» выполняется обработка запроса на оплату.
- Пользователю отправляется СМС-сообщение с кодом подтверждения оплаты. Этот шаг не является обязательным для некоторых мобильных операторов. В некоторых случаях пользователю необходимо указать код на стороне веб-сервиса, тогда со стороны веб-сервиса необходимо отправить запрос с кодом подтверждения в платёжную платформу.
- Пользователь выполняет необходимые действия.
- На стороне сервиса «Мобильная коммерция» выполняется обработка платежа.
- Пользователю отображается результат оплаты.
- От сервиса «Мобильная коммерция» к платёжной платформе направляется уведомление о результате оплаты.
- От платёжной платформы к веб-сервису направляется оповещение о результате оплаты.
- От веб-сервиса пользователю направляется результат оплаты.
Информация о формате запросов и параметрах инициации оплат методом «Мобильная коммерция» через Gate, а также о формате оповещений о результатах оплат приведена далее, общая информация о работе с API см. в разделе Работа с API.
Формат запросов
При работе с запросами на оплаты с применением метода «Мобильная коммерция» необходимо учитывать следующее:
- Должен использоваться запрос /v2/payment/mobile/sale, отправляемый методом POST.
- В запросе должны использоваться следующие объекты и параметры:
- 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": "3zjYFqRhDsaTLF7FVv4yu+Zie3x/wG8JuRey87Q4Oyb3FzF+2uWs1KaaWIHa NUPcN4sF6x4Um+K4SAyamNnFVg==" }, "customer": { "ip_address": "1.1.0.1", "id": "customer123" }, "payment": { "amount": 80000, "currency": "RUB" }, "account": { "number": "79821234567" } }
Форматы оповещений и запросов для дополнения информации о платеже
В некоторых случаях (в зависимости от провайдера, обрабатывающего платёж), когда от платёжной платформы поступает оповещение о необходимости дополнения информации о платеже, для проведения такого платежа необходимо отправить POST-запрос к конечной точке /v2/payment/clarification с кодом подтверждения платежа, полученным от пользователя, и получить ответ о приёме этого запроса в обработку.
В оповещении о необходимости дополнения информации содержится массив clarification_fields
, в состав которого входит параметр approval_code — код подтверждения платежа, который пользователь получает в SMS-сообщении и указывает на стороне веб-сервиса. Срок действия такого кода — 90 секунд с момента его создания на стороне провайдера.
Далее приведён фрагмент оповещения с массивом clarification_fields
.
{ "clarification_fields": [ "approval_code" ], }
Запрос для продолжения платежа, отправляемый к конечной точке /v2/payment/clarification, должен содержать следующие объекты и параметры:
- general — объект, содержащий основные идентификационные сведения запроса:
- project_id — идентификатор проекта, к которому относится проводимый платёж;
- 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
, рекомендуется отправить запрос на повторную отправку кода подтверждения пользователю, после чего отправить запрос с новым кодом подтверждения в платёжную платформу. Если код отправлен после истечения 80 секунд и со стороны платёжной платформы к веб-сервису не приходит оповещение с массивомclarification_fields
, то следует ожидать итогового оповещения о результате платежа.
Запрос на повторную отправку кода подтверждения пользователю отправляется к конечной точке /v2/customer/action/resend
, относящейся к группе запросов /v2/customer/action/{action_name} и должен содержать следующие объекты и параметры:
- general — объект, содержащий основные идентификационные сведения запроса:
- project_id — идентификатор проекта, к которому относится проводимый платёж;
- payment_id — идентификатор платежа, уникальный в рамках проекта;
- signature — подпись, составленная после указания целевых параметров (подробнее — в разделе Работа с подписью к данным);
- customer — объект, содержащий сведения о пользователе:
- ip_address — используемый IP-адрес.
Таким образом, корректный запрос должен содержать идентификаторы проекта и платежа, подпись и IP-адрес пользователя:
Рис.: Пример запроса на повторное получение кода подтверждения
{ "general": { "project_id": 382, "payment_id": "e16d0d998485698c652f96f6b2ff8826", "signature": "3zjYFqRhDsaTLF7FVv4yu+Ziereqwr4343x/wG...FVg==" }, "customer": { "ip_address": "85.140.0.68" } }
В рамках одного платежа запрос на повторную отправку кода подтверждения пользователю может быть отправлен не более трёх раз. Срок действия каждого из отправленных кодов — 90 секунд с момента создания на стороне провайдера.
После отправки корректного запроса на повторную отправку кода подтверждения пользователю следует предоставить пользователю возможность ввести новый код подтверждения и отправить запрос с этим кодом в платёжную платформу.
При этом со стороны платёжной платформы к веб-сервису может направляться оповещение с информацией о статусах платежа и операции, и статус операции в таких оповещениях может принимать некорректные значения, поэтому его рекомендуется игнорировать. Такие особенности вызваны спецификой работы провайдера.
Формат оповещений
Для оповещений о результатах оплат с применением метода «Мобильная коммерция» используется стандартный формат, описание которого представлено в разделе Оповещения.
В следующем примере оповещение свидетельствует о том, что в рамках проекта 382
для пользователя sc-997741
была успешно проведена оплата в размере 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": "test payment" }, "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/T1jhDE1kOvJFfD/iKk7x+hWE01bmFeT K1fowqyrIQoqy76z1x5B9jwOkuJcrVEA==" } }
В следующем примере оплата была отклонена из-за недостатка средств на счёте пользователя.
Рис.: Пример оповещения об отказе в проведении оплаты
{ "project_id": 981, "payment": { "id": "invoice_93688696", "type": "purchase", "status": "decline", "date": "2019-10-18T07:32:26+0000", "method": "mobile", "sum": { "amount": 30000, "currency": "RUB" }, "description": "test payment" }, "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/OK8v2s3rnFr7I+2uqIZCQ5Kc9Pr/qXZcGUyIvyu3 8yF0F7ZudmdYY3Thzh6Fpj9/kKHTWKQ==" } }
Дополнительные материалы
Для организации работы с оплатами через Gate также могут быть полезны следующие материалы:
Выплаты через Gate
Общая информация
Для выплаты через Gate с использованием метода «Мобильная коммерция» со стороны веб-сервиса необходимо отправить запрос, содержащий требуемые параметры и подпись, на рабочий URL ECommPay и принять оповещение о результате выплаты. Полная схема проведения выплаты представлена далее.
Рис.: Проведение выплаты через Gate
- Пользователь на стороне веб-сервиса инициирует выплату через сервис «Мобильная коммерция».
- От веб-сервиса на заданный URL ECommPay передаётся запрос на проведение выплаты через Gate.
- Запрос на проведение выплаты поступает в платёжную платформу.
- Выполняется начальная обработка запроса, в рамках которой обеспечивается проверка наличия обязательных параметров и корректной подписи.
- От платёжной платформы к веб-сервису направляется ответ с информацией о получении запроса и его корректности. Подробнее см. в разделе Формат ответа.
- В платёжной платформе выполняются дальнейшая обработка запроса и его отправка в сервис «Мобильная коммерция».
- На стороне сервиса «Мобильная коммерция» выполняется обработка платежа.
- От «Мобильная коммерция» к платёжной платформе направляется оповещение о результате.
- От платёжной платформы к веб-сервису направляется оповещение о результате.
- От веб-сервиса пользователю направляется результат выплаты.
Информация о формате запросов и параметрах инициации выплат методом «Мобильная коммерция» через Gate, а также о формате оповещений о результатах выплат приведена далее, общая информация о работе с API см. в разделе Работа с API.
Формат запросов
При работе с запросами на выплаты с применением метода «Мобильная коммерция» необходимо учитывать следующее:
- Должен использоваться запрос /v2/payment/mobile/payout, отправляемый методом POST.
- В запросе должны использоваться следующие объекты и параметры:
- general — объект, содержащий основные идентификационные сведения запроса:
- project_id — идентификатор проекта, полученный от ECommPay при интеграции;
- payment_id — идентификатор платежа, уникальный в рамках проекта;
- signature — подпись запроса, составленная после указания целевых параметров (подробнее — в разделе Использование подписи к данным);
- customer — объект, содержащий сведения о пользователе:
- id — идентификатор,
- ip_address — используемый IP-адрес;
- first_name* — имя;
- last_name* — фамилия;
- account — объект, содержащий сведения о счёте пользователя:
- number — номер телефона, на счёт которого совершается выплата, номер указывается с кодом страны, без знаков пунктуации и специальных символов (например,
79031234567
), подробнее о формате можно почитать в ответах на вопросы; - bank_id* — идентификатор мобильного оператора; далее в таблице указаны соответствия значений параметра и мобильных операторов:
Табл. 2. Идентификаторы мобильных операторов Мобильный оператор bank_id MTN 611 M-Pesa 640 Tigo 612 Vodafone 613
- number — номер телефона, на счёт которого совершается выплата, номер указывается с кодом страны, без знаков пунктуации и специальных символов (например,
- payment — объект, содержащий сведения о платеже:
- amount — сумма платежа в минорных единицах валюты,
- currency — валюта платежа в формате ISO-4217 alpha-3.
Прим.: * Данные параметры не являются обязательными для всех мобильных операторов. За более подробной информацией следует обращаться к курирующему менеджеру ECommPay. - general — объект, содержащий основные идентификационные сведения запроса:
- Валютой платежа может быть любая, указанная в таблице Характеристика.
- Дополнительно могут использоваться все параметры, указанные в спецификации.
Таким образом, корректный запрос на выплату с применением метода «Мобильная коммерция» должен содержать идентификаторы проекта и платежа, подпись, идентификатор и IP-адрес пользователя, номер телефона (для зачисления средств), валюту и сумму платежа:
Рис.: Пример запроса на выплату
{ "general": { "project_id": 35, "payment_id": "payout_65", "signature": "akchavu5w7v8vwg467Zie3x/wG8JuRey87Q4Oyb3FzF+2uWs1KaaWIHa NUPcN4sF6x4Um+K4SAyamNnFVg==" }, "customer": { "id": "user45", "ip_address": "1.2.3.4" }, "account": { "number": "79121234567" }, "payment": { "amount": 10000, "currency": "RUB" } }
Формат оповещений
Для оповещений о результатах выплат с применением метода «Мобильная коммерция» используется стандартный формат, описание которого представлено в разделе Оповещения.
В следующем примере оповещение свидетельствует о том, что в рамках проекта 25
для пользователя 1000000000946308
была успешно проведена выплата в размере 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": "test 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": "test 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 (Old Dashboard)
- как единичную выплату — в этом случае для каждой выплаты необходимо указать доступные для данного метода валюту и сумму, выбрать метод и заполнить все поля, отображаемые в интерфейсе с учётом выбранного метода;
- в рамках массового платежа — в этом случае все параметры выплат необходимо задать в файле формата CSV с учётом требований, представленных в разделе Выплаты через Gate (кроме пункта о подписи).
Информация о проведении выплат отображается в разделе Платежи интерфейса Dashboard (Old Dashboard).
Более подробная информация о проведении выплат через Dashboard (Old Dashboard) представлена в разделе Проведение выплат.
Тестирование
Общая информация
Для метода «Мобильная коммерция» доступно тестирование оплат через Payment Page и Gate, а также выплат через Gate.
Тестирование может выполняться в рамках тестового проекта, и для подключения и отключения этой функциональности необходимо обращаться к специалистам технической поддержки ECommPay support@ecommpay.com.
При проведении тестовых платежей следует учитывать, что в запросах должен указываться идентификатор тестового проекта, в качестве валюты может использоваться только RUB, а интерфейс эмулятора платёжной формы Payment Page может отличаться от рабочего.
Статусы тестовых платежей
При тестировании оплат их итоговые статусы определяются исходя из сумм, указанных в запросах:
decline
— при указании суммы40000
или40400
,success
— при указании любой другой суммы.
decline
— при указании суммы40000
или40400
,success
— при указании любой другой суммы.
Оплаты через Payment Page
Для проведения тестовой оплаты через Payment Page необходимо:
- Отправить в платёжную платформу корректный тестовый запрос на открытие Payment Page.
- Если в запросе не был указан метод
mobile
— выбрать метод «Мобильная коммерция» на странице эмулятора. - Указать в поле ввода произвольный номер телефона (из 10 цифр) и щёлкнуть кнопку Оплатить.
- Убедиться в запуске обратного отсчёта времени и в отображении информации о результате оплаты по истечении 20 секунд.
- Принять оповещение с информацией о результате оплаты.
Подробная информация о проведении оплат с использованием метода «Мобильная коммерция» через Payment Page представлена в пункте Оплаты через Payment Page.
Оплаты через Gate
Для проведения тестовой оплаты через Gate необходимо отправить в платёжную платформу корректный тестовый запрос и принять оповещение с информацией о результате. Подробная информация о проведении оплат с использованием метода «Мобильная коммерция» через Gate представлена в пункте Оплаты через Gate.Выплаты через Gate
Для проведения тестовой выплаты через Gate необходимо отправить в платёжную платформу корректный тестовый запрос и принять оповещение с информацией о результате. Подробная информация о проведении выплат с использованием метода «Мобильная коммерция» через Gate представлена в пункте Выплаты через Gate.
Анализ результатов проведения платежей
Как и при работе с другими платёжными методами, которые предоставляет ECommPay, при использовании метода «Мобильная коммерция» доступны разные способы анализа информации о платежах и операциях с применением этого метода — как в отдельности, так и в совокупности с другими методами.
Всю необходимую информацию можно получать и анализировать средствами Dashboard (Old Dashboard), в том числе с помощью аналитических панелей на вкладке Analytics.
Также можно выгружать нужную информацию для последующего анализа с помощью специализированных аналитических средств сторонних разработчиков:
- Dashboard (Old Dashboard) позволяет выгружать данные в форматах CSV и XLS с помощью инструментов на вкладке Платежи. При этом можно выполнять разовые выгрузки информации на локальный компьютер и задействовать периодическую выгрузку и отправку информации на заданные адреса электронной почты.
- Data API позволяет получать информацию в формате JSON и отправлять ее на заданный URL — для этого применяются запросы /operations/get.
С любыми вопросами о возможностях анализа можно обращаться в службу технической поддержки ECommPay.