EcoVoucher
Обзор
EcoVoucher — платёжный метод для проведения платежей с использованием ваучеров. Оплаты осуществляются через Payment Page и Gate.
Характеристика
Тип платёжного метода | платежи с использованием ваучеров |
---|---|
Платёжные инструменты | ваучеры |
Регионы использования | Все страны |
Валюты платежей | CAD, GBP, EUR, USD |
Конвертация валют | На стороне ecommpay |
Оплаты | + |
Выплаты | – |
Оплаты по сохранённым данным | – |
Полные возвраты | – |
Частичные возвраты | – |
Опротестования | – |
Особенности | Сумму платежа устанавливает пользователь на стороне сервиса EcoVoucher, выбирая ваучер установленного номинала, поэтому в запросе на оплату можно передавать нулевое значение |
Организация и стоимость подключения | По согласованию с курирующим менеджером ecommpay |
Схема работы
В проведении отдельного платежа с использованием EcoVoucher задействуются веб-сервис мерчанта, один из интерфейсов и платёжная платформа ecommpay, а также технические средства EcoVoucher.
Основные операции
Интерфейсы | Суммы * | |||||
---|---|---|---|---|---|---|
Payment Page | CMS Plug-ins | Gate | Dashboard | минимум | максимум | |
Оплаты | + | – | + | – | – | – |
* Проведение оплаты возможно с использованием ваучеров следущих номиналов: 10, 15, 25, 50, 75, 100, 150, 250 в любой из поддерживаемых валют. В случае если сумма платежа превышает максимально допустимое значение ваучера, то оплата происходит с помощью нескольких ваучеров. Например, если сумма равна 1250,00 EUR, то оплата произойдет двумя ваучерами с номиналом 500,00 EUR и одним с номиналом 250,00 EUR.
Сценарии использования
Для оплаты с использованием метода EcoVoucher пользователю необходимо ввести данные ваучера (номер, код безопасности и срок действия). Проведение оплаты выполняется с передачей пользователю данных ваучера через веб-сервис мерчанта.
Рис.: Оплата через Payment Page
Рис.: Оплата через Gate
Детальные сведения о том, что необходимо делать со стороны мерчанта для проведения платежей, а также о том, что можно использовать для анализа информации о проведённых платежах и операциях, представлены далее.
Оплаты через Payment Page
Общая информация
Для оплаты через Payment Page с использованием метода EcoVoucher со стороны веб-сервиса необходимо отправить запрос, содержащий требуемые параметры и подпись, на рабочий URL ecommpay, подтвердить сумму оплаты и принять оповещение о результате оплаты. При этом метод EcoVoucher можно сделать предварительно выбранным (подробнее — в разделе Предварительный выбор платёжных методов). Полная схема проведения оплаты представлена далее.
Рис.: Проведение оплаты через Payment Page
- Пользователь на стороне веб-сервиса инициирует оплату.
- От веб-сервиса на заданный URL ecommpay передаётся запрос на проведение оплаты через Payment Page.
- Запрос на проведение оплаты поступает в платёжную платформу.
- Выполняется начальная обработка запроса, в рамках которой обеспечивается проверка наличия обязательных параметров и корректной подписи.
- Осуществляется формирование Payment Page согласно настройкам проекта и параметрам вызова.
- Пользователю отображается сформированная платёжная форма.
- Пользователь выбирает для оплаты EcoVoucher.
- Запрос на проведение оплаты через EcoVoucher поступает в платёжную платформу.
- Выполняются дальнейшая обработка запроса и его отправка в сервис EcoVoucher.
- На стороне EcoVoucher выполняется обработка запроса на оплату.
- От сервиса EcoVoucher к платёжной платформе передаются данные для перенаправления пользователя в сервис EcoVoucher.
- Данные для перенаправления пользователя передаются к Payment Page.
- Пользователь перенаправляется в сервис EcoVoucher.
- Пользователь указывает сумму оплаты на стороне EcoVoucher.
- На стороне сервиса EcoVoucher выполняется обработка запроса.
- От сервиса EcoVoucher к платёжной форме отправляется ответ о принятии запроса на оплату.
- От платёжной платформы к веб-сервису отправляется запрос на подтверждение мерчантом суммы оплаты.
- На стороне веб-сервиса проводится обработка запроса.
- От веб-сервиса к платёжной платформе отправляется ответ с подтверждением суммы оплаты.
- От платёжной платформы к сервису EcoVoucher отправляется запрос на проведение оплаты.
- На стороне сервиса EcoVoucher выполняется обработка платежа.
- Пользователь перенаправляется к Payment Page.
- От сервиса EcoVoucher к платёжной платформе направляется информация о результате оплаты.
- От платёжной платформы к веб-сервису направляется оповещение о результате оплаты.
- От платёжной платформы к Payment Page направляется результат проведения оплаты.
- Результат оплаты отображается пользователю на Payment Page.
Информация о формате запросов и параметрах вызова Payment Page при работе с EcoVoucher, а также о формате оповещений о результатах оплат приведена далее; общая информация о работе с API представлена в разделе Описание Payment Page API.
Формат запросов на инициирование оплаты
При формировании запросов на открытие платёжной формы с применением метода EcoVoucher необходимо учитывать следующее:
- Должен использоваться базовый минимум параметров — параметры, обязательные для любого платёжного метода:
- project_id — идентификатор проекта, полученный от ecommpay при интеграции;
- payment_id — идентификатор платежа, уникальный в рамках проекта;
- payment_currency — валюта платежа в формате ISO-4217 alpha-3;
- payment_amount — сумма платежа в дробных единицах;
- customer_id — идентификатор пользователя в рамках проекта.
- Валютой платежа может быть любая из перечисленных в разделе Характеристика.
- Сумму платежа устанавливает пользователь на стороне сервиса EcoVoucher, выбирая ваучер установленного номинала, поэтому в запросе на оплату можно передавать нулевое значение
- Проведение оплаты возможно с использованием ваучеров следущих номиналов: 10, 15, 25, 50, 75, 100, 150, 250. В случае если сумма платежа превышает максимально допустимое значение ваучера, то оплата происходит с помощью нескольких ваучеров. Например, если сумма равна 1250,00 EUR, то оплата произойдет двумя ваучерами с номиналом 500,00 EUR и одним с номиналом 250,00 EUR.
- Для предварительного выбора метода EcoVoucher необходимо указывать код платёжного метода в параметре force_payment_method —
ecoVoucher
. - Дополнительно могут использоваться любые другие параметры из числа доступных для работы с Payment Page. Детальная информация обо всех параметрах приведена в разделе Параметры вызова платёжной формы.
- После определения всех параметров необходимо составить подпись. Подробную информацию см. в Работа с подписью к данным.
Таким образом, корректный запрос на открытие платёжной формы с применением метода EcoVoucher должен содержать идентификаторы проекта, платежа и пользователя, а также валюту и сумму платежа и подпись:
EPayWidget.run( { payment_id: 'X03936', payment_amount: 0, payment_currency: 'EUR', project_id: 190, customer_id: '12', signature: "kUi2x9dKHAVNU0FYldJrxh4yo+52Kt8KU+Y1Y4HASCQ9vySO\/RLCvht...==" } )
Формат запросов и ответов на подтверждение суммы оплаты
После получения положительного ответа на запрос на инициирование оплаты от сервиса EcoVoucher со стороны платёжной платформы мерчанту отправляется запрос на подтверждение суммы оплаты, указанной пользователем.
- Запрос
check_deposit
для подтверждения суммы оплаты отправляется методом POST на заданный URL веб-сервиса. - Запрос содержит следующие обязательные параметры:
- type — тип операции на стороне веб-сервиса, значение параметра всегда
check_deposit
; - customer_id — идентификатор пользователя в системе мерчанта;
- project_id — идентификатор проекта, полученный от ecommpay при интеграции;
- payment_id — идентификатор платежа, уникальный в рамках проекта;
- amount — сумма платежа в дробных единицах;
- currency — валюта платежа в формате ISO-4217 alpha-3;
- payment_method — название платёжного метода, значение параметра всегда
eco-voucher
; - signature — подпись запроса.
Рис.: Пример запроса на подтверждение суммы оплаты
{ "type": "check_deposit", "project_id": 258, "payment_id": "X03936", "customer_id": "123", "amount": 1000, "currency": "EUR", "payment_method": "eco-voucher", "signature": "+5O+5Qix8kbnOgIQe5JddN50ardeRdGh7Jfi7SJXULy\/+6GbR5nwToLrUXmQ==" }
- type — тип операции на стороне веб-сервиса, значение параметра всегда
- Ответ на запрос подтверждения суммы оплаты должен быть отправлен синхронно и содержать следующие обязательные параметры:
- code — код ответа на запрос. Для подтверждения суммы необходимо указать значение
0
, для отклонения — любое другое значение (в этом случае платёж переводится в статусdecline
и со стороны платёжной платформы отправляется оповещение об отказе в проведении оплаты). Если в ответе используется HTTP-код класса4xx
или5xx
, то платёж также переводится в статусdecline
. - payment_id — идентификатор платежа, уникальный в рамках проекта.
Рис.: Пример ответа на запрос
{ "code":0, "payment_id":"X03936" }
- code — код ответа на запрос. Для подтверждения суммы необходимо указать значение
Формат оповещений
Для оповещений о результатах оплат с применением метода EcoVoucher используется стандартный формат, описание которого представлено в разделе Оповещения.
В следующем примере оповещение свидетельствует о том, что в рамках проекта 238
для пользователя 12
была успешно проведена оплата в размере 10,00 EUR
.
Рис.: Пример оповещения о проведении оплаты
{ "project_id": 238, "payment": { "id": "TEST_15354433ww22", "type": "purchase", "status": "success", "date": "2018-09-03T12:03:20+0000", "method": "eco-voucher", "sum": { "amount": 1000, "currency": "EUR" }, "description": "" }, "customer": { "id": "12" }, "operation": { "id": 151162, "type": "sale", "status": "success", "date": "2018-09-03T12:03:20+0000", "created_date": "2018-09-03T12:01:52+0000", "request_id": "166ffa4ea", "sum_initial": { "amount": 1000, "currency": "EUR" }, "sum_converted": { "amount": 1000, "currency": "EUR" }, "provider": { "id": 1109, "payment_id": "3324010000019879134", "date": "2018-09-03T12:03:19+0000", "auth_code": "" }, "code": "0", "message": "Success" }, "signature": "zbMmZm+dIB9vSlVwC6hCBpBRol50WjQfwTkGhEvoA5pvUT...==" }
В следующем примере оплата была отклонена из-за истечения времени ожидания.
Рис.: Пример оповещения об отказе в проведении оплаты
{ "project_id": 238, "payment": { "id": "TEST_15731114254729", "type": "purchase", "status": "decline", "date": "2019-11-07T07:30:52+0000", "method": "eco-voucher", "sum": { "amount": 0, "currency": "EUR" }, "description": "TEST_1573111425472" }, "customer": { "id": "1" }, "operation": { "id": 18321000013161, "type": "sale", "status": "decline", "date": "2019-11-07T07:30:52+0000", "created_date": "2019-11-07T07:30:19+0000", "request_id": "00018322", "sum_initial": { "amount": 0, "currency": "EUR" }, "sum_converted": { "amount": 0, "currency": "EUR" }, "code": "20000", "message": "General decline", "provider": { "id": 1109, "payment_id": "4057010000023812693", "auth_code": "", "date": "2019-11-07T07:30:51+0000" } }, "signature": "yTXwH/0+FIhMv7iBRLLlf0HOg9nH/++EFQOcjoESkBGAi58N/DKKGs...==" }
Дополнительные материалы
Для организации работы с оплатами через Payment Page также могут быть полезны следующие материалы:
Оплаты через Gate
Общая информация
Для оплаты через Gate с использованием метода EcoVoucher со стороны веб-сервиса необходимо:
- Отправить запрос, содержащий требуемые параметры и подпись, на рабочий URL ecommpay.
- Осуществить перенаправление пользователя в сервис EcoVoucher.
- Обработать запрос на подтверждение суммы оплаты на стороне веб-сервиса.
- Отправить ответ с подтверждением суммы оплаты.
- Принять оповещение о результате оплаты.
Полная схема проведения оплаты представлена далее.
Рис.: Проведение оплаты через Gate
- Пользователь на стороне веб-сервиса инициирует оплату через EcoVoucher.
- От веб-сервиса на заданный URL ecommpay передаётся запрос на проведение оплаты через Gate.
- Запрос на проведение оплаты поступает в платёжную платформу.
- Выполняется начальная обработка запроса, в рамках которой обеспечивается проверка наличия обязательных параметров и корректной подписи.
- От платёжной платформы к веб-сервису направляется ответ с информацией о получении запроса и его корректности. Подробнее см. в разделе Формат ответа.
- В платёжной платформе выполняются дальнейшая обработка запроса и его отправка в сервис EcoVoucher.
- На стороне EcoVoucher выполняется обработка запроса на оплату.
- От сервиса EcoVoucher к платёжной платформе передаются данные для перенаправления пользователя на сайт сервиса EcoVoucher.
- От платёжной платформы к веб-сервису направляется оповещение с данными для перенаправления пользователя на сайт EcoVoucher в объекте redirect_data.
- Пользователь перенаправляется в сервис EcoVoucher.
- Пользователь указывает сумму оплаты на стороне EcoVoucher.
- На стороне сервиса EcoVoucher выполняется обработка запроса.
- От сервиса EcoVoucher к платёжной форме отправляется ответ о принятии запроса на оплату.
- От платёжной платформы к веб-сервису отправляется запрос на подтверждение мерчантом суммы оплаты.
- На стороне веб-сервиса проводится обработка запроса.
- От веб-сервиса к платёжной платформе отправляется ответ с подтверждением суммы оплаты.
- От платёжной платформы к сервису EcoVoucher отправляется запрос на проведение оплаты.
- На стороне сервиса EcoVoucher выполняется обработка платежа.
- Пользователь перенаправляется к веб-сервису.
- От сервиса EcoVoucher к платёжной платформе направляется уведомление о результате оплаты.
- От платёжной платформы к веб-сервису направляется оповещение о результате оплаты.
- От веб-сервиса пользователю направляется результат оплаты.
Информация о формате запросов и параметрах инициации оплат методом EcoVoucher через Gate, а также о формате оповещений о результатах оплат приведена далее, общая информация о работе с API представлена в разделе Работа с API.
Формат запросов на инициирование оплаты
При работе с запросами на оплаты с применением метода EcoVoucher необходимо учитывать следующее:
- Должен использоваться запрос
v2/payment/voucher/eco-voucher/sale
, отправляемый методом POST. Этот запрос относится к запросам для платежей с использованием ваучеров: /v2/payment/voucher/{payment_method}/sale - В запросе должны использоваться следующие объекты и параметры:
- general — объект, содержащий основные идентификационные сведения запроса:
- project_id — идентификатор проекта, полученный от ecommpay при интеграции;
- payment_id — идентификатор платежа, уникальный в рамках проекта;
- signature — подпись запроса, составленная после указания целевых параметров (подробнее — в разделе Использование подписи к данным);
- customer — объект, содержащий сведения о пользователе:
- id — идентификатор, уникальный в рамках проекта
- ip_address — используемый IP-адрес;
- payment — сведения о платеже:
- amount — сумма платежа в дробных единицах валюты,
- currency — валюта платежа в формате ISO-4217 alpha-3.
- return_url — URL для возвращения пользователя со стороны сервиса после оплаты:
- success — URL для перенаправления пользователя при проведенной оплате,
- decline — URL для перенаправления пользователя при отклоненной оплате.
- general — объект, содержащий основные идентификационные сведения запроса:
- Валютой платежа может быть любая из перечисленных в разделе Характеристика.
- Сумму платежа устанавливает пользователь на стороне сервиса EcoVoucher, выбирая ваучер установленного номинала, поэтому в запросе на оплату можно передавать нулевое значение
- Проведение оплаты возможно с использованием ваучеров следущих номиналов: 10, 15, 25, 50, 75, 100, 150, 250. В случае если сумма платежа превышает максимально допустимое значение ваучера, то оплата происходит с помощью нескольких ваучеров. Например, если сумма равна 1250,00 EUR, то оплата произойдет двумя ваучерами с номиналом 500,00 EUR и одним с номиналом 250,00 EUR.
- Дополнительно могут использоваться все параметры, указанные в спецификации.
Таким образом, корректный запрос на оплату с применением метода EcoVoucher должен содержать идентификаторы проекта и платежа, подпись, идентификатор и IP-адрес пользователя, данные ваучера, валюту и сумму платежа:
Рис.: Пример запроса на инициирование оплаты
{ "general": { "project_id": 417, "payment_id": "payment_123", "signature": "PJkV8ejrtyUG0Di8hTng6JvC7vQsaC6tajQVVfBaNIipTv+AWoXW\/9MTO8yJA==" }, "payment": { "amount": 0, "currency": "EUR" }, "customer": { "ip_address": "66.249.79.102", "id": "play7" }, "return_url":{ "decline" : "http://return.url", "success" : "http://return.url" } }
Форматы данных для перенаправления пользователей
Для перенаправления пользователя от веб-сервиса на сайт сервиса EcoVoucher необходимо принять оповещение от платёжной платформы, содержащее ссылку для перенаправления в параметре redirect_data.url и данные для отправки в теле запроса redirect_data.body, и использовать эти параметры при открытии HTML-страницы методом, указанным в redirect_data.method.
Далее приведён фрагмент оповещения, содержащего данные для перенаправления.
"redirect_data": {
"body": {
"PaymentPageID": "3324",
"MerchantAccountNumber": "118069",
"CustomerIdAtMerchant": "12",
"OnSuccessUrl": "https://process/complete-redirect?wsid=4a9qleke55vv6jfonut1jtpdp2",
"OnFailureUrl": "https://process/complete-redirect?wsid=4a9qleke55vv6jfonut1jtpdp2",
"TxID": 15781000001162,
"Currency": "EUR",
"TransferUrl": "https://ecoVoucherViaEcoPayz/callback/",
"CallbackUrl": "https://ecoVoucherViaEcoPayz/callback/",
"Checksum": "d1aa9a777d77f894b86962c51b341710"
},
"method": "POST",
"url": "https://secure.ecopayz.com/PrivateArea/ecoVoucherOnlineTransfer.aspx"
}
Формат запросов и ответов на подтверждение суммы оплаты
После получения положительного ответа на запрос на инициирование оплаты от сервиса EcoVoucher со стороны платёжной платформы мерчанту отправляется запрос на подтверждение суммы оплаты, указанной пользователем.
- Запрос
check_deposit
для подтверждения суммы оплаты отправляется методом POST на заданный URL веб-сервиса. - Запрос содержит следующие обязательные параметры:
- type — тип операции на стороне веб-сервиса, значение параметра всегда
check_deposit
; - customer_id — идентификатор пользователя в системе мерчанта;
- project_id — идентификатор проекта, полученный от ecommpay при интеграции;
- payment_id — идентификатор платежа, уникальный в рамках проекта;
- amount — сумма платежа в дробных единицах;
- currency — валюта платежа в формате ISO-4217 alpha-3;
- payment_method — название платёжного метода, значение параметра всегда
eco-voucher
; - signature — подпись запроса.
Рис.: Пример запроса на подтверждение суммы оплаты
{ "type": "check_deposit", "project_id": 258, "payment_id": "X03936", "customer_id": "123", "amount": 1000, "currency": "EUR", "payment_method": "eco-voucher", "signature": "+5O+5Qix8kbnOgIQe5JddN50ardeRdGh7Jfi7SJXULy\/+6GbR5nwToLrUXmQ==" }
- type — тип операции на стороне веб-сервиса, значение параметра всегда
- Ответ на запрос подтверждения суммы оплаты должен быть отправлен синхронно и содержать следующие обязательные параметры:
- code — код ответа на запрос. Для подтверждения суммы необходимо указать значение
0
, для отклонения — любое другое значение (в этом случае платёж переводится в статусdecline
и со стороны платёжной платформы отправляется оповещение об отказе в проведении оплаты). Если в ответе используется HTTP-код класса4xx
или5xx
, то платёж также переводится в статусdecline
. - payment_id — идентификатор платежа, уникальный в рамках проекта.
Рис.: Пример ответа на запрос
{ "code":0, "payment_id":"X03936" }
- code — код ответа на запрос. Для подтверждения суммы необходимо указать значение
Формат оповещений
Для оповещений о результатах оплат с применением метода EcoVoucher используется стандартный формат, описание которого представлено в разделе Оповещения.
В следующем примере оповещение свидетельствует о том, что в рамках проекта 238
для пользователя 12
была успешно проведена оплата в размере 10,00 EUR
.
Рис.: Пример оповещения о проведении оплаты
{ "project_id": 238, "payment": { "id": "TEST_15354433ww22", "type": "purchase", "status": "success", "date": "2018-09-03T12:03:20+0000", "method": "eco-voucher", "sum": { "amount": 1000, "currency": "EUR" }, "description": "" }, "customer": { "id": "12" }, "operation": { "id": 151162, "type": "sale", "status": "success", "date": "2018-09-03T12:03:20+0000", "created_date": "2018-09-03T12:01:52+0000", "request_id": "166ffa4ea", "sum_initial": { "amount": 1000, "currency": "EUR" }, "sum_converted": { "amount": 1000, "currency": "EUR" }, "provider": { "id": 1109, "payment_id": "3324010000019879134", "date": "2018-09-03T12:03:19+0000", "auth_code": "" }, "code": "0", "message": "Success" }, "signature": "zbMmZm+dIB9vSlVwC6hCBpBRol50WjQfwTkGhEvoA5pvUT...==" }
В следующем примере оплата была отклонена из-за истечения времени ожидания..
Рис.: Пример оповещения об отказе в проведении оплаты
{ "project_id": 238, "payment": { "id": "TEST_15731114254729", "type": "purchase", "status": "decline", "date": "2019-11-07T07:30:52+0000", "method": "eco-voucher", "sum": { "amount": 0, "currency": "EUR" }, "description": "TEST_1573111425472" }, "customer": { "id": "1" }, "operation": { "id": 18321000013161, "type": "sale", "status": "decline", "date": "2019-11-07T07:30:52+0000", "created_date": "2019-11-07T07:30:19+0000", "request_id": "00018322", "sum_initial": { "amount": 0, "currency": "EUR" }, "sum_converted": { "amount": 0, "currency": "EUR" }, "code": "20000", "message": "General decline", "provider": { "id": 1109, "payment_id": "4057010000023812693", "auth_code": "", "date": "2019-11-07T07:30:51+0000" } }, "signature": "yTXwH/0+FIhMv7iBRLLlf0HOg9nH/++EFQOcjoESkBGAi58N/DKKGs...==" }
Дополнительные материалы
Для организации работы с оплатами через Gate также могут быть полезны следующие материалы:
Анализ результатов проведения платежей
Как и при работе с другими платёжными методами, которые предоставляет ecommpay, при использовании метода EcoVoucher доступны разные способы анализа информации о платежах и операциях с применением этого метода — как в отдельности, так и в совокупности с другими методами.
Всю необходимую информацию можно получать и анализировать средствами Dashboard, в том числе с помощью аналитических панелей на вкладке Analytics.
Также можно выгружать нужную информацию для последующего анализа с помощью специализированных аналитических средств сторонних разработчиков:
- Dashboard позволяет выгружать данные в форматах CSV и XLS с помощью инструментов на вкладке Платежи. При этом можно выполнять разовые выгрузки информации на локальный компьютер и задействовать периодическую выгрузку и отправку информации на заданные адреса электронной почты.
- Data API позволяет получать информацию в формате JSON и отправлять ее на заданный URL — для этого применяются запросы /operations/get.
С любыми вопросами о возможностях анализа можно обращаться в службу технической поддержки ecommpay.