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

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

Схема работы

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

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

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

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

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

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

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

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

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

Рис.: Возврат через Gate

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

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

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

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

* Данные ограничения следует уточнять у курирующего менеджера 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 с использованием метода «Мобильная коммерция» со стороны веб-сервиса необходимо отправить запрос, содержащий требуемые параметры и подпись, на рабочий URL ECommPay и принять оповещение о результате оплаты. При этом метод «Мобильная коммерция» можно сделать предварительно выбранным (подробнее — в разделе Предварительный выбор платёжного метода). Полная схема проведения оплаты выглядит следующим образом.

По умолчанию при работе с этим методом пользователь выбирает сначала метод «Мобильная коммерция», а затем — оператора мобильной связи. Вместе с тем, в платёжной платформе 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. После определения всех параметров запроса необходимо составить подпись (подробнее).

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

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

{
    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=="
}

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

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

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

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

В других случаях (с учётом особенностей работы сервисов операторов связи) для подтверждения платежа пользователю необходимо не указывать проверочный код, а выполнять иные действия, в соответствии с платёжной инструкцией. Данные для отображения такой инструкции отправляются от платёжной платформы к веб-сервису в оповещении с массивом display_data, в котором содержатся объекты со следующими параметрами:

• type — тип передаваемых данных (в значении всегда передаётся add_info);
• title — язык платёжной инструкции;
• data — текст платёжной инструкции (при передаче значения en в параметре title текст указывается на английском, при значении ru — на русском).

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

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

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

В следующем примере в оповещении содержится информация о том, что в рамках проекта 382 проведена оплата в размере 800,00 RUB со счёта мобильной связи пользователя с номером телефона 79821234567.

 {
        "customer": {
            "id": "sc-997741"
        },
        "payment": {
            "date": "2019-10-18T07:30:50+0000",
            "id": "e16d0d998485698c652f96f6b2ff8826",
            "method": "mobile",
            "status": "success",
            "sum": {
                "amount": 80000,
                "currency": "RUB"
            },
            "type": "purchase",
            "account": {
                "number": "79821234567"
            },
            "description": ""
        },
        "project_id": 382,
        "operation": {
            "id": 7375000008886,
            "type": "sale",
            "status": "success",
            "date": "2019-10-18T07:30:50+0000",
            "created_date": "2019-10-18T07:29:08+0000",
            "request_id": "83a47d9a5f5677b55fe534d9a9c0335a18-00007376",
            "sum_initial": {
                "amount": 80000,
                "currency": "RUB"
            },
            "sum_converted": {
                "amount": 80000,
                "currency": "RUB"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 1078,
                "payment_id": "118665991",
                "auth_code": ""
            }
        },
        "account": {
            "type": "MTS"
        },
        "signature": "gf5CBRhCgltRUoXMUJ38qX/TK1fowqyrIQoqy76z1x5B9jwOkuJcrVEA=="
    }
}

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

{
        "project_id": 981,
        "payment": {
            "id": "93688696",
            "type": "purchase",
            "status": "decline",
            "date": "2019-10-18T07:32:26+0000",
            "method": "mobile",
            "sum": {
                "amount": 30000,
                "currency": "RUB"
            },
            "description": ""
        },
        "account": {
            "number": "79051234567",
            "type": "BEELINE"
        },
        "customer": {
            "id": "1028232202"
        },
        "operation": {
            "id": 29839000009286,
            "type": "sale",
            "status": "decline",
            "date": "2019-10-18T07:32:26+0000",
            "created_date": "2019-10-18T07:08:26+0000",
            "request_id": "8ff0457e32ad81b524a807d7a307ffa9ae8f03aadb0b-00029840",
            "sum_initial": {
                "amount": 30000,
                "currency": "RUB"
            },
            "sum_converted": {
                "amount": 30000,
                "currency": "RUB"
            },
            "code": "20105",
            "message": "Insufficient funds on customer account",
            "provider": {
                "id": 1078,
                "payment_id": "118662791",
                "auth_code": ""
            }
        },
        "signature": "ZdfYgsg02Mhd1c/OK8v2s3rnFr7I+2uqIZCQ5Kc9Pr/qXZcGUyIvyu3
                                           8yF0F7ZudmdYY3Thzh6Fpj9/kKHTWKQ=="
    }
}

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

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

