«Платежи с использованием карт через партнёра (Узбекистан)»
Обзор
Платёжный метод, который позволяет проводить оплаты и выплаты с использованием платёжных карт через сервис партнёра. Оплаты осуществляются через Payment Page и Gate, выплаты — через Gate.
Характеристика
Тип платёжного метода | Платежи с использованием карт через партнёра |
---|---|
Регионы использования | UZ |
Валюты платежей | UZS |
Конвертация валют | – |
Оплаты | + |
Выплаты | + |
Оплаты по сохранённым данным | – |
Полные возвраты | – |
Частичные возвраты | – |
Опротестования | – |
Особенности | – |
Организация и стоимость подключения | По согласованию с курирующим менеджером ecommpay |
Схема работы
В проведении отдельного платежа с использованием данного метода задействуются веб-сервис мерчанта, один из интерфейсов и платёжная платформа ecommpay, а также технические средства партнёра.
Основные операции
Интерфейсы | Суммы, USD * | Время ** | ||||||
---|---|---|---|---|---|---|---|---|
Payment Page | CMS Plug-ins | Gate | Dashboard | минимум | максимум | базовое | предельное | |
Оплаты | + | – | + | – | – | – | – | – |
Выплаты | – | – | + | – | – | – | в пределах 20 минут | до 24 часов |
* Лимиты сумм платежей согласовываются с курирующим менеджером ecommpay.
- Базовое время — среднее расчётное время проведения платежа от момента его инициирования на стороне платёжной платформы до момента отправки инициатору оповещения о результате. Это время, определяемое для условий штатной работы всех технических средств и каналов связи, а также типичных действий со стороны пользователя (там, где они необходимы). Базовое время рекомендуется использовать для реагирования на отсутствие оповещений о результате платежа и выполнения опроса состояния платежа.
- Предельное время — максимально допустимое время проведения платежа от момента его инициирования на стороне платёжной платформы до момента отправки инициатору оповещения о результате. Если платёж не был проведён или отклонён за это время, он автоматически переводится в статус
decline
. Для индивидуальной настройки предельного времени следует обращаться к специалистам технической поддержки ecommpay.
Сценарии использования
Проведение оплат с использованием метода выполняется с перенаправлением пользователей к Telegram боту партнёра, проведение выплат — с уведомлением пользователей через веб-сервис мерчанта.
Рис.: Оплата через Payment Page
Рис.: Оплата через Gate
Рис.: Выплата через Gate
Детальные сведения о том, что необходимо делать со стороны мерчанта для проведения платежей, а также о том, что можно использовать для анализа информации о проведённых платежах и операциях, представлены далее.
Оплаты через Payment Page
Общая информация
Для оплаты через Payment Page с использованием данного метода со стороны веб-сервиса необходимо отправить запрос, содержащий требуемые параметры и подпись, на рабочий URL ecommpay и принять оповещение о результате оплаты. При этом метод можно сделать предварительно выбранным (подробнее — в разделе Предварительный выбор платёжных методов). Полная схема проведения оплаты представлена далее.
Рис.: Проведение оплаты через Payment Page
- Пользователь на стороне веб-сервиса инициирует оплату.
- От веб-сервиса на заданный URL ecommpay передаётся запрос на проведение оплаты через Payment Page.
- Запрос на проведение оплаты поступает в платёжную платформу.
- Выполняется начальная обработка запроса, в рамках которой обеспечивается проверка наличия обязательных параметров и корректной подписи.
- Осуществляется генерация Payment Page согласно настройкам проекта и параметрам вызова.
- Пользователю отображается сгенерированная платёжная форма.
- Пользователь выбирает для оплаты платёжный метод.
- Запрос на проведение оплаты поступает в платёжную платформу.
- Выполняются дальнейшая обработка запроса и его отправка в сервис партнёра.
- На стороне партнёра выполняется обработка запроса на оплату.
- От сервиса партнёра к платёжной платформе передаются данные для перенаправления пользователя к Telegram боту партнёра.
- Данные для перенаправления пользователя передаются к Payment Page.
- Пользователь перенаправляется к Telegram боту партнёра.
- Пользователь выполняет необходимые действия для оплаты.
- На стороне сервиса партнёра выполняется обработка платежа.
- Результат оплаты отображается пользователю в сервисе партнёра.
- Пользователь перенаправляется к Payment Page.
- От сервиса партнёра к платёжной платформе направляется результат оплаты.
- От платёжной платформы к веб-сервису направляется оповещение о результате оплаты.
- От платёжной платформы к Payment Page направляется результат проведения оплаты.
- Результат оплаты отображается пользователю на Payment Page.
Информация о формате запросов и параметрах вызова Payment Page при работе с данным методом, а также о формате оповещений о результатах оплат приведена далее; общая информация о работе с API см. в разделе Описание Payment Page API.
Формат запросов
При формировании запросов на открытие платёжной формы с применением метода необходимо учитывать следующее:
- Должен использоваться базовый минимум параметров — параметры, обязательные для любого платёжного метода:
- project_id — идентификатор проекта, полученный от ecommpay при интеграции;
- payment_id — идентификатор платежа, уникальный в рамках проекта;
- payment_currency — валюта платежа в формате ISO-4217 alpha-3;
- payment_amount — сумма платежа в минорных единицах;
- customer_id — идентификатор пользователя уникальный в рамках проекта.
- Валютой платежа может быть только UZS.
- Для предотвращения ошибок при перенаправлении к сервису партнёра рекомендуется использовать параметр payment_extra_param и указывать значение
uzcard
. - Для предварительного выбора метода необходимо указывать код платёжного метода в параметре force_payment_method —
card-partner
. - Дополнительно могут использоваться любые другие параметры из числа доступных для работы с Payment Page. Детальная информация обо всех параметрах приведена в разделе Параметры вызова платёжной формы.
- После определения всех параметров необходимо составить подпись. Подробную информацию см. в Работа с подписью к данным.
Таким образом, корректный запрос на открытие платёжной формы с применением метода должен содержать идентификаторы проекта, пользователя и платежа, валюту, сумму платежа и подпись, также рекомендуется передавать код uzcard
в параметре payment_extra_param:
EPayWidget.run( { payment_id: 'X03936', payment_amount: 10000, payment_currency: 'UZS', project_id: 198, customer_id: 'test1', payment_extra_param: 'uzcard', signature: "kUi2x9dKHAVNU0FYldJrxh4yoASCQ9vySO\/RLCvhafgqac34gwhq...==" } )
Формат оповещений
Для оповещений о результатах оплат с применением метода используется типовой формат, описание которого представлено в разделе Оповещения.
К особенностям данного платёжного метода можно отнести то, что в оповещениях о проведении оплаты в параметре number
объекта account
передаётся идентификатор использованной карты в сервисе партнёра, а в параметре masked_card
объекта provider_extra_fields
— маскированный номер этой карты. Поэтому в случаях, когда один пользователь использует разные карты, в этих параметрах передаются разные значения. Также стоит учитывать что идентификаторы карт могут использоваться при проведении выплат (в параметре number
объекта account
).
В следующем примере оповещение свидетельствует о том, что в рамках проекта 579
от пользователя 65465
была успешно проведена оплата в размере 1 000,00 UZS
.
Рис.: Пример оповещения о проведении оплаты
{ "project_id": 579, "payment": { "id": "307657677656546777", "type": "purchase", "status": "success", "date": "2019-10-08T14:13:50+0000", "method": "Card partner", "sum": { "amount": 100000, "currency": "UZS" }, "description": "" }, "customer": { "id": "65465" }, "account": { "number": "1743-3223966A2D...514183B2584F543" }, "provider_extra_fields": { "masked_card": "411111******1111" }, "operation": { "id": 9708000007271, "type": "sale", "status": "success", "date": "2019-10-08T14:13:50+0000", "created_date": "2019-10-08T14:02:18+0000", "request_id": "30d9d5d9d7966a8a74b44ba559b1a989f2cad321e2-00009709", "sum_initial": { "amount": 100000, "currency": "UZS" }, "sum_converted": { "amount": 100000, "currency": "UZS" }, "code": "0", "message": "Success", "provider": { "id": 1521, "payment_id": "632441", "auth_code": "", "date": "2019-10-08T14:02:19+0000" } }, "signature": "gh13skxTd+KkEUemF3KaFYyLCTiteYp5FhTJJWu+qdhbMYUyLSf/uICQ BC9enst71izQvQ670YIpSkL1nyO90WA==" } }
В следующем примере оплата была отклонена из-за недостатка средств на счёте пользователя.
Рис.: Пример оповещения об отказе в проведении оплаты
{ "project_id": 579, "payment": { "id": "307657677656546777", "type": "purchase", "status": "decline", "date": "2019-10-08T14:13:50+0000", "method": "Card partner", "sum": { "amount": 100000, "currency": "UZS" }, "description": "" }, "customer": { "id": "65465" }, "account": { "number": "1743-3223966A2D...514183B2584F543" }, "provider_extra_fields": { "masked_card": "411111******1111" }, "operation": { "id": 9708000007271, "type": "sale", "status": "decline", "date": "2019-10-08T14:13:50+0000", "created_date": "2019-10-08T14:02:18+0000", "request_id": "30d9d5d9d7966a8a74b44ba559b1a989f2cad321e2-00009709", "sum_initial": { "amount": 100000, "currency": "UZS" }, "sum_converted": { "amount": 100000, "currency": "UZS" }, "code": "20105", "message": "Insufficient funds on customer account", "provider": { "id": 1521, "payment_id": "632441", "auth_code": "", "date": "2019-10-08T14:02:19+0000" } }, "signature": "gh13skxTd+KkEUemF3KaFYyLCTiteYp5FhTJJWu+qdhbMYUyLSf/uICQ BC9enst71izQvQ670YIpSkL1nyO90WA==" } }
Дополнительные материалы
Для организации работы с оплатами через Payment Page также могут быть полезны следующие материалы:
Оплаты через Gate
Общая информация
Для оплаты через Gate с использованием метода со стороны веб-сервиса необходимо:
- Отправить запрос, содержащий требуемые параметры и подпись, на рабочий URL ecommpay.
- Осуществить перенаправление к Telegram боту партнёра.
- Принять оповещение от платежной платформы ecommpay о результате оплаты.
Полная схема проведения оплаты представлена далее.
Рис.: Проведение оплаты через Gate
- Пользователь на стороне веб-сервиса инициирует оплату через партнёра.
- От веб-сервиса на заданный URL ecommpay передаётся запрос на проведение оплаты через Gate.
- Запрос на проведение оплаты поступает в платёжную платформу ecommpay.
- Выполняется начальная обработка запроса, в рамках которой обеспечивается проверка наличия обязательных параметров и корректной подписи.
- От платёжной платформы к веб-сервису направляется ответ с информацией о получении запроса и его корректности. Подробнее см. в разделе Формат ответа.
- В платёжной платформе выполняются дальнейшая обработка запроса и его отправка в сервис партнёра.
- На стороне партнёра выполняется обработка запроса на оплату.
- От сервиса партнёра к платёжной платформе передаются данные для перенаправления пользователя на сайт партнёра.
- От платёжной платформы к веб-сервису направляется оповещение с данными для перенаправления пользователя к Telegram боту партнёра в объекте redirect_data.
- Пользователь перенаправляется к Telegram боту партнёра.
- Пользователь выполняет необходимые действия для оплаты.
- На стороне сервиса партнёра выполняется обработка платежа.
- Пользователю отображается результат оплаты.
- Пользователь перенаправляется к веб-сервису.
- От сервиса партнёра к платёжной платформе направляется уведомление о результате оплаты.
- От платёжной платформы к веб-сервису направляется оповещение о результате оплаты.
- От веб-сервиса пользователю направляется результат оплаты.
Информация о формате запросов и параметрах инициации оплат методом через Gate, а также о формате оповещений о результатах оплат приведена далее, общая информация о работе с API см. в разделе Работа с API.
Формат запросов
При работе с запросами на оплаты с применением метода необходимо учитывать следующее:
- Должен использоваться запрос v2/payment/card-partner/sale, отправляемый методом POST.
- В запросе должны использоваться следующие объекты и параметры:
- general — объект, содержащий основные идентификационные сведения запроса:
- project_id — идентификатор проекта, полученный от ecommpay при интеграции;
- payment_id — идентификатор платежа, уникальный в рамках проекта;
- signature — подпись запроса, составленная после указания целевых параметров (подробнее — в разделе Использование подписи к данным);
- customer — объект, содержащий сведения о пользователе:
- id — идентификатор, уникальный в рамках проекта
- ip_address — используемый IP-адрес;
- payment — объект, содержащий сведения о платеже:
- amount — сумма платежа в минорных единицах валюты,
- currency — валюта платежа в формате ISO-4217 alpha-3,
- extra_param — дополнительный параметр. Для оплаты через партнёра в Узбекистане необходимо передать код
uzcard
.
- general — объект, содержащий основные идентификационные сведения запроса:
- Валютой платежа может быть только UZS.
- Дополнительно могут использоваться все параметры, указанные в спецификации.
Таким образом, корректный запрос на оплату с применением метода должен содержать идентификаторы проекта и платежа, подпись, данные пользователя и платежа:
Рис.: Пример запроса на оплату
{ "general": { "project_id": 198, "payment_id": "561719496", "signature": "fCkXYCxiTjiN9AkFvEZCpbe/a+wKKMv4i4BmNB2sVcrW0r3...==" }, "customer": { "id": "customer_test", "ip_address": "1.2.3.4" }, "payment": { "amount": 10000, "currency": "UZS", "extra_param": "uzcard" } }
Форматы данных для перенаправления пользователей
Для перенаправления пользователя от веб-сервиса на сайт сервиса партнёра необходимо принять оповещение от платёжной платформы, содержащее ссылку для перенаправления в параметре redirect_data.url и данные для отправки в теле запроса redirect_data.body, и использовать эти параметры для открытия аккаунта Telegram бота методом, указанным в redirect_data.method.
Далее приведён фрагмент оповещения, содержащего данные для перенаправления.
"redirect_data": {
"body": { },
"method": "GET",
"url": "https://telegram.me/uzs_tg_bot?start=0891fb3b7cff50a75a212439fe22018c"
}
Формат оповещений
Для оповещений о результатах оплат с применением метода используется стандартный формат, описание которого представлено в разделе Оповещения.
К особенностям данного платёжного метода можно отнести то, что в оповещениях о проведении оплаты в параметре number
объекта account
передаётся идентификатор использованной карты в сервисе партнёра, а в параметре masked_card
объекта provider_extra_fields
— маскированный номер этой карты. Поэтому в случаях, когда один пользователь использует разные карты, в этих параметрах передаются разные значения. Также стоит учитывать что идентификаторы карт могут использоваться при проведении выплат (в параметре number
объекта account
).
В следующем примере оповещение свидетельствует о том, что в рамках проекта 579
от пользователя 65465
была успешно проведена оплата в размере 1 000,00 UZS
.
Рис.: Пример оповещения о проведении оплаты
{ "project_id": 579, "payment": { "id": "307657677656546777", "type": "purchase", "status": "success", "date": "2019-10-08T14:13:50+0000", "method": "Card partner", "sum": { "amount": 100000, "currency": "UZS" }, "description": "" }, "customer": { "id": "65465" }, "account": { "number": "1743-3223966A2D...514183B2584F543" }, "provider_extra_fields": { "masked_card": "411111******1111" }, "operation": { "id": 9708000007271, "type": "sale", "status": "success", "date": "2019-10-08T14:13:50+0000", "created_date": "2019-10-08T14:02:18+0000", "request_id": "30d9d5d9d7966a8a74b44ba559b1a989f2cad321e2-00009709", "sum_initial": { "amount": 100000, "currency": "UZS" }, "sum_converted": { "amount": 100000, "currency": "UZS" }, "code": "0", "message": "Success", "provider": { "id": 1521, "payment_id": "632441", "auth_code": "", "date": "2019-10-08T14:02:19+0000" } }, "signature": "gh13skxTd+KkEUemF3KaFYyLCTiteYp5FhTJJWu+qdhbMYUyLSf/uICQ BC9enst71izQvQ670YIpSkL1nyO90WA==" } }
В следующем примере оплата была отклонена из-за недостатка средств на счёте пользователя.
Рис.: Пример оповещения об отказе в проведении оплаты
{ "project_id": 579, "payment": { "id": "307657677656546777", "type": "purchase", "status": "decline", "date": "2019-10-08T14:13:50+0000", "method": "Card partner", "sum": { "amount": 100000, "currency": "UZS" }, "description": "" }, "customer": { "id": "65465" }, "account": { "number": "1743-3223966A2D...514183B2584F543" }, "provider_extra_fields": { "masked_card": "411111******1111" }, "operation": { "id": 9708000007271, "type": "sale", "status": "decline", "date": "2019-10-08T14:13:50+0000", "created_date": "2019-10-08T14:02:18+0000", "request_id": "30d9d5d9d7966a8a74b44ba559b1a989f2cad321e2-00009709", "sum_initial": { "amount": 100000, "currency": "UZS" }, "sum_converted": { "amount": 100000, "currency": "UZS" }, "code": "20105", "message": "Insufficient funds on customer account", "provider": { "id": 1521, "payment_id": "632441", "auth_code": "", "date": "2019-10-08T14:02:19+0000" } }, "signature": "gh13skxTd+KkEUemF3KaFYyLCTiteYp5FhTJJWu+qdhbMYUyLSf/uICQ BC9enst71izQvQ670YIpSkL1nyO90WA==" } }
Дополнительные материалы
Для организации работы с оплатами через Gate также могут быть полезны следующие материалы:
Выплаты через Gate
Общая информация
Для выплаты через Gate с использованием данного метода со стороны веб-сервиса необходимо отправить запрос, содержащий требуемые параметры и подпись, на рабочий URL ecommpay и принять оповещение о результате выплаты. Полная схема проведения выплаты представлена далее.
Рис.: Проведение выплаты через Gate
- Пользователь на стороне веб-сервиса инициирует выплату через партнёра.
- От веб-сервиса на заданный URL ecommpay передаётся запрос на проведение выплаты через Gate.
- Запрос на проведение выплаты поступает в платёжную платформу.
- Выполняется начальная обработка запроса, в рамках которой обеспечивается проверка наличия обязательных параметров и корректной подписи.
- От платёжной платформы к веб-сервису направляется ответ с информацией о получении запроса и его корректности. Подробнее см. в разделе Формат ответа.
- В платёжной платформе выполняются дальнейшая обработка запроса и его отправка в сервис партнёра.
- На стороне партнёра выполняется обработка платежа.
- От партнёра к платёжной платформе направляется оповещение о результате.
- От платёжной платформы к веб-сервису направляется оповещение о результате.
- От веб-сервиса пользователю направляется результат выплаты.
Формат запросов
При работе с запросами на выплаты с применением метода необходимо учитывать следующее:
- Должен использоваться запрос к конечной точке v2/payment/card-partner/payout, отправляемый методом POST.
- В запросе должны использоваться следующие объекты и параметры:
- general — объект, содержащий основные идентификационные сведения запроса:
- project_id — идентификатор проекта, полученный от ecommpay при интеграции;
- payment_id — идентификатор платежа, уникальный в рамках проекта;
- signature — подпись запроса, составленная после указания целевых параметров (подробнее — в разделе Использование подписи к данным);
- customer — объект, содержащий сведения о пользователе:
- id — идентификатор, уникальный в рамках проекта,
- ip_address — используемый IP-адрес;
- payment — объект, содержащий сведения о платеже:
- amount — сумма выплаты в минорных единицах валюты,
- currency — валюта платежа в формате ISO-4217 alpha-3;
- account — объект, содержащий сведения о платёжной карте пользователя:
- number — идентификатор карты, используемый сервисом партнёра для проведения выплаты. В этом параметре может передаваться один из идентификаторов, полученных от партнёра в оповещениях по оплатам пользователя, указанного в параметре customer.id.
- general — объект, содержащий основные идентификационные сведения запроса:
- Валютой платежа может быть только UZS.
- Дополнительно могут использоваться все параметры, указанные в спецификации.
Таким образом, корректный запрос на выплату с применением метода должен содержать идентификаторы проекта и платежа, подпись, данные пользователя, платежа и номер карты:
Рис.: Пример запроса на выплату
{ "general": { "project_id": 456, "payment_id": "af719496", "signature": "kahfYCxiTjiN9AkFvEZCpbe/a+wKKMv4i4BmNB2sVcrW0r3...==" }, "customer": { "id": "customer_test", "ip_address": "1.2.3.4" }, "payment": { "amount": 10000, "currency": "UZS" }, "account": { "number": "1743-3223966A2D...514183B2584F543" } }
Формат оповещений
Для оповещений о результатах выплат на карты используется стандартный формат, описание которого представлено в разделе Выплаты.
К особенностям данного платёжного метода можно отнести то, что при выплате идентификатор карты пользователя, используемый сервисом провайдера для обработки выплаты, передаётся в параметре number
объекта account
.
В следующем примере оповещение свидетельствует о том, что в рамках проекта 112
была успешно проведена выплата в размере 5,00 UZS
.
Рис.: Пример оповещения о проведении выплаты
{
"project_id": 112,
"payment": {
"id": "ORDER_ID_123",
"type": "payout",
"status": "success",
"date": "2020-01-29T11:43:00+0000",
"method": "Card partner",
"sum": {
"amount": 500,
"currency": "UZS"
},
"description": "Test sale"
},
"account": {
"number": "1743-3223966A2D...514183B2584F543"
},
"customer": {
"id": "1"
},
"operation": {
"id": 2000000026,
"type": "payout",
"status": "success",
"date": "2020-01-29T11:43:00+0000",
"created_date": "2020-01-29T11:42:54+0000",
"request_id": "1b47b55b41cf0cdd02b82a02bac2ba-00000003",
"sum_initial": {
"amount": 500,
"currency": "UZS"
},
"sum_converted": {
"amount": 500,
"currency": "UZS"
},
"code": "0",
"message": "Success",
"provider": {
"id": 1743,
"payment_id": "1580298177082",
"auth_code": "",
"date": "2019-08-28T07:14:54+0000"
}
},
"signature": "PsjbijucMMiDh50NSgareVvte+/NN/6cgqwV745Qt2j15yqBLWoRQ=="
}
}
В следующем примере оплата была отклонена.
Рис.: Пример оповещения об отказе в проведении оплаты
{
"project_id": 112,
"payment": {
"id": "ORDER_ID_123",
"type": "payout",
"status": "decline",
"date": "2020-01-29T11:44:00+0000",
"method": "Card partner",
"sum": {
"amount": 500,
"currency": "UZS"
},
"description": "Test sale"
},
"account": {
"number": "1743-3223966A2D...514183B2584F544"
},
"customer": {
"id": "1"
},
"operation": {
"id": 2000000026,
"type": "payout",
"status": "success",
"date": "2020-01-29T11:43:00+0000",
"created_date": "2020-01-29T11:42:54+0000",
"request_id": "1b47b55b41cf0cdd02b82a02bac2ba-00000003",
"sum_initial": {
"amount": 500,
"currency": "UZS"
},
"sum_converted": {
"amount": 500,
"currency": "UZS"
},
"code": "0",
"message": "Success",
"provider": {
"id": 1743,
"payment_id": "1580298177082",
"auth_code": "",
"date": "2019-08-28T07:14:54+0000"
}
},
"signature": "PsjbijucMMiDh50NSgareVvte+/NN/6cgqwV745Qt2j15yqBLWoRQ=="
}
}
Дополнительные материалы
Для организации работы с выплатами через Gate также могут быть полезны следующие материалы:
Анализ результатов проведения платежей
Как и при работе с другими платёжными методами, которые предоставляет ecommpay, при использовании метода партнёра доступны разные способы анализа информации о платежах и операциях с применением этого метода — как в отдельности, так и в совокупности с другими методами.
Всю необходимую информацию можно получать и анализировать средствами Dashboard, в том числе с помощью аналитических панелей на вкладке Analytics.
Также можно выгружать нужную информацию для последующего анализа с помощью специализированных аналитических средств сторонних разработчиков:
- Dashboard позволяет выгружать данные в форматах CSV и XLS с помощью инструментов на вкладке Платежи. При этом можно выполнять разовые выгрузки информации на локальный компьютер и задействовать периодическую выгрузку и отправку информации на заданные адреса электронной почты.
- Data API позволяет получать информацию в формате JSON и отправлять ее на заданный URL — для этого применяются запросы /operations/get.
С любыми вопросами о возможностях анализа можно обращаться в службу технической поддержки ecommpay.