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

Обзор

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

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

Тип платёжного метода мобильная коммерция
Регионы использования UA
Валюты платежей
Конвертация валют
Оплаты +
Выплаты +
Оплаты по сохранённым данным
Полные возвраты
Частичные возвраты
Опротестования
Особенности поддерживается работа со следующими операторами связи:
  • оплаты — Kyivstar
  • выплаты:
    • Kyivstar
    • lifecell
    • Vodafone
Организация и стоимость подключения по согласованию с курирующим менеджером ECommPay

Схема работы

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



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

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

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

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

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

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

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

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

Рис.: Оплата через Payment Page с подтверждением платежа через указание кода подтверждения или отправку ответного SMS-сообщения



Рис.: Оплата через Gate с подтверждением платежа через указание кода подтверждения



Рис.: Оплата через Gate с подтверждением платежа через отправку ответного SMS-сообщения



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



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

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

Табл. 1. Список операторов связи
Оператор связи ID
Kyivstar KYIVSTAR
lifecell LIFECELL
Vodafone VODAFONE

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

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

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

Для оплаты через Payment Page с использованием метода «Мобильная коммерция в Украине» со стороны веб-сервиса необходимо отправить запрос, содержащий требуемые параметры и подпись, на рабочий URL ECommPay и принять оповещение о результате оплаты. При этом метод «Мобильная коммерция в Украине» можно сделать предварительно выбранным (подробнее — в разделе Предварительный выбор платёжного метода).

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

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



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

  1. Пользователь на стороне веб-сервиса инициирует оплату.
  2. От веб-сервиса на заданный URL ECommPay передаётся запрос на проведение оплаты через Payment Page.
  3. Запрос на проведение оплаты поступает в платёжную платформу.
  4. Выполняется начальная обработка запроса, в рамках которой обеспечивается проверка наличия обязательных параметров и корректной подписи.
  5. Осуществляется подготовка Payment Page согласно настройкам проекта и параметрам вызова.
  6. Пользователю отображается платёжная форма.
  7. Пользователь выбирает для оплаты метод «Мобильная коммерция в Украине».
  8. Пользователю отображается форма для ввода номера телефона.
  9. Пользователь вводит номер телефона, с которого он хочет оплатить.
  10. Запрос на проведение оплаты с использованием метода «Мобильная коммерция в Украине» передаётся к платёжной платформе.
  11. Выполняются дальнейшая обработка запроса и его отправка в сервис провайдера.
  12. На стороне сервиса провайдера выполняется обработка запроса на оплату.
  13. От сервиса провайдера к платёжной платформе передаётся информация о необходимости подтверждения платежа.
  14. Информация о необходимости подтверждения платежа передаётся от платёжной платформы к Payment Page.
  15. На Payment Page пользователю отображается форма для ввода кода подтверждения.
  16. Со стороны сервиса провайдера пользователю отправляется SMS-сообщение с кодом подтверждения оплаты.
  17. Пользователь подтверждает платёж. Для подтверждения платежа пользователю необходимо либо указать полученный в SMS-сообщении код подтверждения на Payment Page, либо ответить на SMS-сообщение, полученное со стороны сервиса провайдера (шаг 16). В зависимости от выбранного способа выполняются следующие действия:
    • Способ 1 — подтверждение платежа через код подтверждения:
      • Пользователь указывает код подтверждения на Payment Page и подтверждает оплату. В соответствии с протоколом работы провайдера пользователю необходимо ввести код подтверждения в течение 15 минут. Повторная отправка кода со стороны провайдера невозможна.
      • Информация о подтверждении платежа передаётся от Payment Page к платёжной платформе.
      • Информация о подтверждении платежа передаётся от платёжной платформы к сервису провайдера.
    • Способ 2 — подтверждение платежа через ответное SMS-сообщение: пользователь отправляет ответное SMS-сообщение для подтверждения платежа, и информация о подтверждении передаётся напрямую в сервис провайдера. В этом случае проведение платежа продолжается с шага 18 без необходимости указания пользователем кода подтверждения на Payment Page, а после подтверждения и обработки платежа страница Payment Page с полем для ввода кода сменяется страницей с информацией о результате (шаг 22).
  18. На стороне провайдера выполняется обработка платежа.
  19. От сервиса провайдера к платёжной платформе направляется информация о результате оплаты.
  20. От платёжной платформы к веб-сервису направляется оповещение о результате оплаты.
  21. От платёжной платформы к Payment Page направляется информация о результате проведения оплаты.
  22. Информация о результате оплаты отображается пользователю на 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. Для предварительного выбора метода «Мобильная коммерция в Украине» необходимо указывать код платёжного метода в параметре force_payment_methodmobile.
  3. Если в запросе на открытие Payment Page используется параметр customer_phone, то номер телефона в значении параметра необходимо указывать с кодом страны и без знаков пунктуации и специальных символов (например, 3800971234567). При использовании этого параметра в запросе значение этого параметра отобразится пользователю в форме ввода номера телефона на Payment Page.
  4. Дополнительно могут использоваться любые другие параметры из числа доступных для работы с Payment Page. Детальная информация обо всех параметрах приведена в разделе Параметры открытия платежной формы Payment Page.
  5. После определения всех параметров необходимо составить подпись (подробнее).

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

    { 
      project_id: 12,
      payment_id: 'X03936', 
      payment_currency: 'UAH', 
      payment_amount: 1000, 
      customer_id: '123',
      signature: "kUi2x9dKHAVNU0FYldJrxRLCvhtT4DqtVUkDJrOcZzUCwX6R\/ekpZhkIQg=="
    }

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

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