• Организация взаимодействия
• Модель проведения платежей
• Работа с подписью к данным
• Информация об операциях

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

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

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

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

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

1. Должен использоваться запрос /v2/payment/mobile/refund, отправляемый методом POST.
2. В запросе должны использоваться следующие объекты и параметры:
   • general — объект, содержащий основные идентификационные сведения о запросе:
     • project_id — идентификатор проекта;
     • payment_id — идентификатор платежа;
     • signature — подпись запроса, составленная после указания целевых параметров (подробнее — в разделе Использование подписи к данным);
   • payment — объект, содержащий сведения о возврате:
     • description — комментарий или описание возврата.
3. Дополнительно могут использоваться все параметры, указанные в спецификации.

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

{
  "general": {
    "project_id": 9999,
    "payment_id":"Test-refund-001",
    "signature": "52D7C03EA096CAB4F271F12FE96EBE3D47F5F0EC4280509D293D1094AA793BBC"
  },
  "payment": {
    "description": "Test refund"
  }
}

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

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

В следующем примере оповещение свидетельствует о том, что в рамках проекта 386 был успешно проведён возврат в размере 1,00 RUB.

{
    "project_id": 386,
    "payment": {
        "id": "ORDER_104149_36884701",
        "type": "purchase",
        "status": "refunded",
        "date": "2021-03-18T07:42:02+0000",
        "method": "mobile",
        "sum": {
            "amount": 0,
            "currency": "RUB"
        },
        "description": ""
    },
    "account": {
        "number": "1234"
    },
    "operation": {
        "id": 919,
        "type": "refund",
        "status": "success",
        "date": "2021-03-18T07:42:02+0000",
        "created_date": "2021-03-18T07:41:59+0000",
        "request_id": "ac1142f91e68eaacdc70a90b...5bd22a75dbffe10-00000001",
        "sum_initial": {
            "amount": 100,
            "currency": "RUB"
        },
        "sum_converted": {
            "amount": 100,
            "currency": "RUB"
        },
        "code": "0",
        "message": "Success",
        "provider": {
            "id": 2993,
            "payment_id": "6ad094c24bdfab6b4ffd7e25765fd77c",
            "auth_code": "",
            "date": "2021-03-18T07:42:01+0000"
        }
    },
    "signature": "iO4ywLw3OKHFrgklqilnzIHrSPbEf..wc2NTkrgKU4LMCrZ8itl/LiMA=="
}

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

{
    "project_id": 386,
    "payment": {
        "id": "ORDER_15989542",
        "type": "purchase",
        "status": "success",
        "date": "2021-03-18T07:47:27+0000",
        "method": "mobile",
        "sum": {
            "amount": 31500,
            "currency": "RUB"
        },
        "description": ""
    },
    "account": {
        "***mber": "***9999"
    },
    "operation": {
        "id": 923,
        "type": "refund",
        "status": "decline",
        "date": "2021-03-18T07:47:27+0000",
        "created_date": "2021-03-18T07:47:25+0000",
        "request_id": "e22cb890d5a9b67ff7f4a97...a6248b988ad6579b30-00000001",
        "sum_initial": {
            "amount": 31500,
            "currency": "RUB"
        },
        "sum_converted": {
            "amount": 31500,
            "currency": "RUB"
        },
        "code": "20000",
        "message": "General decline",
        "provider": {
            "id": 2993,
            "payment_id": "e1c792fb5aa16b32e1c1d751f96d3129",
            "auth_code": ""
        }
    },
    "signature": "T0/7s1JZAcwWlypP5Xnhz...7aP4Z3pSlgzsCBwZaXgUOk1hkX6cJEQ=="
}

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

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

• Организация взаимодействия
• Работа с подписью к данным
• Модель проведения платежей
• Информация об операциях

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

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

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

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

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

1. Должен использоваться POST-запрос к конечной точке /v2/payment/mobile/payout.
2. В запросе должны использоваться следующие объекты и параметры:
   • general — объект, содержащий основные сведения о запросе:
     • project_id — идентификатор проекта, полученный от ECommPay при интеграции;
     • 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. Дополнительно могут использоваться все параметры, указанные в спецификации.

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

