Оплата в магазинах Индонезии
Обзор
Введение
«Оплата в магазинах» — метод, позволяющий проводить платежи в индонезийских рупиях с использованием наличных в Индонезии. Пользователь заказывает товары и услуги онлайн и завершает платёж самостоятельно по чеку или номеру заказа в ближайшем сетевом магазине. Сети магазинов, которые поддерживают этот платёжный метод, включают Alfamart и Indomaret, что делает его удобным способом оплаты для многих индонезийских пользователей. Для этого метода в платёжной платформе ecommpay поддерживаются оплаты.
В этой статье представлена информация о работе с методом «Оплата в магазинах»: обзорный раздел с общими сведениями и последующие разделы с информацией о действиях, необходимых со стороны мерчанта для решения разных задач.
Характеристика
Тип платёжного метода | платежи через точки оплаты |
---|---|
Платёжные инструменты | наличные |
Регионы использования | ID |
Валюты платежей | IDR |
Конвертация валют | на стороне ecommpay; для подключения необходимо обратиться к курирующему менеджеру ecommpay |
Разовые оплаты | + |
Повторяемые оплаты | – |
Полные возвраты | по запросу в службу технической поддержки ecommpay |
Частичные возвраты | по запросу в службу технической поддержки ecommpay |
Выплаты | – |
Опротестования | – |
Особенности |
|
Организация и стоимость подключения | по согласованию с курирующим менеджером ecommpay |
Схема работы
В проведении отдельного платежа с использованием метода «Оплата в магазинах» задействуются веб-сервис мерчанта, один из интерфейсов и платёжная платформа ecommpay, а также технические средства сервиса Alfamart и Indomaret.
Основные операции
Для проведения платежей и выполнения операций с использованием метода «Оплата в магазинах» могут применяться различные интерфейсы платёжной платформы. Так, оплаты могут проводиться через Payment Page, Gate и Dashboard (с применением платёжных ссылок). При этом, независимо от используемых интерфейсов, для этого метода характерны следующие свойства и ограничения.
При работе с методом «Оплата в магазинах», независимо от используемых интерфейсов, актуальны следующие свойства и ограничения.
Суммы, IDR | Время ¹ | |||
---|---|---|---|---|
Минимум | Максимум | Базовое | Предельное | |
Оплаты | 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.
- Пользователь выполняет необходимые действия для оплаты.
- В сервисе магазина выполняется обработка платежа.
- От сервиса магазина к платёжной платформе направляется информация о результате оплаты.
- От платёжной платформы к веб-сервису направляется оповещение о результате оплаты.
- От платёжной платформы к Payment Page направляется информация о результате оплаты.
- Информация о результате оплаты отображается пользователю на Payment Page.
Как правило, после того как пользователь на стороне веб-сервиса подтверждает готовность перейти к оплате, он перенаправляется к Payment Page, выбирает платёжный метод и, в случае работы с методом «Оплата в магазинах», дополнительно выбирает одну из доступных сетей магазинов. Вместе с тем, в некоторых ситуациях могут быть актуальны другие варианты выбора платёжного метода и сети магазинов. Например, при открытии Payment Page можно сразу перенаправлять пользователя к выбору сети магазинов. Конкретный вариант выбора платёжного метода и сети магазинов определяется через параметры, указанные в запросе на открытие Payment Page (подробнее), при этом допустимы следующие варианты:
- 1 — при открытии платёжной формы в ней последовательно отображаются отдельные страницы для выбора метода и сети магазинов, и пользователь выбирает сначала метод, а затем сеть магазинов (этот вариант используется по умолчанию);
- 2 — при открытии платёжной формы в ней отображается страница с кнопками выбора методов и сетей магазинов для данного метода, и пользователь выбирает одну из этих сетей;
- 3 — при открытии платёжной формы в ней отображается страница с кнопками выбора всех доступных сетей магазинов для данного метода, и пользователь выбирает одну из этих сетей;
- 4 — при открытии платёжной формы в ней отображается страница подтверждения перенаправления к сервису заданной сети магазинов, и пользователь соглашается с этим перенаправлением.
Информация о форматах запросов и оповещений, используемых для проведения оплат методом «Оплата в магазинах» через Payment Page, приведена далее в этом разделе; общая информация о работе с Payment Page API — в отдельной статье Организация взаимодействия.
Формат запросов
При формировании запросов на открытие платёжной формы с применением метода «Оплата в магазинах» необходимо учитывать следующее:
- Должен использоваться базовый минимум параметров, обязательный для любого платежа:
project_id
— идентификатор проекта, полученный от ecommpay при интеграции;payment_id
— идентификатор платежа, уникальный в рамках проекта;payment_currency
— код валюты платежа в формате ISO-4217 alpha-3;payment_amount
— сумма платежа в дробных единицах валюты;customer_id
— идентификатор пользователя в рамках проекта.
- Должен использоваться базовый минимум параметров:
project_id
,payment_id
,payment_currency
,payment_amount
,customer_id
. - Дополнительно рекомендуется указывать имя и адрес электронной почты пользователя в параметрах
customer_first_name
иcustomer_email
. Если какие-либо из этих параметров отсутствуют в запросе, в платёжной форме могут отображаться поля для ввода пользователем недостающих значений (подробнее — в разделе Дополнение информации о платежах). - Payment Page можно открывать на индонезийском языке. Для этого необходимо передавать код языка
id
в параметреlanguage_code
(подробнее — в разделе Управление языком платёжной формы). -
Вариант выбора сети магазинов может определяться следующим образом:
- Через выбор в Payment Page метода и сети магазинов (1) — как вариант по умолчанию, применяемый, если не указываются параметр
force_payment_method
и объектpayment_methods_options
, упоминаемые в подпунктах 2–5. - Через выбор в Payment Page сети магазинов среди доступных методов (2) — для этого в объекте
payment_methods_options
необходимо указывать объектindonesia_cash
, содержащий параметрsplit_banks
со значениемtrue
:"payment_methods_options": "{\"indonesia_cash\": {\"split_banks\": true}}"
- Через выбор в Payment Page сети магазинов из числа доступных (3) — для этого в параметре
force_payment_method
необходимо указывать код предварительного выбора методаindonesia-cash
. - Через подтверждение в Payment Page перенаправления к сервису заданной сети магазинов (4) — для этого необходимо указывать:
- код
indonesia-cash
в параметреforce_payment_method
; - объект
payment_methods_options
с объектомtest-code
, который должен содержать параметрsplit_banks
со значениемtrue
и объектbanks_id
с массивом, включающим в себя идентификатор целевого сети магазинов (идентификатор Alfamart —431
, Indomaret —432
):"payment_methods_options": "{\"indonesia_cash\": {\"banks_id\": [431]}}"
- код
- Через выбор в Payment Page метода и сети магазинов (1) — как вариант по умолчанию, применяемый, если не указываются параметр
- Дополнительно могут использоваться любые другие параметры из числа доступных для работы с Payment Page (подробнее).
- После указания всех целевых параметров необходимо составлять подпись (подробнее).
Таким образом, корректный запрос на открытие платёжной формы с применением метода «Оплата в магазинах» должен содержать идентификатор проекта, базовые сведения о платеже (идентификатор, сумму и код валюты), информацию о пользователе и подпись.
{ "project_id": 120, "payment_id": "580", "payment_amount": 1000, "payment_currency": "IDR", "customer_id": "customer1", "customer_first_name": "Doe", "customer_email": "doe@example.com", "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg==" }
Рис.: Пример достаточного набора данных для запроса на оплату
{ "project_id": 120, "payment_id": "580", "payment_amount": 1000, "payment_currency": "IDR", "customer_id": "customer1", "customer_first_name": "Doe", "customer_email": "doe@example.com", "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg==" }
Вместе с тем, в случае с перенаправлением к сервису заданной сети магазинов (4), запрос на открытие Payment Page может содержать расширенный набор данных.
{ "project_id": 120, "payment_id": "580", "payment_amount": 1000, "payment_currency": "IDR", "customer_id": "customer1", "force_payment_method": "indonesia-cash", "payment_methods_options": "{\"indonesia_cash\": {\"banks_id\": [431]}}" "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg==" }
Формат оповещений
Для оповещений о результатах оплат с применением метода «Оплата в магазинах» используется типовой формат, описание которого представлено в разделе Оповещения.
В следующем примере оповещение свидетельствует о том, что в рамках проекта 580
была проведена оплата в размере 200 000,00 IDR
.
Рис.: Пример данных из оповещения о проведении оплаты
{ "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": "e5c3b50e144a2011ced91cbb2df953512c17e4f512", "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": "7Jh1jmn20UFEuuFUCyoPe1GS0GCjH5L3rZdV8WXVw7g==" }
В следующем примере оповещение свидетельствует об отклонённой оплате.
Рис.: Пример данных из оповещения об отклонении оплаты
{ "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": "12adeb019e5b283628f74cc66d391a0b44fa69b354", "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/9TZ454e7FX5uAL0Q==" }
Дополнительные материалы
Для организации работы с оплатами через Payment Page также могут быть полезны следующие материалы:
- Организация взаимодействия — о том, как организовать взаимодействие веб-сервиса с платёжной платформой через Payment Page.
- Работа с подписью к данным — о порядке создания и проверки подписи в программных запросах и оповещениях при взаимодействии с платёжной платформой.
- Модель проведения платежей — о типах, схемах проведения и возможных статусах поддерживаемых платежей и операций.
- Разовая оплата в одну стадию — о том, как проводить разовые оплаты через Payment Page.
- Информация о выполнении операций — о служебных кодах, которые используются в платёжной платформе, чтобы фиксировать информацию о выполнении операций.
Оплаты через Gate
Общая информация
- Отправить запрос, содержащий требуемые параметры и подпись, на рабочий URL ecommpay.
- Принять промежуточное оповещение от платёжной платформы и осуществить перенаправление пользователя на страницу с платёжной инструкцией.
- Принять итоговое оповещение от платёжной платформы.
Полная схема проведения оплаты выглядит следующим образом.
Рис.: Проведение оплаты через Gate. Описание шагов
- Пользователь на стороне веб-сервиса инициирует оплату с использованием метода «Оплата в магазинах».
- От веб-сервиса на заданный URL ecommpay передаётся запрос на проведение оплаты через Gate.
- Запрос на проведение оплаты поступает в платёжную платформу ecommpay.
- В платёжной платформе выполняется приём запроса с проверкой наличия обязательных параметров и корректной подписи.
- От платёжной платформы к веб-сервису направляется ответ с информацией о получении запроса и его корректности (подробнее).
- От платёжной платформы к веб-сервису направляется оповещение с данными для перенаправления пользователя на страницу с инструкцией по оплате в Alfamart или Indomaret.
- Пользователь перенаправляется на страницу с инструкцией по оплате в Alfamart или Indomaret.
- Пользователь выполняет необходимые действия для оплаты.
- В сервисе Alfamart или Indomaret выполняется обработка платежа.
- От сервиса Alfamart или Indomaret к платёжной платформе направляется информация о результате оплаты.
- От платёжной платформы к веб-сервису направляется оповещение о результате оплаты.
- На стороне веб-сервиса обеспечивается информирование пользователя о результате оплаты.
Информация о форматах запросов и оповещений, используемых для проведения оплат методом «Оплата в магазинах» через Gate, приведена далее в этом разделе; общая информация о работе с Gate API — в отдельной статье Организация взаимодействия.
Формат запросов
При формировании запросов на оплату с применением метода «Оплата в магазинах» необходимо учитывать следующее:
- Для инициирования каждой оплаты должен использоваться отдельный POST-запрос к конечной точке
/v2/payment/cash/indonesia/sale
. Эта точка относится к группе /v2/payment/cash/{payment_method}/sale. - В каждом запросе должны использоваться следующие объекты и параметры:
general
— объект, содержащий основные идентификационные сведения запроса:project_id
— идентификатор проекта, полученный от ecommpay при интеграции;,payment_id
— идентификатор платежа, уникальный в рамках проекта;,signature
— подпись запроса, составленная после указания всех целевых параметров (подробнее — в разделе Работа с подписью к данным); (подробнее),
payment
— объект, содержащий сведения о платеже:amount
— сумма платежа в дробных единицах валюты;,currency
— код валюты платежа в формате ISO-4217 alpha-3;,
customer
— объект, содержащий сведения о пользователе:id
— идентификатор пользователя, уникальный в рамках проекта;,ip_address
— IP-адрес пользователя, актуальный для инициируемого платежа.
- Дополнительно рекомендуется указывать следующие объекты и параметры:
customer
— объект, содержащий сведения о пользователе:-
first_name
— имя пользователя,email
— адрес электронной почты;
account
— объект, содержащий сведения о сети магазинов:bank_id
— идентификатор сети магазинов: для Alfamart —431
, для Indomaret —432
.
Если какие-либо из этих параметров отсутствуют в запросе, список с названиями недостающих параметров может отправляться в оповещении на уточнение (подробнее — в статье Дополнение информации о платеже).
- Дополнительно могут использоваться любые другие параметры из числа указанных в спецификации.
Таким образом, корректный запрос на оплату с применением метода «Оплата в магазинах» должен содержать идентификатор проекта, базовые сведения о платеже (идентификатор, сумму и код валюты), информацию о пользователе и сети магазинов, а также подпись.
{ "general": { "project_id": 580, "payment_id": payment_id, "signature": "PJkV8ej\/UG0Di8hT+AWoXW\/9MTO8yJA==" }, "payment": { "amount": 35000000, "currency": "IDR" }, "customer": { "ip_address": "192.0.2.0", "first_name": "Riza", "email": "riza@example.com", "id": "customer123" }, "account":{ "bank_id": 431 } }
Рис.: Пример достаточного набора данных для запроса на оплату
{ "general": { "project_id": 580, "payment_id": payment_id, "signature": "PJkV8ej\/UG0Di8hT+AWoXW\/9MTO8yJA==" }, "payment": { "amount": 35000000, "currency": "IDR" }, "customer": { "ip_address": "192.0.2.0", "first_name": "Riza", "email": "riza@example.com", "id": "customer123" }, "account":{ "bank_id": 431 } }
Формат промежуточных оповещений для перенаправления пользователей
Для перенаправления пользователей от веб-сервиса мерчанта к сервису «Оплата в магазинах» при проведении каждого платежа с использованием метода «Оплата в магазинах» необходимо принять промежуточное оповещение от платёжной платформы и использовать информацию из него, включённую в объект redirect_data
. Формат таких оповещений является типовым (подробнее), при этом в состав объекта redirect_data
включаются следующие объекты и параметры:
body
— объект с данными для отправки в теле запроса;method
— параметр с указанием HTTP-метода отправки запроса (GET
илиPOST
);url
— параметр со ссылкой для перенаправления.
Рис.: Пример объекта redirect_data
"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
.
Рис.: Пример данных из оповещения о проведении оплаты
{ "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": "e5c3b50e144a20d166bc1cbb2df953512c17e4f512", "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": "7Jh1jmn20UFEuuFUCyoPe1GS0GCjH5L3rZdV8WXVw7g==" }
В следующем примере оповещение свидетельствует об отклонённой оплате.
Рис.: Пример данных из оповещения об отклонении оплаты
{ "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": "12adeb019e5b28374cc66d391a0b44fa69b354", "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/9To++SANuH+JOZ454e7FX5uAL0Q==" }
Дополнительные материалы
Для организации работы с оплатами через Gate также могут быть полезны следующие материалы:
- Организация взаимодействия — о том, как взаимодействовать с платёжной платформой через Gate.
- Работа с подписью к данным — о порядке создания и проверки подписи в программных запросах и оповещениях при взаимодействии с платёжной платформой.
- Модель проведения платежей — о типах, схемах проведения и возможных статусах поддерживаемых платежей и операций.
- Разовая оплата в одну стадию — о том, как проводить разовые оплаты через Gate.
- Информация об операциях — о служебных кодах, используемых в платёжной платформе для фиксации информации о выполнении операций.
Анализ результатов проведения платежей
Для анализа информации о платежах и операциях, как в отдельности по методу «Оплата в магазинах», так и в совокупности с другими методами, можно использовать:
- инструментарий интерфейса Dashboard, с различными реестрами и аналитическими панелями;,
- отчёты в формате CSV, выгружаемые (как разово, так и периодически) через раздел Отчёты интерфейса Dashboard;,
- данные в формате JSON, получаемые по программным запросам через интерфейс Data API.
С вопросами по анализу информации можно обращаться к разделам документации (Dashboard и Использование Data API) и специалистам ecommpay.