«Мобильная коммерция»

Обзор

«Мобильная коммерция» — платёжный метод для проведения платежей по номеру телефона пользователя. Оплаты осуществляются через Payment Page и Gate, выплаты — через Gate и Dashboard (Old Dashboard).

Характеристика

Тип платёжного метода мобильная коммерция
Регионы использования

GH, KE, KZ, RU

подробная информация об ограничениях для мобильных операторов представлена в таблице Поддерживаемые мобильные операторы и их ограничения

Валюты платежей

GHS, KES, KZT, RUB

подробная информация об ограничениях для мобильных операторов представлена в таблице Поддерживаемые мобильные операторы и их ограничения

Конвертация валют
Оплаты +
Выплаты + (доступны не для всех мобильных операторов)
Оплаты по сохранённым данным
Полные возвраты
Частичные возвраты
Опротестования
Особенности
Организация и стоимость подключения по согласованию с курирующим менеджером ECommPay

Схема работы

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

Основные операции

Интерфейсы Время**
Payment Page CMS Plug-ins Gate Dashboard (Old Dashboard) базовое предельное
Оплаты + + * *
Выплаты + + * *

* Информацию необходимо уточнять у курирующего менеджера ECommPay.

** Базовое и предельное время определяются следующим образом:

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

Сценарии использования

Проведение оплат осуществляется со счёта мобильного телефона пользователя, проведение выплат — на счёт мобильного телефона пользователя.

Рис.: Оплата через Payment Page

Рис.: Оплата через Gate



Рис.: Выплата через Gate



Поддержка со стороны мобильных операторов

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

Точный список поддерживаемых мобильных операторов и стран можно уточнить через запрос /v2/info/mobile/{operation_type}/list, отправляемому методом POST с использованием Gate API:
  • /v2/info/mobile/sale/list — для уточнения списка мобильных операторов и стран, поддерживающих проведение оплат;
  • /v2/info/mobile/payout/list — для уточнения списка мобильных операторов и стран, поддерживающих проведение выплат.
Табл. 1. Поддерживаемые мобильные операторы и их ограничения
Мобильный оператор Идентификатор Страны Валюты Суммы
минимум максимум
«Билайн» BEELINE RU, KZ RUB, KZT
  • Оплаты в России: 10,00 RUB
  • Выплаты в России: 1,00 RUB
  • Оплаты в Казахстане: 5,00 KZT
  • Оплаты в России: 15 000,00 RUB
  • Выплаты в России: 15 000,00 RUB
  • Оплаты в Казахстане: 60 000,00 KZT или 200 000,00 KZT *
«МТС» MTS RU RUB Оплаты и выплаты: 1,00 RUB
  • Оплаты: 14 999,00 RUB
  • Выплаты: 15 000,00 RUB
Tele2 TELE2 RU, KZ RUB, KZT
  • Оплаты и выплаты в России: 1,00 RUB
  • Оплаты в Казахстане: 5,00 KZT
  • Оплаты в России: 15 000,00 RUB
  • Выплаты в России: 14 999,00 RUB
  • Оплаты в Казахстане: 60 000,00 KZT или 200 000,00 KZT *
«МегаФон» MEGAFON RU RUB Оплаты и выплаты: 1,00 RUB
  • Оплаты: 15 000,00 RUB
  • Выплаты: 14 999,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

  1. Пользователь на стороне веб-сервиса инициирует оплату.
  2. От веб-сервиса на заданный URL ECommPay передаётся запрос на проведение оплаты через Payment Page.
  3. Запрос на проведение оплаты поступает в платёжную платформу.
  4. Выполняется начальная обработка запроса, в рамках которой обеспечивается проверка наличия обязательных параметров и корректной подписи.
  5. Осуществляется генерация Payment Page согласно настройкам проекта и параметрам вызова.
  6. Пользователю отображается сгенерированная платёжная форма.
  7. Пользователь выбирает для оплаты метод «Мобильная коммерция».
  8. Пользователю отображается форма для ввода номера телефона.
  9. Пользователь вводит номер телефона, с которого он хочет оплатить, и выбирает мобильного оператора.
  10. Запрос на проведение оплаты с использованием метода «Мобильная коммерция» поступает в платёжную платформу.
  11. Выполняются дальнейшая обработка запроса и его отправка в сервис «Мобильная коммерция».
  12. На стороне «Мобильная коммерция» выполняется обработка запроса на оплату.
  13. Пользователю отправляется СМС-сообщение с кодом подтверждения оплаты или отображается платёжная инструкция.
  14. Пользователь выполняет необходимые действия.
  15. На стороне сервиса «Мобильная коммерция» выполняется обработка платежа.
  16. Результат оплаты отображается пользователю в сервисе «Мобильная коммерция».
  17. Пользователь перенаправляется к Payment Page.
  18. От сервиса «Мобильная коммерция» к платёжной платформе направляется результат оплаты.
  19. От платёжной платформы к веб-сервису направляется оповещение о результате оплаты.
  20. От платёжной платформы к Payment Page направляется результат проведения оплаты.
  21. Результат оплаты отображается пользователю на Payment Page.

