Indonesian Online Banking
Обзор
Введение
Indonesian Online Banking — метод, позволяющий проводить платежи в индонезийских рупиях с использованием банковских счетов в Индонезии. Для этого метода в платёжной платформе ecommpay поддерживаются оплаты и выплаты.
В этой статье представлена информация о работе с методом Indonesian Online Banking: обзорный раздел с общими сведениями и последующие разделы с информацией о действиях, необходимых со стороны мерчанта для решения разных задач.
Характеристика
Тип платёжного метода | банковские платежи |
---|---|
Платёжные инструменты | банковские счета |
Регионы использования | ID |
Валюты платежей | IDR |
Конвертация валют | на стороне ecommpay |
Разовые оплаты | + |
Повторяемые оплаты | – |
Полные возвраты | – |
Частичные возвраты | – |
Выплаты | + |
Опротестования | – |
Особенности |
|
Организация и стоимость подключения | по согласованию с курирующим менеджером ecommpay; дополнительную информацию можно получить в ecommpay shop |
Схема работы
В проведении отдельного платежа с использованием метода Indonesian Online Banking задействуются веб-сервис мерчанта, один из интерфейсов и платёжная платформа ecommpay, а также технические средства сервиса одного из банков.
Основные операции
Для проведения платежей и выполнения операций с использованием метода Indonesian Online Banking могут применяться различные интерфейсы платёжной платформы. Так, оплаты могут проводиться через Payment Page, Gate и Dashboard (с применением платёжных ссылок), а выплаты — через Gate и Dashboard. При этом, независимо от используемых интерфейсов, для этого метода характерны следующие свойства и ограничения.
При работе с методом Indonesian Online Banking, независимо от используемых интерфейсов, актуальны следующие свойства и ограничения.
Суммы, IDR | Время ¹ | |||
---|---|---|---|---|
минимум | максимум | базовое | предельное | |
Оплаты | 100 000,00 | 25 000 000,00 | * | * |
Выплаты | 100 000,00 | 10 000 000,00 | * | * |
- Ограничения по времени выполнения операций зависят от банков, поддерживающих оплату этим методом. Базовое и предельное время определяются следующим образом:
- Базовое время — среднее расчётное время проведения платежа от момента его инициирования на стороне платёжной платформы до момента отправки инициатору оповещения о результате. Это время определяется для условий штатной работы всех технических средств и каналов связи, а также типичных действий со стороны пользователя (там, где они необходимы). Базовое время рекомендуется использовать для реагирования на отсутствие оповещений о результате платежа и выполнения опроса состояния платежа (подробнее).
- Предельное время — максимально допустимое время проведения платежа от момента его инициирования на стороне платёжной платформы до момента отправки инициатору оповещения о результате. Если платёж не был проведён или отклонён за это время, он автоматически переводится в статус
decline
. Для индивидуальной настройки предельного времени следует обращаться к специалистам технической поддержки ecommpay.
Сценарии использования
Проведение оплат с использованием метода Indonesian Online Banking осуществляется с перенаправлением пользователей к сервису банка, проведение выплат — с уведомлением пользователей через веб-сервис мерчанта.
Пользовательский сценарий оплаты через Payment Page (в базовом варианте с выбором пользователем метода и банка и перенаправлением с итоговой страницы платёжной формы к веб-сервису) выглядит следующим образом.
Общие сценарии проведения оплат и выплат можно представить следующим образом.
Вместе с тем, к особенностям работы с методом Indonesian Online Banking можно отнести то, что для каждого платежа с использованием этого метода должен быть выбран конкретный банк. При работе через Payment Page, как правило, выбор банка осуществляется пользователем уже в платёжной форме, но при вызовах Payment Page с предварительным выбором метода и банка, а также при инициировании оплат и выплат через Gate банк должен быть выбран на стороне веб-сервиса и в запросах должен указываться идентификатор этого банка. Возможные варианты выбора банка при работе через Payment Page описаны в разделе Оплаты через Payment Page этой статьи, а способы работы с идентификаторами банков — в следующем подразделе, Поддержка со стороны банков.
Вместе с тем, для оплат этим методом поддерживаются разные варианты выбора банка; они описаны в разделе Оплаты через Payment Page этой статьи.
Поддержка со стороны банков
В следующей таблице в ознакомительных целях приведены названия и идентификаторы банков, поддерживающих работу с методом Indonesian Online Banking.
Банк | ID | Оплаты | Выплаты |
---|---|---|---|
Bank Artha Graha | 2871 | – | + |
Bank Bukopin | 549 | – | + |
Bank Central Asia | 140 | + | + |
Bank CIMB Niaga | 507 | – | + |
Bank Commonwealth | 567 | – | + |
Bank Danamon Indonesia | 398 | – | + |
Bank HSBC | 513 | – | + |
Bank Mandiri | 143 | + | + |
Bank Maspion | 2891 | – | + |
Bank MayBank Indonesia | 565 | – | + |
Bank Mega | 547 | – | + |
Bank Mestika | 2901 | – | + |
Bank Negara Indonesia | 141 | + | + |
Bank OCBC NISP | 509 | – | + |
Bank Panin | 506 | – | + |
Bank Permata | 396 | – | + |
Bank Rakyat Indonesia | 142 | + | + |
Bank Rakyat Indonesia Syariah | 545 | – | + |
Bank Sinar Mas | 2911 | – | + |
Bank Sumut | 525 | – | + |
Bank Tabungan Pensiunan Nasional /BTPN | 544 | – | + |
Bank UOB Buana Indonesia | 508 | – | + |
OCBC Indonesia | 2921 | – | + |
Поскольку со временем состав доступных банков может меняться, для получения актуальной информации рекомендуется использовать POST-запрос к конечным точкам /v2/info/banks/indonesia/sale/list
(для оплат) и /v2/info/banks/indonesia/payout/list
(для выплат), которые относятся к группе конечных точек /v2/info/banks/{payment_method}/{operationType}/list
Gate API. В этом запросе должны указываться идентификатор проекта, идентификатор, валюта и сумма платежа и подпись к этим данным; при этом рекомендуется передавать реальные данные о платеже, но допускается и указание произвольных значений.
{ "general": { "project_id": 200, "payment_id": "ORDER_155860015", "signature": "K6jllym+PtObocZtr345st...==" }, "payment": { "amount": 15000, "currency": "IDR" } }
[ { "id": 507, // Индентификатор банка "abbr": "CIMB", // Служебная аббревиатура банка, используемая в платформе "name": "BANK CIMB NIAGA", // Основное (международное) название банка "nativeName": "Bank CIMB Niaga", // Локальное (национальное или региональное) название банка "currencies": [ // Массив с информацией о валютах, поддерживаемых банком { "id": 982, // Идентификатор валюты в платёжной платформе "alpha_3_4217": "IDR", // Буквенный код валюты платежа в формате ISO-4217 alpha-3 "number_3_4217": "360", // Цифровой код валюты платежа в формате ISO-4217 alpha-3 "exponent": 2 // Число дробных разрядов валюты } ] }, { "id": 2901, "abbr": "BMTK", "name": "Bank Mestika", "nativeName": "Bank Mestika", "currencies": [ { "id": 982, "alpha_3_4217": "IDR", "number_3_4217": "360", "exponent": 2 } ] }, { "id": 2871, "abbr": "BAG", "name": "Bank Artha Graha", "nativeName": "Bank Artha Graha", "currencies": [ { "id": 982, "alpha_3_4217": "IDR", "number_3_4217": "360", "exponent": 2 } ] } ]
С вопросами о работе с банками, поддерживающими метод Indonesian Online Banking, можно обращаться к курирующему менеджеру ecommpay.
Оплаты через Payment Page
Общая информация
Для проведения оплаты через Payment Page с использованием метода Indonesian Online Banking со стороны веб-сервиса необходимо отправить запрос, содержащий требуемые параметры и подпись, на рабочий URL ecommpay и принять оповещение о результате. Полная схема проведения оплаты выглядит следующим образом.
- Пользователь на стороне веб-сервиса инициирует оплату.
- От веб-сервиса на заданный URL ecommpay передаётся запрос на проведение оплаты через Payment Page.
- Запрос на проведение оплаты поступает в платёжную платформу.
- В платёжной платформе выполняется приём запроса, с проверкой наличия обязательных параметров и корректной подписи.
- Осуществляется подготовка Payment Page согласно параметрам проекта и вызова.
- Пользователю отображается платёжная форма.
- Пользователь выбирает для оплаты метод Indonesian Online Banking.
- Запрос на проведение оплаты через выбранный банк поступает в платёжную платформу.
- В платёжной платформе выполняются обработка полученного запроса и его отправка в сервис банка.
- В сервисе банка выполняется обработка запроса на оплату.
- От сервиса банка к платёжной платформе передаются данные для перенаправления пользователя к сервису банка.
- Данные для перенаправления пользователя передаются к Payment Page.
- Пользователь перенаправляется к сервису банка.
- Пользователь выполняет необходимые действия для оплаты.
- В сервисе банка выполняется обработка платежа.
- Информация о результате оплаты отображается пользователю в сервисе банка.
- Пользователь перенаправляется к Payment Page.
- От сервиса банка к платёжной платформе направляется информация о результате оплаты.
- От платёжной платформы к веб-сервису направляется оповещение о результате оплаты.
- От платёжной платформы к Payment Page направляется информация о результате оплаты.
- Информация о результате оплаты отображается пользователю на Payment Page.
Как правило, после того как пользователь на стороне веб-сервиса подтверждает готовность перейти к оплате, он перенаправляется к Payment Page, выбирает платёжный метод и, в случае работы с методом Indonesian Online Banking, дополнительно выбирает один из доступных банков. Вместе с тем, в некоторых ситуациях могут быть актуальны другие варианты выбора платёжного метода и банка. Например, при открытии Payment Page можно сразу перенаправлять пользователя к выбору банка либо ограничивать список поддерживаемых банков для отдельного платежа и отображать пользователю только кнопки выбора целевых банков. Конкретный вариант выбора платёжного метода и банка определяется через параметры, указанные в запросе на открытие Payment Page (подробнее Формат запросов), при этом допустимы следующие варианты:
- 1 — при открытии платёжной формы в ней последовательно отображаются отдельные страницы для выбора метода и банка, и пользователь выбирает сначала метод, а затем банк (этот вариант используется по умолчанию);
- 2 — при открытии платёжной формы в ней отображается страница с кнопками выбора методов и банков для данного метода, и пользователь выбирает один из этих банков;
- 3 — при открытии платёжной формы в ней отображается страница с кнопками выбора всех доступных банков для данного метода, и пользователь выбирает один из этих банков;
- 4 — при открытии платёжной формы в ней отображается страница с кнопками выбора заданных банков для данного метода, и пользователь выбирает один из этих банков;
- 5 — при открытии платёжной формы в ней отображается страница подтверждения перенаправления к сервису заданного банка, и пользователь соглашается с этим перенаправлением.
Информация о форматах запросов и оповещений, используемых для проведения оплат методом Indonesian Online Banking через Payment Page, приведена далее в этом разделе; общая информация о работе с Payment Page API — в отдельной статье Организация взаимодействия.
Формат запросов
При формировании запросов на открытие платёжной формы с применением метода Indonesian Online Banking необходимо учитывать следующее:
- Должен использоваться базовый минимум параметров, обязательный для любого платежа:
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
. -
Вариант выбора банка может определяться следующим образом:
- Через выбор в Payment Page метода и банка (1) — как вариант по умолчанию, применяемый, если не указываются параметр
force_payment_method
и объектpayment_methods_options
, упоминаемые в подпунктах 2–5. - Через выбор в Payment Page банка среди доступных методов (2) — для этого в объекте
payment_methods_options
необходимо указывать объектonline_indonesian_banks
, содержащий параметрsplit_banks
со значениемtrue
:"payment_methods_options": "{\"online_indonesian_banks\": {\"split_banks\": true}}"
- Через выбор в Payment Page банка из числа доступных (3) — для этого в параметре
force_payment_method
необходимо указывать код предварительного выбора методаonline-indonesian-banks
. - Через выбор в Payment Page банка из числа заданных (4) — для этого необходимо указывать:
- код
online-indonesian-banks
в параметреforce_payment_method
; - объект
payment_methods_options
с объектомonline_indonesian_banks
, который должен содержать параметрsplit_banks
со значениемtrue
и объектbanks_id
с массивом, включающим в себя идентификаторы целевых банков:"payment_methods_options": "{\"online_indonesian_banks\": {\"split_banks\": true, \"banks_id\": [2901, 2871]}}"
- код
- Через подтверждение в Payment Page перенаправления к сервису заданного банка (5) — для этого необходимо указывать:
- код
online-indonesian-banks
в параметреforce_payment_method
; - объект
payment_methods_options
с объектомonline_indonesian_banks
, который должен содержать параметрsplit_banks
со значениемtrue
и объектbanks_id
с массивом, включающим в себя идентификатор целевого банка:"payment_methods_options": "{\"online_indonesian_banks\": {\"split_banks\": true, \"banks_id\": [2901]}}"
- код
- Через выбор в Payment Page метода и банка (1) — как вариант по умолчанию, применяемый, если не указываются параметр
- Дополнительно могут использоваться любые другие параметры из числа доступных для работы с Payment Page (подробнее).
- После указания всех целевых параметров необходимо составлять подпись (подробнее).
Таким образом, корректный запрос на открытие платёжной формы с применением метода Indonesian Online Banking должен содержать идентификатор проекта, базовые сведения о платеже (идентификатор, сумму и код валюты), идентификатор пользователя и подпись.
{ "project_id": 120, "payment_id": "580", "payment_amount": 1000000, "payment_currency": "IDR", "customer_id": "customer1", "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg==" }
{ "project_id": 120, "payment_id": "580", "payment_amount": 1000000, "payment_currency": "IDR", "customer_id": "customer1", "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg==" }
Вместе с тем, в случае с выбором из заданных банков (4), запрос на открытие Payment Page может содержать расширенный набор данных.
{ "project_id": 120, "payment_id": "580", "payment_amount": 1000000, "payment_currency": "THB", "customer_id": "customer1", "force_payment_method": "online-indonesian-banks", "payment_methods_options": "{\"online_indonesian_banks\": {\"split_banks\": true, \"banks_id\": [140, 141]}}", "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg==" }
Формат оповещений
Для оповещений о результатах оплат с применением метода Indonesian Online Banking используется типовой формат, описание которого представлено в разделе Оповещения.
В следующем примере оповещение свидетельствует о том, что в рамках проекта 200
была проведена оплата в размере 200 000,00 IDR
.
{ "project_id": 200, "payment": { "id": "154383173598055", "type": "purchase", "status": "success", "date": "2022-09-03T10:50:29+0000", "method": "Indonesian banks", "sum": { "amount": 20000000, "currency": "IDR" }, "description": "1543831735980" }, "customer": { "id": "1" }, "operation": { "id": 15788000002076, "type": "sale", "status": "success", "date": "2022-09-03T10:50:29+0000", "created_date": "2022-09-03T10:40:20+0000", "request_id": "72cb91e7586004", "sum_initial": { "amount": 20000000, "currency": "IDR" }, "sum_converted": { "amount": 20000000, "currency": "IDR" }, "provider": { "id": 1153, "payment_id": "", "date": "2022-09-03T10:44:27+0000", "auth_code": "" }, "code": "0", "message": "Success" }, "signature": "Cug4rIB6OimEkwmMBi1OfYpFyBErmi0OVw34WpHt5CzEA==" }
В следующем примере оповещение свидетельствует об отклонённой оплате.
{ "project_id": 200, "payment": { "id": "154356886034811111", "type": "purchase", "status": "decline", "date": "2022-09-10T14:11:13+0000", "method": "Indonesian banks", "sum": { "amount": 1000, "currency": "IDR" }, "description": "154356886034811111" }, "operation": { "id": 9830000002095, "type": "sale", "status": "decline", "date": "2022-09-10T14:11:13+0000", "created_date": "2022-09-10T14:11:06+0000", "request_id": "3b14e5b0fd1", "sum_initial": { "amount": 1000, "currency": "IDR" }, "sum_converted": { "amount": 10, "currency": "IDR" }, "provider": { "id": 1153, "payment_id": "", "auth_code": "" }, "code": "20101", "message": "Decline due to amount or frequency limit" }, "signature": "cQbMiD0pON9eJc5ZugNK0iRmVyHzNTmOX6Zg5w==" }
Дополнительные материалы
Для организации работы с оплатами через Payment Page также могут быть полезны следующие материалы:
- Быстрый старт и Организация взаимодействия — о том, как организовать взаимодействие веб-сервиса с платёжной платформой через Payment Page.
- Работа с подписью к данным — о порядке создания и проверки подписи в программных запросах и оповещениях при взаимодействии с платёжной платформой.
- Проведение платежей — о типах, схемах проведения и возможных статусах поддерживаемых платежей и операций.
- Разовая оплата в одну стадию — о том, как проводить разовые оплаты с незамедлительным списанием средств через Payment Page.
- Работа с информацией об операциях — о служебных кодах, которые используются в платёжной платформе, чтобы фиксировать информацию о выполнении операций.
Оплаты через Gate
Общая информация
Для проведения оплаты через Gate с использованием метода Indonesian Online Banking со стороны веб-сервиса необходимо:
- Отправить запрос, содержащий требуемые параметры и подпись, на рабочий URL ecommpay.
- Принять промежуточное оповещение от платёжной платформы и осуществить перенаправление пользователя к сервису банка.
- Принять итоговое оповещение от платёжной платформы.
Полная схема проведения оплаты выглядит следующим образом.
- Пользователь на стороне веб-сервиса инициирует оплату с использованием метода Indonesian Online Banking.
- От веб-сервиса на заданный URL ecommpay передаётся запрос на проведение оплаты через Gate.
- Запрос на проведение оплаты поступает в платёжную платформу ecommpay.
- В платёжной платформе выполняется приём запроса с проверкой наличия обязательных параметров и корректной подписи.
- От платёжной платформы к веб-сервису направляется ответ с информацией о получении запроса и его корректности (подробнее).
- В платёжной платформе выполняются дальнейшая обработка запроса (с проверкой согласованности параметров) и его оправка в сервис банка.
- В сервисе банка выполняется обработка запроса на оплату.
- От сервиса банка к платёжной платформе передаются данные для перенаправления пользователя к сервису банка.
- От платёжной платформы к веб-сервису направляется оповещение с данными для перенаправления пользователя к сервису банка.
- Пользователь перенаправляется к сервису банка.
- Пользователь выполняет необходимые действия для оплаты.
- В сервисе банка выполняется обработка платежа.
- Пользователю отображается информация о результате оплаты.
- Пользователь перенаправляется к веб-сервису.
- От сервиса банка к платёжной платформе направляется информация о результате оплаты.
- От платёжной платформы к веб-сервису направляется оповещение о результате оплаты.
- На стороне веб-сервиса обеспечивается информирование пользователя о результате оплаты.
Информация о форматах запросов и оповещений, используемых для проведения оплат методом Indonesian Online Banking через Gate, приведена далее в этом разделе; общая информация о работе с Gate API — в отдельной статье Организация взаимодействия.
Формат запросов
При формировании запросов на оплату с применением метода Indonesian Online Banking необходимо учитывать следующее:
- Для инициирования каждой оплаты должен использоваться отдельный POST-запрос к конечной точке
/v2/payment/banks/indonesia/sale
. Эта конечная точка относится к группе /v2/payment/banks/{payment_method}/sale. - В каждом запросе должны использоваться следующие объекты и параметры:
general
— объект, содержащий основные идентификационные сведения запроса:project_id
— идентификатор проекта, полученный от ecommpay при интеграции;,payment_id
— идентификатор платежа, уникальный в рамках проекта;,signature
— подпись запроса, составленная после указания всех целевых параметров (подробнее — в разделе Работа с подписью); (подробнее),
payment
— объект, содержащий сведения о платеже:amount
— округлённая до целого числа сумма платежа в дробных единицах валюты, со стороны мерчанта необходимо предупреждать пользователей об округлении;,currency
— код валюты платежа в формате ISO-4217 alpha-3;,
customer
— объект, содержащий сведения о пользователе:id
— идентификатор пользователя, уникальный в рамках проекта;,ip_address
— IP-адрес пользователя, актуальный для инициируемого платежа;,
account
— объект, содержащий сведения о банковском счёте пользователя:bank_id
— идентификатор банка.
- Дополнительно могут использоваться любые другие параметры из числа указанных в спецификации.
Таким образом, корректный запрос на оплату с применением метода Indonesian Online Banking должен содержать идентификатор проекта, базовые сведения о платеже (идентификатор, сумму и код валюты), идентификатор и IP-адрес пользователя, а также идентификатор банка и подпись.
{ "general": { "project_id": 2990, "payment_id": payment_id, "signature": "PJkV8ej\/UG0Di8hTng6JNIipTv+AWoXW\/9MTO8yJA==" }, "payment": { "amount": 20000000, "currency": "IDR" }, "customer": { "id":"2990", "ip_address": "192.0.2.0", }, "account":{ "bank_id": 140 } }
{ "general": { "project_id": 2990, "payment_id": payment_id, "signature": "PJkV8ej\/UG0Di8hTng6JNIipTv+AWoXW\/9MTO8yJA==" }, "payment": { "amount": 20000000, "currency": "IDR" }, "customer": { "id":"2990", "ip_address": "192.0.2.0", }, "account":{ "bank_id": 140 } }
Формат промежуточных оповещений для перенаправления пользователей
Для перенаправления пользователей от веб-сервиса мерчанта к сервису Indonesian Online Banking при проведении каждого платежа с использованием метода Indonesian Online Banking необходимо принять промежуточное оповещение от платёжной платформы и использовать информацию из него, включённую в объект redirect_data
. Формат таких оповещений является типовым (подробнее), при этом в состав объекта redirect_data
включаются следующие объекты и параметры:
body
— объект с данными для отправки в теле запроса;method
— параметр с указанием HTTP-метода отправки запроса (GET
илиPOST
);url
— параметр со ссылкой для перенаправления.
"redirect_data": { "body": {}, "method": "GET", "url": "https://www.example.com/pay" }
Формат итоговых оповещений
Для оповещений о результатах оплат с применением метода Indonesian Online Banking используется типовой формат, описание которого представлено в разделе Оповещения.
В следующем примере оповещение свидетельствует о том, что в рамках проекта 200
была проведена оплата в размере 200 000,00 IDR
.
{ "project_id": 200, "payment": { "id": "154383173598055", "type": "purchase", "status": "success", "date": "2022-09-03T10:50:29+0000", "method": "Indonesian banks", "sum": { "amount": 20000000, "currency": "IDR" }, "description": "1543831735980" }, "customer": { "id": "1" }, "operation": { "id": 15788000002076, "type": "sale", "status": "success", "date": "2022-09-03T10:50:29+0000", "created_date": "2022-09-03T10:40:20+0000", "request_id": "72cb91e7586004", "sum_initial": { "amount": 20000000, "currency": "IDR" }, "sum_converted": { "amount": 20000000, "currency": "IDR" }, "provider": { "id": 1153, "payment_id": "", "date": "2022-09-03T10:44:27+0000", "auth_code": "" }, "code": "0", "message": "Success" }, "signature": "Cug4rIB6OimEkwmMBi1OfYpapSpZri0OVw34WpHt5CzEA==" }
В следующем примере оповещение свидетельствует об отклонённой оплате.
{ "project_id": 200, "payment": { "id": "154356886034811111", "type": "purchase", "status": "decline", "date": "2022-09-10T14:11:13+0000", "method": "Indonesian banks", "sum": { "amount": 1000, "currency": "IDR" }, "description": "154356886034811111" }, "operation": { "id": 9830000002095, "type": "sale", "status": "decline", "date": "2022-09-10T14:11:13+0000", "created_date": "2022-09-10T14:11:06+0000", "request_id": "3b14e5b0fd1", "sum_initial": { "amount": 1000, "currency": "IDR" }, "sum_converted": { "amount": 10, "currency": "IDR" }, "provider": { "id": 1153, "payment_id": "", "auth_code": "" }, "code": "20101", "message": "Decline due to amount or frequency limit" }, "signature": "cQbMiD0pON9eJc5ZugNK0iTVyHzNTmOX6Zg5w==" }
Дополнительные материалы
Для организации работы с оплатами через Gate также могут быть полезны следующие материалы:
- Быстрый старт и Организация взаимодействия — о том, как взаимодействовать с платёжной платформой через Gate.
- Работа с подписью к данным — о порядке создания и проверки подписи в программных запросах и оповещениях при взаимодействии с платёжной платформой.
- Проведение платежей — о типах, схемах проведения и возможных статусах поддерживаемых платежей и операций.
- Разовая оплата в одну стадию — о том, как проводить разовые оплаты через Gate.
- Работа с информацией об операциях — о служебных кодах, которые используются в платёжной платформе, чтобы фиксировать информацию о выполнении операций.
Выплаты через Gate
Общая информация
Для проведения выплаты через Gate с использованием метода Indonesian Online Banking со стороны веб-сервиса необходимо отправить запрос, содержащий требуемые параметры и подпись, на рабочий URL ecommpay и принять оповещение о результате. Полная схема проведения выплаты выглядит следующим образом.
- Пользователь на стороне веб-сервиса инициирует выплату через Indonesian Online Banking.
- От веб-сервиса на заданный URL ecommpay передаётся запрос на проведение выплаты через Gate.
- Запрос на проведение выплаты поступает в платёжную платформу.
- В платёжной платформе выполняется приём запроса с проверкой наличия обязательных параметров и корректной подписи.
- От платёжной платформы к веб-сервису направляется ответ с информацией о получении запроса и его корректности. Подробнее — в разделе Формат ответа.
- В платёжной платформе обеспечиваются дальнейшая обработка запроса (с проверкой согласованности параметров) и его отправка в сервис Indonesian Online Banking.
- В сервисе Indonesian Online Banking выполняется обработка выплаты.
- От сервиса Indonesian Online Banking к платёжной платформе направляется информация о результате выплаты.
- От платёжной платформы к веб-сервису направляется оповещение о результате выплаты.
- На стороне веб-сервиса обеспечивается информирование пользователя о результате выплаты.
Информация о форматах запросов и оповещений, используемых для проведения выплат методом Indonesian Online Banking через Gate, приведена далее в этом разделе; общая информация о работе с Gate API — в отдельной статье Организация взаимодействия.
Формат запросов
При формировании запросов на выплату с применением метода Indonesian Online Banking необходимо учитывать следующее:
- Для инициирования каждой выплаты должен использоваться отдельный POST-запрос к конечной точке
/v2/payment/banks/indonesia/payout
. Эта точка относится к группе /v2/payment/banks/{payment_method}/payout. - В каждом запросе должны использоваться следующие объекты и параметры:
general
— объект, содержащий основные идентификационные сведения запроса:project_id
— идентификатор проекта, полученный от ecommpay при интеграции;,payment_id
— идентификатор платежа, уникальный в рамках проекта;,signature
— подпись запроса, составленная после указания всех целевых параметров (подробнее — в разделе Работа с подписью); (подробнее),
payment
— объект, содержащий сведения о платеже:amount
— округлённая до целого числа сумма выплаты в дробных единицах валюты;,currency
— код валюты платежа в формате ISO-4217 alpha-3;,
customer
— объект, содержащий сведения о пользователе:id
— идентификатор пользователя, уникальный в рамках проекта;,ip_address
— IP-адрес пользователя, актуальный для инициируемой выплаты;,
account
— объект, содержащий сведения о банковском счёте пользователя:number
— номер счёта;,customer_name
— имя держателя банковского счета;,bank_id
— идентификатор банка.
- Дополнительно могут использоваться любые другие параметры из числа указанных в спецификации.
Таким образом, корректный запрос на выплату с применением метода Indonesian Online Banking должен содержать идентификатор проекта, базовые сведения о платеже (его идентификатор, сумму и код валюты), идентификатор и IP-адрес пользователя, информацию о счёте и подпись.
{ "general": { "project_id": 2990, "payment_id": payment_id, "signature": "PJkV8ej\/UG0Di8hTng6JvaRfBaNIipTv+AWoXW\/9MTO8yJA==" }, "payment": { "amount": 35000000, "currency": "IDR" }, "customer": { "id":"2990", "ip_address": "192.0.2.0" }, "account":{ "bank_id": 140, "customer_name": "Putra account", "number": "314159265358979" } }
{ "general": { "project_id": 2990, "payment_id": payment_id, "signature": "PJkV8ej\/UG0Di8hTng6JvaRfBaNIipTv+AWoXW\/9MTO8yJA==" }, "payment": { "amount": 35000000, "currency": "IDR" }, "customer": { "id":"2990", "ip_address": "192.0.2.0" }, "account":{ "bank_id": 140, "customer_name": "Putra account", "number": "314159265358979" } }
Формат оповещений
Для оповещений о результатах выплат с применением метода Indonesian Online Banking используется типовой формат, описание которого представлено в разделе Оповещения.
В следующем примере оповещение свидетельствует о том, что в рамках проекта 200
была проведена выплата в размере 200 000,00 IDR
.
{ "project_id": 200, "payment": { "id": "PAYOUT7891022555", "type": "payout", "status": "success", "date": "2022-09-12T13:28:58+0000", "method": "Indonesian banks", "sum": { "amount": 20000000, "currency": "IDR" }, "description": "payout" }, "account": { "number": "6419422222", "bank_id": 140, "region_id": 236 }, "customer": { "id": "1" }, "operation": { "id": 15112000002236, "type": "payout", "status": "success", "date": "2022-09-12T13:28:58+0000", "created_date": "2022-09-12T13:22:15+0000", "request_id": "b54610e94a76", "sum_initial": { "amount": 20000000, "currency": "IDR" }, "sum_converted": { "amount": 20000000, "currency": "IDR" }, "provider": { "id": 1153, "payment_id": "E80NPPQ6Z1YSYPZTPH0NBON42", "date": "2022-09-12T13:28:34+0000", "auth_code": "" }, "code": "0", "message": "Success" }, "signature": "qV2FRs/wxoOaywQS0GrpMkoW80mynkaQfSAUJpfQ==" }
В следующем примере оповещение свидетельствует об отклонённой выплате.
{ "project_id": 200, "payment": { "id": "PAYOUT789", "type": "payout", "status": "decline", "date": "2022-09-07T09:44:43+0000", "method": "Indonesian banks", "sum": { "amount": 5000, "currency": "IDR" }, "description": "" }, "account": { "number": "6419422222", "bank_id": 140, "region_id": 236 }, "customer": { "id": "1" }, "errors": [ { "code": "3104", "message": "Payment Constraint Invalid Payout Amount", "description": "Gate. Operation was declined. Maximum payout limit is exceeded" } ], "operation": { "id": 533000002202, "type": "payout", "status": "decline", "date": "2022-09-07T09:44:43+0000", "created_date": "2022-09-07T09:44:43+0000", "request_id": "205d3536a91f474d62a602dd42fa7d248258224fe3f6", "sum_initial": { "amount": 5000, "currency": "IDR" }, "sum_converted": { "amount": 5000, "currency": "IDR" }, "provider": { "id": 1153, "payment_id": "" }, "code": "3104", "message": "Payment Constraint Invalid Payout Amount" }, "signature": "j4cxKDvx0EaDe4zKHot6v83rzDMlinxE915lAWGHKVjurpQ==" }
Дополнительные материалы
Для организации работы с выплатами через Gate также могут быть полезны следующие материалы:
- Быстрый старт и Организация взаимодействия — о том, как взаимодействовать с платёжной платформой через Gate.
- Работа с подписью к данным — о порядке создания и проверки подписи в программных запросах и оповещениях при взаимодействии с платёжной платформой.
- Проведение платежей — о типах, схемах проведения и возможных статусах поддерживаемых платежей и операций.
- Выплата — о том, как проводить выплаты через Gate.
- Работа с информацией об операциях — о служебных кодах, которые используются в платёжной платформе, чтобы фиксировать информацию о выполнении операций.
Выплаты через Dashboard
При использовании интерфейса Dashboard можно проводить одиночные и массовые выплаты методом Indonesian Online Banking с единичной и пакетной отправкой запросов, называемые соответственно одиночными и массовыми.
- Для проведения одиночной выплаты необходимо открыть форму выплаты, задать все необходимые параметры (включая метод), отправить запрос и убедиться в проведении выплаты.
-
Для проведения массовой выплаты необходимо подготовить и загрузить файл с информацией обо всех целевых выплатах, отправить пакет запросов и убедиться в проведении выплат.
При этом должен использоваться файл формата CSV, структура которого соответствует требованиям, представленным в разделе Сведения о массовых платежах, а параметры выплат — должны соответствовать требованиям, представленным в разделе Выплаты через Gate этой статьи (за исключением пункта о подписи).
Более подробная информация о проведении выплат через Dashboard представлена в отдельной статье.
Тестирование
Общая информация
Для метода Indonesian Online Banking доступно тестирование оплат через Payment Page и Gate, а также выплат через Gate. Тестирование может выполняться в рамках тестового проекта, и для подключения и отключения этой функциональности следует обращаться к специалистам технической поддержки ecommpay.
При тестировании платежей следует учитывать, что в запросах должен указываться идентификатор тестового проекта, а интерфейсы эмулятора платёжных форм Payment Page и Indonesian Online Banking могут отличаться от рабочих.
Статусы тестовых платежей
При тестировании оплат их итоговые статусы определяются исходя из сумм, указанных в запросах:
decline
— при указании суммы40000
или40400
,success
— при указании любой другой суммы.
При тестировании выплат их итоговые статусы определяются исходя из сумм, указанных в запросах:
decline
— при указании суммы40000
или40400
,success
— при указании любой другой суммы.
Оплаты через Payment Page
Для проведения тестовой оплаты через Payment Page необходимо:
- Отправить в платёжную платформу корректный тестовый запрос на открытие Payment Page.
- Если в запросе не был указан метод
online-indonesian-banks
— выбрать метод Indonesian Online Banking на странице эмулятора. - Если для выбора доступно несколько банков, то выбрать банк; если для выбора доступен только один банк, то щёлкнуть кнопку Оплатить.
- Щёлкнуть кнопку Success или Decline (в зависимости от запрашиваемой суммы).
- Принять итоговое оповещение с информацией о результате оплаты.
Более подробная информация о проведении оплат с использованием метода Indonesian Online Banking через Payment Page представлена в разделе Оплаты через Payment Page этой статьи.
Оплаты через Gate
Для проведения тестовой оплаты через Gate необходимо:
- Отправить в платёжную платформу корректный тестовый запрос на оплату (с указанием идентификатора банка в параметре
bank_id
, идентификатор следует уточнять у службы технической поддержки ecommpay). - Принять промежуточное оповещение с данными для перенаправления.
- Перейти по полученному URL и щёлкнуть кнопку Success или Decline (в зависимости от запрашиваемой суммы) — на странице эмулятора.
- Принять итоговое оповещение с информацией о результате оплаты.
Более подробная информация о проведении оплат с использованием метода Indonesian Online Banking через Gate представлена в разделе Оплаты через Gate этой статьи.
Выплаты через Gate
Для проведения тестовой выплаты через Gate необходимо отправить в платёжную платформу корректный тестовый запрос и принять итоговое оповещение с информацией о результате. Более подробная информация о проведении выплат с использованием метода Indonesian Online Banking представлена в разделе Выплаты через Gate этой статьи.
Анализ результатов проведения платежей
Для анализа информации о платежах и операциях, как в отдельности по методу Indonesian Online Banking, так и в совокупности с другими методами, можно использовать:
- инструментарий интерфейса Dashboard, с различными реестрами и аналитическими панелями;,
- отчёты в формате CSV, выгружаемые (как разово, так и периодически) через раздел Отчёты интерфейса Dashboard;,
- данные в формате JSON, получаемые по программным запросам через интерфейс Data API.
С вопросами по анализу информации можно обращаться к разделам документации (Dashboard и Использование Data API) и специалистам ecommpay.