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

Обзор

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

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

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

BI, CI, CM, GH, KE, KZ, RU, RW, UG, ZM

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

BIF, GHS, KES, KZT, RUB, RWF, UGX, USD, XAF, ZMW

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

Схема работы

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



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

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

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

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

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

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

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

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

Поддержка со стороны операторов

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

Табл. 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
Aitrtel AIRTEL GH, RW, UG GHS, RWF, UGX * *
Activ ACTIV KZ KZT Оплаты: 200,00 KZT Оплаты: 148 850,00 KZT
Altel ALTEL KZ KZT Оплаты: 5,00 KZT Оплаты: 60 000,00 KZT или 200 000,00 KZT *
Econet ECONET BI BIF, USD * *
Kcell KCELL KZ KZT Оплаты: 200,00 KZT Оплаты: 148 850,00 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. Описание шагов

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

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

При обработке запроса на оплату для подтверждения платежа в зависимости от специфики сервиса оператора связи может использоваться один из следующих способов:

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

Для обеспечения подобных процедур используется возможность дополнения информации о платеже (подробнее).

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

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

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

  1. Должен использоваться базовый минимум параметров — параметры, обязательные для любого платёжного метода:
    • project_id — идентификатор проекта, полученный от ECommPay при интеграции;
    • payment_id — идентификатор платежа, уникальный в рамках проекта;
    • customer_id — идентификатор пользователя, уникальный в рамках проекта;
    • payment_currency — код валюты платежа в формате ISO-4217 alpha-3;
    • payment_amount — сумма платежа в дробных единицах валюты.
  2. Валютой платежа может быть любая, указанная в таблице .
  3. Для предварительного выбора метода «Мобильная коммерция» необходимо указывать код mobile в параметре force_payment_method, а для предварительного выбора оператора мобильной связи или страны — дополнительно передавать объект payment_methods_options, содержащий следующие параметры:
    • enable_mobile_service — указатель предварительного выбора оператора связи и страны, следует передавать 1 при выборе оператора связи или страны на стороне веб-сервиса;
    • selected_operator — идентификатор выбранного оператора, в соответствии с таблицей Поддерживаемые мобильные операторы и их ограничения;
    • selected_country — код страны в формате ISO 3166-1 alpha-2.
  4. Дополнительно могут использоваться любые другие параметры из числа доступных для работы с Payment Page. Информация об этих параметрах приведена в разделе Параметры открытия платежной формы Payment Page.
  5. После определения всех параметров запроса необходимо составить подпись (подробнее).

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

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

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

Полная схема проведения оплаты выглядит следующим образом.

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

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

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

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

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

  1. Должен использоваться HTTP-POST-запрос к конечной точке /v2/payment/mobile/sale.
  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": "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"
        }
    ]

Формат оповещений

Для оповещений о результатах оплат с применением метода «Мобильная коммерция» используется типовой формат, описание которого представлено в разделе Оповещения.

В следующем примере в оповещении содержится информация о том, что в рамках проекта 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

  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 — идентификатор проекта;
      • payment_id — идентификатор платежа;
      • signature — подпись запроса, составленная после указания целевых параметров, подробнее — в разделе Использование подписи к данным;
    • customer — объект, содержащий сведения о пользователе:
      • id — идентификатор пользователя в веб-сервисе;
      • ip_address — IP-адрес;
      • first_name* — имя;
      • last_name* — фамилия;
    • account — объект, содержащий сведения о счёте пользователя:
      • number — номер телефона, на счёт которого совершается выплата, номер указывается с кодом страны, без знаков пунктуации и специальных символов (например, 79031234567), подробнее о формате можно почитать в ответах на вопросы;
      • service_provider* — идентификатор мобильного оператора пользователя,
    • payment — объект, содержащий сведения о платеже:
      • amount — сумма платежа в минорных единицах валюты,
      • currency — валюта платежа в формате ISO-4217 alpha-3.
    Прим.: * Данные параметры не являются обязательными для всех операторов мобильной связи. За более подробной информацией следует обращаться к курирующему менеджеру ECommPay.
  3. Валютой платежа может быть любая, указанная в таблице Характеристика.
  4. Дополнительно могут использоваться все параметры, указанные в спецификации.

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

Рис.: Пример запроса на выплату

{
    "general": {
        "project_id": 35,
        "payment_id": "payout_65",
        "signature": "akchavu5w7v8vwg467Zie3x/wG8JuRey87Q4Oyb3FzF+2uWs1KaaWIHa
                                                 NUPcN4sF6x4Um+K4SAyamNnFVg=="
    },
    "customer": {
        "id": "customer_45",
        "ip_address": "1.2.3.4"
    },
    "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 (Old Dashboard)

Для проведения выплат через Dashboard (Old Dashboard) со стороны мерчанта необходимо инициировать запросы на выплаты и принять уведомления об их успешной обработке. Инициировать такие выплаты можно двумя способами:
  • как единичную выплату — в этом случае для каждой выплаты необходимо указать доступные для данного метода валюту и сумму, выбрать метод и заполнить все поля, отображаемые в интерфейсе с учётом выбранного метода;
  • в рамках массового платежа — в этом случае все параметры выплат необходимо задать в файле формата CSV с учётом требований, представленных в разделе Выплаты через Gate (кроме пункта о подписи).

Информация о проведении выплат отображается в разделе Платежи интерфейса Dashboard (Old Dashboard).

Более подробная информация о проведении выплат через Dashboard (Old Dashboard) представлена в разделе Проведение выплат.

Тестирование

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

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

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

Статусы тестовых платежей

Итоговые статусы тестовых оплат определяются исходя из сумм, указанных в запросах:

  • decline — при указании суммы 40000 или 40400,
  • success — при указании любой другой суммы.

Итоговые статусы тестовых выплат определяются исходя из сумм, указанных в запросах:

  • decline — при указании суммы 40000 или 40400,
  • success — при указании любой другой суммы.

Оплаты через Payment Page

Для проведения тестовой оплаты через Payment Page необходимо:

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

Информация о проведении оплат с использованием метода «Мобильная коммерция» через Payment Page представлена в пункте Оплаты через Payment Page этой статьи.

Оплаты через Gate

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

Выплаты через Gate

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

Анализ результатов проведения платежей

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

Всю необходимую информацию можно получать и анализировать средствами Dashboard (Old Dashboard), в том числе с помощью аналитических панелей в разделе Аналитика.

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

  • Dashboard (Old Dashboard) позволяет выгружать данные в формате CSV с помощью инструментов в разделе Отчёты. При этом можно выполнять разовые и периодические выгрузки информации на локальный компьютер.
  • Data API позволяет получать информацию в формате JSON и отправлять ее на заданный URL — для этого применяются запросы к конечной точке /operations/get.

С любыми вопросами о возможностях анализа результатов можно обращаться в службу технической поддержки ECommPay.