Оповещение о результате оплаты может передаваться к веб-сервису даже в том случае, если в качестве подтверждения оплаты пользователь отправляет ответное SMS-сообщение провайдеру и платёжная платформа ECommPay не задействуется в процессе подтверждения платежа.

В следующем примере оповещение свидетельствует о том, что в рамках проекта 2664 для пользователя customer1 была успешно проведена оплата в размере 332,00 UAH с номера телефона 3800971234567.

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

{
        "project_id": 2664,
        "payment": {
            "id": "S0332_20200710_133159_73006807",
            "type": "purchase",
            "status": "success",
            "date": "2020-07-10T10:32:32+0000",
            "method": "mobile",
            "sum": {
                "amount": 33200,
                "currency": "UAH"
            },
            "description": "test"
        },
        "account": {
            "number": "3800971234567"
        },
        "customer": {
            "id": "customer1"
        },
        "operation": {
            "id": 711,
            "type": "sale",
            "status": "success",
            "date": "2020-07-10T10:32:32+0000",
            "created_date": "2020-07-10T10:31:59+0000",
            "request_id": "eaccec8fcdefa3c6e3825e...2d646369c1-00000001",
            "sum_initial": {
                "amount": 33200,
                "currency": "UAH"
            },
            "sum_converted": {
                "amount": 33200,
                "currency": "UAH"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 2223,
                "payment_id": "15943771212",
                "auth_code": ""
            }
        },
        "signature": "py7aBmHSdibbtc6ALYnPcQV7zkY...GQWeRRwlOMtKI6m+81aWvpEwQ=="
    }

В следующем примере оплата была отклонена.

Рис.: Пример данных из оповещения об отказе в проведении оплаты

{
        "project_id": 2664,
        "payment": {
            "id": "D0320_20200710_134338_67886731",
            "type": "purchase",
            "status": "decline",
            "date": "2020-07-10T10:43:51+0000",
            "method": "mobile",
            "sum": {
                "amount": 32000,
                "currency": "UAH"
            },
            "description": "test"
        },
        "account": {
            "number": "3800971234567"
        },
        "customer": {
            "id": "customer2"
        },
        "operation": {
            "id": 764,
            "type": "sale",
            "status": "decline",
            "date": "2020-07-10T10:43:51+0000",
            "created_date": "2020-07-10T10:43:38+0000",
            "request_id": "18bc2e7b37883c787d37...f5854ec75a4e1eff41874-00000001",
            "sum_initial": {
                "amount": 32000,
                "currency": "UAH"
            },
            "sum_converted": {
                "amount": 32000,
                "currency": "UAH"
            },
            "code": "20000",
            "message": "General decline",
            "provider": {
                "id": 2223,
                "payment_id": "15943778211",
                "auth_code": ""
            }
        },
        "signature": "2T6qRAdB2zPtWqLqmgvzNso1h...VUc1SIM419KlEIFSoQ=="
    }

Дополнительные материалы

Для организации работы с оплатами через Payment Page также могут быть полезны следующие материалы:

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

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

