Оплата в магазинах Индонезии
Обзор
«Оплата в магазинах» — платёжный метод для оплат наличными в магазинах. Пользователь заказывает товары и услуги онлайн и завершает платёж самостоятельно по чеку или номеру заказа в ближайшем сетевом магазине. Сети магазинов, которые поддерживают этот платёжный метод, включают Alfamart и Indomaret, что делает его удобным способом оплаты для многих индонезийских пользователей. Для работы с этим методом доступно проведение оплат через Payment Page и Gate.
Характеристика
Тип платёжного метода | платежи через точки оплаты |
---|---|
Платёжные инструменты | наличные |
Регионы использования | ID |
Валюты платежей | IDR |
Конвертация валют | на стороне ecommpay; для подключения необходимо обратиться к курирующему менеджеру ecommpay |
Оплаты | + |
Выплаты | – |
Оплаты по сохранённым данным | – |
Полные возвраты | по запросу в службу технической поддержки ecommpay |
Частичные возвраты | по запросу в службу технической поддержки ecommpay |
Опротестования | – |
Особенности |
|
Организация и стоимость подключения | По согласованию с курирующим менеджером ecommpay |
Схема работы
В проведении отдельного платежа с использованием метода «Оплата в магазинах» задействуются веб-сервис мерчанта, один из интерфейсов и платёжная платформа ecommpay, а также сервис сетевых магазинов Alfamart и Indomaret.
Основные операции
Интерфейсы | Суммы, IDR | Время* | ||||||
---|---|---|---|---|---|---|---|---|
Payment Page | CMS Plug-ins | Gate | Dashboard | Минимум | Максимум | Базовое | Предельное | |
Оплаты | + | – | + | – | 0,01 | 2 500 000,00 | 2 часа | 6 часов |
- Базовое время — среднее расчётное время проведения платежа от момента его инициирования на стороне платёжной платформы до момента отправки инициатору оповещения о результате. Это время, определяемое для условий штатной работы всех технических средств и каналов связи, а также типичных действий со стороны пользователя (там, где они необходимы). Базовое время рекомендуется использовать для реагирования на отсутствие оповещений о результате платежа и выполнения опроса состояния платежа.
- Предельное время — максимально допустимое время проведения платежа от момента его инициирования на стороне платёжной платформы до момента отправки инициатору оповещения о результате. Если платёж не был проведён или отклонён за это время, он автоматически переводится в статус
decline
. Для индивидуальной настройки предельного времени следует обращаться к специалистам технической поддержки ecommpay.
Сценарии использования
Проведение оплат с использованием метода «Оплата в магазинах» выполняется с перенаправлением пользователей на страницу с инструкцией, следуя которой пользователю необходимо добраться до магазина и завершить оплату на кассе.
Рис.: Оплата через Payment Page
Рис.: Оплата через Gate
Детальные сведения о том, что необходимо делать со стороны мерчанта для проведения оплат, а также о том, что можно использовать для анализа информации о проведённых платежах и операциях, представлены далее.
Оплаты через Payment Page
Общая информация
Для оплаты через Payment Page с использованием метода «Оплата в магазинах» со стороны веб-сервиса необходимо отправить запрос, содержащий требуемые параметры и подпись, на рабочий URL ecommpay и принять оповещение о результате оплаты. При этом метод «Оплата в магазинах» можно сделать предварительно выбранным (подробнее — в разделе Предварительный выбор платёжных методов). Полная схема проведения оплаты представлена далее.
Рис.: Проведение оплаты через Payment Page
- Пользователь на стороне веб-сервиса инициирует оплату.
- От веб-сервиса на заданный URL ecommpay передаётся запрос на проведение оплаты через Payment Page.
- Запрос на проведение оплаты поступает в платёжную платформу.
- Выполняется начальная обработка запроса, в рамках которой обеспечивается проверка наличия обязательных параметров и корректной подписи.
- Осуществляется генерация Payment Page согласно настройкам проекта и параметрам вызова.
- Пользователю отображается сгенерированная платёжная форма.
- Пользователь выбирает оплату наличными в одной из сетей: Alfamart или Indomaret, и подтверждает готовность использовать этот метод (если метод был задан предварительно выбранным, то только подтверждает готовность).
- Пользователь перенаправляется на страницу с инструкцией по оплате в Alfamart или Indomaret.
- Пользователь добирается до одного из магазинов сетей Alfamart или Indomaret и завершает оплату наличными на кассе магазина.
- На стороне сервиса Alfamart или Indomaret выполняется обработка платежа.
- От сервиса Alfamart или Indomaret к платёжной платформе направляется уведомление о результате оплаты.
- От платёжной платформы к веб-сервису направляется оповещение о результате оплаты.
- От платёжной платформы к Payment Page направляется результат проведения оплаты.
- Результат оплаты отображается пользователю на Payment Page.
Информация о формате запросов и параметрах вызова Payment Page при работе с методом «Оплата в магазинах», а также о формате оповещений о результатах оплат приведена далее; общая информация о работе с API — в разделе Описание Payment Page API.
Формат запросов
При формировании запросов на открытие платёжной формы с применением метода «Оплата в магазинах» необходимо учитывать следующее:
- Должен использоваться базовый минимум параметров — параметры, обязательные для любого платёжного метода:
- project_id — идентификатор проекта, полученный от ecommpay при интеграции;
- payment_id — идентификатор платежа, уникальный в рамках проекта;
- payment_amount — сумма платежа в дробных единицах валюты;
- payment_currency — валюта платежа в формате ISO-4217 alpha-3;
- customer_id — идентификатор пользователя в рамках проекта.
- Дополнительно рекомендуется указывать имя и адрес электронной почты пользователя в параметрах customer_first_name и customer_email. Если параметры отсутствуют в запросе, на Payment Page пользователю отображаются поля для ввода недостающих значений. Подробнее об уточнении параметров — в разделе Дополнение информации о платежах.
- Payment Page можно открывать на индонезийском языке. Для этого необходимо передавать код языка
id
в параметре language_code (подробнее — в разделе Управление языком платёжной формы). -
Можно настраивать отображение страницы Payment Page с выбором метода оплаты.
По умолчанию названия сетей магазинов, Alfamart и Indomaret, объединены в группу и отображаются одной кнопкой Indonesian convenience stores, поэтому выбор сети магазинов осуществляется в два этапа. Сначала выбирается Indonesian convenience stores среди прочих методов, а затем на следующей странице с перечнем банков выбирается конкретная сеть магазинов. Существует несколько вариантов отображения страницы Payment Page с выбором метода оплаты:
- Отображение сетей магазинов Alfamart и Indomaret одной кнопкой Indonesian convenience stores среди прочих методов.
- Отображение Alfamart и Indomaret отдельными кнопками среди прочих методов. Для этого необходимо передавать параметр split_banks со значением
true
в параметре payment_methods_options."payment_methods_options": "{\"indonesia_cash\": {\"split_banks\": true}}"
- Отображение только сетей магазинов Alfamart и Indomaret одной кнопкой Indonesian convenience stores. Для этого используется предварительный выбор метода «Оплата в магазинах». Необходимо передавать код платежного метода
indonesia-cash
в параметре force_payment_method. Пользователю сразу открывается страница с выбором сети магазинов. - Отображение только одной сети магазинов: Alfamart или Indomaret. Для этого используется предварительный выбор метода «Оплата в магазинах», но с указанием конкретной сети. Для этого необходимо передавать код платежного метода
indonesia-cash
в параметре force_payment_method и идентификатор сети магазинов banks_id в параметре payment_methods_options. Идентификатор Alfamart —431
, Indomaret —432
.payment_methods_options: '{\"indonesia_cash\": {\"banks_id\": [431]}}'
Ниже приведён пример запроса на открытие Payment Page на индонезийском языке с предварительно выбранной сетью магазинов Alfamart.
Рис.: Пример запроса с предварительным выбором метода
EPayWidget.run( { payment_id: '580', payment_amount: 20000000, payment_currency: 'IDR', project_id: 120, force_payment_method: 'indonesia-cash', payment_methods_options: '{\"indonesia_cash\": {\"banks_id\": [431]}}', language_code: 'id', customer_id: 'customer1', signature: "XFyr/D1zXj84lUZVfpbWZol9JAZLnUZoPJKPXRbOqBUpxxa/hOKm2 P8XOqydoyeIi7KdqrcxLFd3GxgPgUzIDg== } )
- Дополнительно могут использоваться любые другие параметры из числа доступных для работы с Payment Page. Детальная информация обо всех параметрах приведена в разделе Параметры вызова платёжной формы.
- После определения всех параметров необходимо составить подпись. Подробнее — в разделе Работа с подписью к данным.
Таким образом, корректный запрос на открытие платёжной формы с применением метода «Оплата в магазинах» должен содержать идентификатор, сумму и валюту платежа, идентификатор проекта и подпись:
EPayWidget.run( { payment_id: '580', payment_amount: 20000000, payment_currency: 'IDR', project_id: 120, signature: "XFyr/D1zXj84lUZVfpbWZol9JAZLnUZoPJKPXRbOqBUpxxa/hOKm2 P8XOqydoyeIi7KdqrcxLFd3GxgPgUzIDg==" } )
Формат оповещений
Для оповещений о результатах оплат с применением метода «Оплата в магазинах» используется стандартный формат, описание которого представлено в разделе Оповещения.
В следующем примере оповещение свидетельствует о том, что в рамках проекта 580
была успешно проведена оплата в размере 200 000,00 IDR
на виртуальный счёт 8888872800000162
.
Рис.: Пример оповещения о проведении оплаты
{ "project_id": 580, "payment": { "id": "ECT_TEST_154469827896", "type": "purchase", "status": "success", "date": "2018-12-13T11:04:37+0000", "method": "Indonesia", "sum": { "amount": 20000000, "currency": "IDR" }, "description": "" }, "account": { "number": "8888872800000162" }, "operation": { "id": 4326000002254, "type": "sale", "status": "success", "date": "2018-12-13T11:04:37+0000", "created_date": "2018-12-13T11:03:10+0000", "request_id": "e5c3b50e144a20d166bc13ac388be7 bf929703ae-46176f275f3311ced91cbb2df953512c17e4f512", "sum_initial": { "amount": 100, "currency": "IDR" }, "sum_converted": { "amount": 100, "currency": "IDR" }, "provider": { "id": 1163, "payment_id": "5044801", "date": "2018-12-13T11:04:35+0000", "auth_code": "" }, "code": "0", "message": "Success" }, "signature": "7Jh1jmn20UFEuuFUCyoPapeKoXauQkO5sapBZ7bnv m+Cl+1nOeyqgz3SOhto2kwe1GS0GCjH5L3rZdV8WXVw7g==" }
В следующем примере оплата была отклонена, так как истекло время ожидания подтверждения оплаты со стороны пользователя.
Рис.: Пример оповещения об отказе в проведении оплаты
{ "project_id": 580, "payment": { "id": "TEST_Indonesia_convenience_stores", "type": "purchase", "status": "decline", "date": "2018-12-13T19:54:35+0000", "method": "Indonesia", "sum": { "amount": 1000000, "currency": "IDR" }, "description": "" }, "account": { "number": "8888887800000022" }, "operation": { "id": 16617000002212, "type": "sale", "status": "decline", "date": "2018-12-13T19:54:35+0000", "created_date": "2018-12-13T13:54:33+0000", "request_id": "12adeb019e5b283f83803845267bd1648e67efb 5-372d87ad3760c628f74cc66d391a0b44fa69b354", "sum_initial": { "amount": 1000000, "currency": "IDR" }, "sum_converted": { "amount": 1000000, "currency": "IDR" }, "provider": { "id": 1163, "payment_id": "", "auth_code": "" }, "code": "20602", "message": "Time-out" }, "signature": "dkURT8W7wV1vvATI/9T1KwepNRSMfyu4AsIpV9Xv78kQcndRFIlnpHUtM i71Go++SANuH+JOZ454e7FX5uAL0Q==" }
Дополнительные материалы
Для организации работы с оплатами через Payment Page также могут быть полезны следующие материалы:
Оплаты через Gate
Общая информация
Для оплаты через Gate с использованием метода «Оплата в магазинах» со стороны веб-сервиса необходимо:
- Отправить запрос, содержащий требуемые параметры и подпись, на рабочий URL ecommpay.
- Осуществить перенаправление пользователя на страницу с инструкцией по оплате.
- Принять оповещение о результате оплаты.
Полная схема проведения оплаты представлена далее.
Рис.: Проведение оплаты через Gate
- Пользователь на стороне веб-сервиса инициирует оплату наличными в Alfamart или Indomaret.
- От веб-сервиса на заданный URL ecommpay передаётся запрос на проведение оплаты через Gate.
- Запрос на проведение оплаты поступает в платёжную платформу.
- Выполняется начальная обработка запроса, в рамках которой обеспечивается проверка наличия обязательных параметров и корректной подписи.
- От платёжной платформы к веб-сервису направляется ответ с информацией о получении запроса и его корректности. Подробнее — в разделе Формат ответа.
- От платёжной платформы к веб-сервису направляется оповещение с данными для перенаправления пользователя на страницу с инструкцией по оплате. Необходимые данные содержатся в объекте
redirect_data
. - Пользователь перенаправляется на страницу с инструкцией по оплате в Alfamart или Indomaret.
- Пользователь добирается до одного из магазинов сетей Alfamart или Indomaret и завершает оплату наличными на кассе магазина.
- На стороне сервиса Alfamart или Indomaret выполняется обработка платежа.
- От сервиса Alfamart или Indomaret к платёжной платформе направляется уведомление о результате оплаты.
- От платёжной платформы к веб-сервису направляется оповещение о результате оплаты.
- От веб-сервиса пользователю направляется результат оплаты.
Информация о формате запросов и параметрах инициирования оплат через Gate при работе с методом «Оплата в магазинах», а также о форматах данных для перенаправления пользователей и о формате оповещений о результатах оплат приведена далее; общая информация о работе с API — в разделе Работа с API.
Формат запросов
При формировании запросов на оплату с применением метода «Оплата в магазинах» необходимо учитывать следующее:
- Должен использоваться запрос
/v2/payment/cash/indonesia/sale
, отправляемый методом POST. Этот запрос относится к группе запросов оплаты наличными /v2/payment/cash/{payment_method}/sale. - В запросе должны использоваться следующие объекты и параметры:
- general — объект, содержащий основные идентификационные сведения запроса:
- project_id — идентификатор проекта, полученный от ecommpay при интеграции;
- payment_id — идентификатор платежа, уникальный в рамках проекта;
- signature — подпись запроса, составленная после указания целевых параметров (подробнее — в разделе Использование подписи к данным);
- customer — объект, содержащий сведения о пользователе:
- id — идентификатор, уникальный в рамках проекта,
- ip_address — используемый IP-адрес:
- payment — объект, содержащий сведения о платеже:
- amount — сумма платежа в дробных единицах валюты,
- currency — валюта платежа в формате ISO-4217 alpha-3.
- general — объект, содержащий основные идентификационные сведения запроса:
- Дополнительно рекомендуется указывать имя и адрес электронной почты пользователя и идентификатор сети магазинов. Если параметры отсутствуют в запросе, список недостающих параметров отправляется в оповещении на уточнение. Подробнее об уточнении параметров — в разделе Дополнение информации о платеже.
Рекомендуется использовать следующие объекты и параметры:
- customer — объект, содержащий сведения о пользователе:
- first_name — имя пользователя,
- email — адрес электронной почты;
- account — объект, содержащий сведения о сети магазинов:
- bank_id — идентификатор сети магазинов: для Alfamart —
431
, для Indomaret —432
.
- bank_id — идентификатор сети магазинов: для Alfamart —
- customer — объект, содержащий сведения о пользователе:
- Дополнительно могут использоваться любые другие параметры, указанные в спецификации.
Таким образом, корректный запрос на оплату с применением метода «Оплата в магазинах» должен содержать идентификаторы проекта и платежа, подпись, сумму и валюту платежа, IP-адрес пользователя, а также может содержать имя и электронный адрес пользователя и идентификатор сети магазинов:
{ "general": { "project_id": 580, "payment_id": payment_id, "signature": "PJkV8ej\/UG0Di8hTng6JvC7vQs aC6tajQVVfBaNIipTv+AWoXW\/9MTO8yJA==" }, "payment": { "amount": 35000000, "currency": "IDR" }, "customer": { "ip_address": "248.121.176", "first_name": "Riza", "email": "riza@testpay.com", "id": "customer123" }, "account":{ "bank_id": 431 } }
Форматы данных для перенаправления пользователей
Для перенаправления пользователей от веб-сервиса на страницу с инструкцией по оплате необходимо:
- Принять от платёжной платформы оповещение с объектом
redirect_data
. - Сформировать
POST
-запрос из параметров, переданных в объекте body, в кодировкеx-www-form-urlencoded
. - Осуществить перенаправление на URL, указанный в параметре url.
Далее приведён фрагмент оповещения, содержащего данные для перенаправления пользователя:
"redirect_data": { "body": { "MALLID": 4038, "CHAINMERCHANT": "NA", "AMOUNT": "10000.00", "PURCHASEAMOUNT": "10000.00", "TRANSIDMERCHANT": 16617000002212, "PAYMENTTYPE": "SALE", "WORDS": "4d1a2cdbc8a1fe972c3437953fc8c844cfeafa90", "REQUESTDATETIME": "20181213205434", "CURRENCY": "360", "PURCHASECURRENCY": "360", "SESSIONID": "6ac463c1", "NAME": "ROMAN", "EMAIL": "test@test.ru", "BASKET": "Sale,10000.00,1,10000.00", "PAYMENTCHANNEL": "35" }, "method": "POST", "url": "https://pay.com/Suite/Receive" },
Формат оповещений о результатах оплат
Для оповещений о результатах оплат с применением метода «Оплата в магазинах» используется стандартный формат, описание которого представлено в разделе Оповещения.
В следующем примере оповещение свидетельствует о том, что в рамках проекта 580
была успешно проведена оплата в размере 200 000,00 IDR
на виртуальный счёт 8888872800000162
.
Рис.: Пример оповещения о проведении оплаты
{ "project_id": 580, "payment": { "id": "ECT_TEST_154469827896", "type": "purchase", "status": "success", "date": "2018-12-13T11:04:37+0000", "method": "Indonesia", "sum": { "amount": 20000000, "currency": "IDR" }, "description": "" }, "account": { "number": "8888872800000162" }, "operation": { "id": 4326000002254, "type": "sale", "status": "success", "date": "2018-12-13T11:04:37+0000", "created_date": "2018-12-13T11:03:10+0000", "request_id": "e5c3b50e144a20d166bc13ac388be7bf9 29703ae-46176f275f3311ced91cbb2df953512c17e4f512", "sum_initial": { "amount": 100, "currency": "IDR" }, "sum_converted": { "amount": 100, "currency": "IDR" }, "provider": { "id": 1163, "payment_id": "5044801", "date": "2018-12-13T11:04:35+0000", "auth_code": "" }, "code": "0", "message": "Success" }, "signature": "7Jh1jmn20UFEuuFUCyoPapeKoXauQkO5sapBZ7bnv m+Cl+1nOeyqgz3SOhto2kwe1GS0GCjH5L3rZdV8WXVw7g==" }
В следующем примере оплата была отклонена, так как истекло время ожидания подтверждения оплаты со стороны пользователя.
Рис.: Пример оповещения об отказе в проведении оплаты
{ "project_id": 580, "payment": { "id": "TEST_Indonesia_convenience_stores", "type": "purchase", "status": "decline", "date": "2018-12-13T19:54:35+0000", "method": "Indonesia", "sum": { "amount": 1000000, "currency": "IDR" }, "description": "" }, "account": { "number": "8888887800000022" }, "operation": { "id": 16617000002212, "type": "sale", "status": "decline", "date": "2018-12-13T19:54:35+0000", "created_date": "2018-12-13T13:54:33+0000", "request_id": "12adeb019e5b283f83803845267bd1648e67e fb5-372d87ad3760c628f74cc66d391a0b44fa69b354", "sum_initial": { "amount": 1000000, "currency": "IDR" }, "sum_converted": { "amount": 1000000, "currency": "IDR" }, "provider": { "id": 1163, "payment_id": "", "auth_code": "" }, "code": "20602", "message": "Time-out" }, "signature": "dkURT8W7wV1vvATI/9T1KwepNRSMfyu4AsIpV9Xv78kQ cndRFIlnpHUtMi71Go++SANuH+JOZ454e7FX5uAL0Q==" }
Дополнительные материалы
Для организации работы с оплатами через Gate также могут быть полезны следующие материалы:
Анализ результатов проведения платежей
Как и при работе с другими платёжными методами, которые предоставляет ecommpay, при использовании метода «Оплата в магазинах» доступны разные способы анализа информации о платежах и операциях с применением этого метода — как в отдельности, так и в совокупности с другими методами.
Всю необходимую информацию можно получать и анализировать средствами Dashboard, в том числе с помощью аналитических панелей на вкладке Analytics.
Также можно выгружать нужную информацию для последующего анализа с помощью специализированных аналитических средств сторонних разработчиков:
- Dashboard позволяет выгружать данные в форматах CSV и XLS с помощью инструментов на вкладке Платежи. При этом можно выполнять разовые выгрузки информации на локальный компьютер и задействовать периодическую выгрузку и отправку информации на заданные адреса электронной почты.
- Data API позволяет получать информацию в формате JSON и отправлять ее на заданный URL — для этого применяются запросы /operations/get.
С любыми вопросами о возможностях анализа можно обращаться в службу технической поддержки ecommpay.