Информация о формате запросов и параметрах вызова Payment Page при работе с методом «Мобильная коммерция», а также о формате оповещений о результатах оплат приведена далее; общая информация о работе с API см. в разделе Описание Payment Page API.

Формат запросов

При формировании запросов на открытие платёжной формы с применением метода «Мобильная коммерция» необходимо учитывать следующее:

  1. Должен использоваться базовый минимум параметров — параметры, обязательные для любого платёжного метода:
    • project_id — идентификатор проекта, полученный от ECommPay при интеграции;
    • payment_id — идентификатор платежа, уникальный в рамках проекта;
    • payment_currency — валюта платежа в формате ISO-4217 alpha-3;
    • payment_amount — сумма платежа в минорных единицах;
    • customer_id — идентификатор пользователя в рамках проекта.
  2. Валютой платежа может быть любая, указанная в таблице Характеристика.
  3. Для предварительного выбора метода «Мобильная коммерция» необходимо указывать код платёжного метода в параметре force_payment_methodmobile.
  4. Если в запросе на открытие Payment Page используется параметр customer_phone, то номер телефона в значении параметра необходимо указывать с кодом страны, без знаков пунктуации и специальных символов (например, 79031234567).
  5. Дополнительно могут использоваться любые другие параметры из числа доступных для работы с Payment Page. Детальная информация обо всех параметрах приведена в разделе Параметры открытия платежной формы Payment Page.
  6. После определения всех параметров необходимо составить подпись. Подробную информацию см. в Работа с подписью к данным.

Таким образом, корректный запрос на открытие платёжной формы с применением метода «Мобильная коммерция» должен содержать идентификаторы проекта и платежа, а также валюту и сумму платежа и подпись:

    { payment_id: 'test936', 
      payment_amount: 25000, 
      payment_currency: 'KZT', 
      project_id: 1380, 
      customer_id: 'customer1',
      signature: "jhfdudu58dtdxtEEyvk1Y4HASCQ9vySO\/RLCvhtT4DqtVUkDJrOcZzUCwX6R\/ekpZhkIQg=="
    }

Дополнительные возможности

По умолчанию все мобильные операторы объединены в группу и отображаются при нажатии на кнопку «Мобильная коммерция», поэтому выбор мобильного оператора происходит в два этапа: пользователь выбирает метод, а затем выбирает мобильного оператора.

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

Для настройки предварительного выбора необходимо передавать в запросах на открытие Payment Page код платёжного метода в параметре force_payment_method и дополнительные параметры в объекте payment_methods_options. Объект payment_methods_options может содержать следующие параметры:
  • 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 с использованием метода «Мобильная коммерция» со стороны веб-сервиса необходимо:

  1. Отправить запрос, содержащий требуемые параметры и подпись, на рабочий URL ECommPay.
  2. Принять оповещение от платежной платформы ECommPay о результате оплаты.

Полная схема проведения оплаты представлена далее.

Рис.: Проведение оплаты через Gate

  1. Пользователь на стороне веб-сервиса инициирует оплату через «Мобильная коммерция».
  2. От веб-сервиса на заданный URL ECommPay передаётся запрос на проведение оплаты через Gate.
  3. Запрос на проведение оплаты поступает в платёжную платформу ECommPay.
  4. Выполняется начальная обработка запроса, в рамках которой обеспечивается проверка наличия обязательных параметров и корректной подписи.
  5. От платёжной платформы к веб-сервису направляется ответ с информацией о получении запроса и его корректности. Подробнее см. в разделе Формат ответа.
  6. В платёжной платформе выполняются дальнейшая обработка запроса и его отправка в сервис «Мобильная коммерция».
  7. На стороне «Мобильная коммерция» выполняется обработка запроса на оплату.
  8. Пользователю отправляется СМС-сообщение с кодом подтверждения оплаты. Этот шаг не является обязательным для некоторых мобильных операторов. В некоторых случаях пользователю необходимо указать код на стороне веб-сервиса, тогда со стороны веб-сервиса необходимо отправить запрос с кодом подтверждения в платёжную платформу.
  9. Пользователь выполняет необходимые действия.
  10. На стороне сервиса «Мобильная коммерция» выполняется обработка платежа.
  11. Пользователю отображается результат оплаты.
  12. От сервиса «Мобильная коммерция» к платёжной платформе направляется уведомление о результате оплаты.
  13. От платёжной платформы к веб-сервису направляется оповещение о результате оплаты.
  14. От веб-сервиса пользователю направляется результат оплаты.