Для оплаты через Gate с использованием метода «Мобильная коммерция в Украине» со стороны веб-сервиса необходимо:

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

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

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



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

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

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

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

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

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

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

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

{
  "general": {
    "project_id": 382,
    "payment_id": "e16d0d998485698c652f96f6b2ff8826",
    "signature": "3zjYFqRhDsaTLF7FVv4yu+Zie3x/...wG8JuRey87Q4Oyb3FzF+2uWs1Ka"
  },
  "customer": {
    "id": "123",
    "ip_address": "66.249.79.102"
  },
  "payment": {
    "amount": 1000,
    "currency": "UAH"
  },
  "account": {
    "number": "3800971234567"
  }
}

Форматы оповещений и запросов для дополнения информации о платеже

Когда от платёжной платформы поступает оповещение о необходимости дополнения информации о платеже, для проведения такого платежа необходимо отправить POST-запрос с кодом подтверждения платежа к конечной точке /v2/payment/clarification и получить ответ о приёме этого запроса в обработку.

В оповещении содержится массив clarification_fields, содержащий в себе параметр confirmation_code — код подтверждения платежа, который пользователь получает в SMS-сообщении и указывает на стороне веб-сервиса.

Далее приведён фрагмент оповещения, содержащего название параметра для дополнения информации о платеже.

{
  "clarification_fields": [
    "confirmation_code"
  ],
}

Запрос для продолжения платежа с учётом дополнения данных отправляется методом POST к конечной точке /v2/payment/clarification и должен содержать следующие объекты и параметры:

  • general — объект, содержащий основные идентификационные сведения запроса:
    • project_id — идентификатор проекта, к которому относится проводимый платёж;
    • payment_id — идентификатор платежа, к которому относятся отправляемые данные;
    • signature — подпись, составленная после указания целевых параметров (подробнее — в разделе Работа с подписью к данным);
  • additional_data — объект с запрошенными данными:
    • confirmation_code — код подтверждения платежа, который пользователь указывает на стороне веб-сервиса.

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

{
  "general": {
    "project_id": 11,
    "payment_id": "EPr-bf14",
    "signature": "v7KNMpfogAthg1ZZ5D/aZAeb0VMdeR+CqghwSm...=="
  },
  "additional_data": {
    "confirmation_code": "12345"
  }
}

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

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

Оповещение о результате оплаты может передаваться к веб-сервису даже в том случае, если в качестве подтверждения оплаты пользователь отправляет ответное SMS-сообщение провайдеру и платёжная платформа ECommPay не задействуется в процессе подтверждения платежа.

В следующем примере оповещение свидетельствует о том, что в рамках проекта 2664 для пользователя customer1 была успешно проведена оплата в размере 332,00 UAH с номера телефона 3800971234567.

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

{
        "project_id": 2664,
        "payment": {
            "id": "S0332_20200710_133159_73006807",
            "type": "purchase",
            "status": "success",
            "date": "2020-07-10T10:32:32+0000",
            "method": "mobile",
            "sum": {
                "amount": 33200,
                "currency": "UAH"
            },
            "description": "test"
        },
        "account": {
            "number": "3800971234567"
        },
        "customer": {
            "id": "customer1"
        },
        "operation": {
            "id": 711,
            "type": "sale",
            "status": "success",
            "date": "2020-07-10T10:32:32+0000",
            "created_date": "2020-07-10T10:31:59+0000",
            "request_id": "eaccec8fcdefa3c6e3825e...2d646369c1-00000001",
            "sum_initial": {
                "amount": 33200,
                "currency": "UAH"
            },
            "sum_converted": {
                "amount": 33200,
                "currency": "UAH"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 2223,
                "payment_id": "15943771212",
                "auth_code": ""
            }
        },
        "signature": "py7aBmHSdibbtc6ALYnPcQV7zkY...GQWeRRwlOMtKI6m+81aWvpEwQ=="
    }

В следующем примере оплата была отклонена.

Рис.: Пример данных из оповещения об отказе в проведении оплаты