{
    "general": {
        "project_id": 35,
        "payment_id": "payout_65",
        "signature": "akchavu5w7v8vwg467Zie3x/wG8NUPcN4sF6x4Um+K4SAyamNnFVg=="
    },
    "customer": {
        "id": "customer_45",
        "ip_address": "127.0.0.1"
    },
    "account": {
        "number": "79123456789",
        "service_provider": "MTN"
    },
    "payment": {
        "amount": 10000,
        "currency": "KZT"
    }
}

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

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

В следующем примере в оповещении содержится информация о том, что в рамках проекта 25 была проведена выплата в размере 724,00 KZT на счёт мобильной связи пользователя с номером телефона 79891234567.

{
        "sum_request": {
            "amount": 72400,
            "currency": "KZT"
        },
        "request_id": "f7cf554411e67d2598159361644bc02ba08f4d64-00063844",
        "transaction": {
            "id": 63843000000321,
            "date": "2019-10-31T07:00:08+0000",
            "type": "payout"
        },
        "payment": {
            "id": "13614419800",
            "method": "mobile",
            "date": "2019-10-31T07:00:08+0000",
            "result_code": "0",
            "result_message": "Success",
            "status": "success",
            "is_new_attempts_available": false,
            "attempts_timeout": 0,
            "cascading_with_redirect": false,
            "provider_id": 14
        },
        "sum_real": {
            "amount": 72400,
            "currency": "KZT"
        },
        "customer": {
            "id": "1000000000946308"
        },
        "account": {
            "number": "79891234567"
        },
        "rrn": "",
        "general": {
            "project_id": 25,
            "payment_id": "13614419800",
            "signature": "efy09xOugbWMreW0T6I3VCz7rlRCqHTA2SiIm4X2H0fl804sB3VDZPEdK7r0
                                                          O/kR349nj7KcokTGpi23kiJlQ=="
        },
        "description": "payout",
        "operations": [
            {
                "id": 63843000000371,
                "type": "payout",
                "status": "success",
                "date": "2019-10-31T07:00:08+0000",
                "processing_time": null,
                "request_id": "f7cf554411e67d2598159361644bc02ba08f4d64-00063844",
                "sum": {
                    "amount": 72400,
                    "currency": "KZT"
                },
                "code": "0",
                "message": "Success"
            }
        ]
    }

В следующем примере содержится информация об отклонении выплаты из-за недоступности аккаунта пользователя.

{
        "sum_request": {
            "amount": 650000,
            "currency": "KZT"
        },
        "request_id": "647c8ea772328e5df288344b5e6c57b207fda92-00013521",
        "transaction": {
            "id": 13520000009331,
            "date": "2019-10-31T08:44:02+0000",
            "type": "payout"
        },
        "payment": {
            "id": "13612847900",
            "method": "mobile",
            "date": "2019-10-31T08:44:02+0000",
            "result_code": "20106",
            "result_message": "Customer account is no longer available",
            "status": "decline",
            "is_new_attempts_available": false,
            "attempts_timeout": 0,
            "cascading_with_redirect": false,
            "provider_id": 14
        },
        "sum_real": {
            "amount": 650000,
            "currency": "KZT"
        },
        "customer": {
            "id": "1000000000930682"
        },
        "account": {
            "number": "79531234567"
        },
        "rrn": "",
        "general": {
            "project_id": 131,
            "payment_id": "13612847900",
            "signature": "V5bloYlpjQrL9PUBUJug9i8jb30vdC411W/le6AFZXLUuX5HQH1zYxWe
                                                 4n2hAj0CSM1Ew/HuQ8ivuLOFwEpJ2A=="
        },
        "description": "payout",
        "operations": [
            {
                "id": 13520000010671,
                "type": "payout",
                "status": "decline",
                "date": "2019-10-31T08:44:02+0000",
                "processing_time": null,
                "request_id": "647c8ea772328e51c289ea2a5387157b207fda92-00013521",
                "sum": {
                    "amount": 650000,
                    "currency": "KZT"
                },
                "code": "20106",
                "message": "Customer account is no longer available"
            }
        ]
    }

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

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

• Организация взаимодействия
• Модель проведения платежей
• Работа с подписью к данным
• Информация об операциях

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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