Информация о формате запросов и параметрах инициации оплат методом «Мобильная коммерция» через Gate, а также о формате оповещений о результатах оплат приведена далее, общая информация о работе с API см. в разделе Работа с API.

Формат запросов

При работе с запросами на оплаты с применением метода «Мобильная коммерция» необходимо учитывать следующее:

  1. Должен использоваться запрос /v2/payment/mobile/sale, отправляемый методом POST.
  2. В запросе должны использоваться следующие объекты и параметры:
    • general — объект, содержащий основные идентификационные сведения запроса:
      • project_id — идентификатор проекта, полученный от ECommPay при интеграции;
      • payment_id — идентификатор платежа, уникальный в рамках проекта;
      • signature — подпись запроса, составленная после указания целевых параметров (подробнее — в разделе Использование подписи к данным);
    • customer — объект, содержащий сведения о пользователе:
      • id — идентификатор, уникальный в рамках проекта,
      • ip_address — используемый IP-адрес;
    • account — объект, содержащий сведения о счёте пользователя:
      • number — номер телефона для оплаты, указывается с кодом страны, без знаков пунктуации и специальных символов (например, 79031234567), подробнее о формате можно почитать в ответах на вопросы,
      • service_provider* — мобильный оператор пользователя,
    • payment — объект, содержащий сведения о платеже:
      • amount — сумма платежа в минорных единицах валюты,
      • currency — валюта платежа в формате ISO-4217 alpha-3,
      • description* — описание.
    Прим.: * Данные параметры не являются обязательными для всех мобильных операторов. Рекомендуется настроить реагирование на ситуации с необходимостью дополнения информации о платеже.
  3. Валютой платежа может быть любая, указанная в таблице Характеристика.
  4. Дополнительно могут использоваться все параметры, указанные в спецификации.

Таким образом, корректный запрос на оплату с применением метода «Мобильная коммерция» должен содержать идентификаторы проекта и платежа, подпись, 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

  1. Пользователь на стороне веб-сервиса инициирует выплату через сервис «Мобильная коммерция».
  2. От веб-сервиса на заданный URL ECommPay передаётся запрос на проведение выплаты через Gate.
  3. Запрос на проведение выплаты поступает в платёжную платформу.
  4. Выполняется начальная обработка запроса, в рамках которой обеспечивается проверка наличия обязательных параметров и корректной подписи.
  5. От платёжной платформы к веб-сервису направляется ответ с информацией о получении запроса и его корректности. Подробнее см. в разделе Формат ответа.
  6. В платёжной платформе выполняются дальнейшая обработка запроса и его отправка в сервис «Мобильная коммерция».
  7. На стороне сервиса «Мобильная коммерция» выполняется обработка платежа.
  8. От «Мобильная коммерция» к платёжной платформе направляется оповещение о результате.
  9. От платёжной платформы к веб-сервису направляется оповещение о результате.
  10. От веб-сервиса пользователю направляется результат выплаты.

Информация о формате запросов и параметрах инициации выплат методом «Мобильная коммерция» через Gate, а также о формате оповещений о результатах выплат приведена далее, общая информация о работе с API см. в разделе Работа с API.

Формат запросов

При работе с запросами на выплаты с применением метода «Мобильная коммерция» необходимо учитывать следующее:

  1. Должен использоваться запрос /v2/payment/mobile/payout, отправляемый методом POST.
  2. В запросе должны использоваться следующие объекты и параметры:
    • 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
    • payment — объект, содержащий сведения о платеже:
      • amount — сумма платежа в минорных единицах валюты,
      • currency — валюта платежа в формате ISO-4217 alpha-3.
    Прим.: * Данные параметры не являются обязательными для всех мобильных операторов. За более подробной информацией следует обращаться к курирующему менеджеру ECommPay.
  3. Валютой платежа может быть любая, указанная в таблице Характеристика.
  4. Дополнительно могут использоваться все параметры, указанные в спецификации.

Таким образом, корректный запрос на выплату с применением метода «Мобильная коммерция» должен содержать идентификаторы проекта и платежа, подпись, идентификатор и 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)

Для проведения выплат через 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 необходимо:

  1. Отправить в платёжную платформу корректный тестовый запрос на открытие Payment Page.
  2. Если в запросе не был указан метод mobile — выбрать метод «Мобильная коммерция» на странице эмулятора.
  3. Указать в поле ввода произвольный номер телефона (из 10 цифр) и щёлкнуть кнопку Оплатить.
  4. Убедиться в запуске обратного отсчёта времени и в отображении информации о результате оплаты по истечении 20 секунд.
  5. Принять оповещение с информацией о результате оплаты.

Подробная информация о проведении оплат с использованием метода «Мобильная коммерция» через 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.