{
        "project_id": 2664,
        "payment": {
            "id": "D0320_20200710_134338_67886731",
            "type": "purchase",
            "status": "decline",
            "date": "2020-07-10T10:43:51+0000",
            "method": "mobile",
            "sum": {
                "amount": 32000,
                "currency": "UAH"
            },
            "description": "test"
        },
        "account": {
            "number": "3800971234567"
        },
        "customer": {
            "id": "customer2"
        },
        "operation": {
            "id": 764,
            "type": "sale",
            "status": "decline",
            "date": "2020-07-10T10:43:51+0000",
            "created_date": "2020-07-10T10:43:38+0000",
            "request_id": "18bc2e7b37883c787d37...f5854ec75a4e1eff41874-00000001",
            "sum_initial": {
                "amount": 32000,
                "currency": "UAH"
            },
            "sum_converted": {
                "amount": 32000,
                "currency": "UAH"
            },
            "code": "20000",
            "message": "General decline",
            "provider": {
                "id": 2223,
                "payment_id": "15943778211",
                "auth_code": ""
            }
        },
        "signature": "2T6qRAdB2zPtWqLqmgvzNso1h...VUc1SIM419KlEIFSoQ=="
    }

Дополнительные материалы

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

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

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

{
    "general": {
        "project_id": 35,
        "payment_id": "payout_65",
        "signature": "akchavu5w7v8vwg467Zie3x/wG8JuRey87Q4Oyb3FzF+2uWs1"
    },
    "customer": {
        "id": "user45",
        "ip_address": "66.249.79.102"
    },
    "account": {
        "number": "3800501234567",
        "service_provider": "VODAFONE"
    },
    "payment": {
        "amount": 1000,
        "currency": "UAH"
    }
}

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

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

В следующем примере оповещение свидетельствует о том, что в рамках проекта 2664 для пользователя customer1 была успешно проведена выплата в размере 101,00 UAH на счёт 3800501234567.

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

{
        "project_id": 2664,
        "payment": {
            "id": "S0101_20200710_140630_66147689",
            "type": "payout",
            "status": "success",
            "date": "2020-07-10T11:06:35+0000",
            "method": "mobile",
            "sum": {
                "amount": 10100,
                "currency": "UAH"
            },
            "description": "test"
        },
        "account": {
            "number": "3800501234567",
            "type": "VODAFONE"
        },
        "customer": {
            "id": "customer1"
        },
        "operation": {
            "id": 818,
            "type": "payout",
            "status": "success",
            "date": "2020-07-10T11:06:35+0000",
            "created_date": "2020-07-10T11:06:30+0000",
            "request_id": "c48b2cad0ff3775bc32717af...d0a2cac7d95cdfa2f-00000001",
            "sum_initial": {
                "amount": 10100,
                "currency": "UAH"
            },
            "sum_converted": {
                "amount": 10100,
                "currency": "UAH"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 2223,
                "payment_id": "15943791930",
                "auth_code": ""
            }
        },
        "signature": "7dXKXo0GyDcLQ8Et5t...r3xn+xL5RcpqjaxRi4pJlWA=="
    }

В следующем примере выплата была отклонена.

Рис.: Пример данных из оповещения об отказе в проведении выплаты

{
        "project_id": 2664,
        "payment": {
            "id": "D0246_20200710_141726_61240779",
            "type": "payout",
            "status": "decline",
            "date": "2020-07-10T11:17:37+0000",
            "method": "mobile",
            "sum": {
                "amount": 24600,
                "currency": "UAH"
            },
            "description": "test"
        },
        "account": {
            "number": "3800501234567",
            "type": "VODAFONE"
        },
        "customer": {
            "id": "customer2"
        },
        "operation": {
            "id": 847,
            "type": "payout",
            "status": "decline",
            "date": "2020-07-10T11:17:37+0000",
            "created_date": "2020-07-10T11:17:28+0000",
            "request_id": "19bbb72fa221998695b9858d2c6...5f3a538f7527a9-00000001",
            "sum_initial": {
                "amount": 24600,
                "currency": "UAH"
            },
            "sum_converted": {
                "amount": 24600,
                "currency": "UAH"
            },
            "code": "20000",
            "message": "General decline",
            "provider": {
                "id": 2223,
                "payment_id": "15943798538",
                "auth_code": ""
            }
        },
        "signature": "VMSdQC3zswwE4Vn2aqLG...DSFL41y1SbpwLTLFBg=="
    }

Дополнительные материалы

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

Выплаты через Dashboard (Old Dashboard)

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

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

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

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

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

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

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

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

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