# Vietnamese Online Banking {#pm_vietnam} **На уровень выше:**[Банковские платежи](ru_pm_bankpayments.md) ## Обзор {#ru_pm_vietnam_overview} статья о работе с платёжным методом Vietnamese Online Banking, который позволяет проводить платежи в вьетнамских донгах с использованием банковских счетов во Вьетнаме и для которого в платформе Ecommpay поддерживаются оплаты и выплаты ### Введение {#section_ql3_5fj_stb .section} Vietnamese Online Banking — метод, позволяющий проводить платежи в вьетнамских донгах с использованием банковских счетов во Вьетнаме. Для этого метода в платёжной платформе Ecommpay поддерживаются оплаты и выплаты. В этой статье представлена информация о работе с методом Vietnamese Online Banking: обзорный раздел с общими сведениями и последующие разделы с информацией о действиях, необходимых со стороны мерчанта для решения разных задач. ### Характеристика {#section_tbf_2zk_ggb .section} |Тип платёжного метода|банковские платежи| |Платёжные инструменты|банковские счета| |Регионы использования|[VN](references/ru/countries/VN.md)| |Валюты платежей|[VND](references/ru/currencies/VND.md)| |Конвертация валют|на стороне Ecommpay| |Разовые оплаты|+| |Повторяемые оплаты|–| |Полные возвраты|–| |Частичные возвраты|–| |Выплаты|+| |Опротестования|–| |Особенности|- при работе с Payment Page поддерживаются разные варианты выбора банка, [подробнее](pm_vietnam.md#section_lpr_swm_g3b) - для валюты [VND](references/ru/currencies/VND.md) суммы указываются без дробной части - в браузере Safari может не поддерживаться перенаправление на сервис банка. Подробности необходимо уточнять у курирующего менеджера Ecommpay | |Организация и стоимость подключения|по согласованию с курирующим менеджером Ecommpay; дополнительную информацию можно получить в [Ecommpay shop](https://ecommpay.com/shop/payment-methods/online-banking-vietnam/)| ### Схема работы {#section_tsp_gzk_ggb .section} В проведении отдельного платежа с использованием метода Vietnamese Online Banking задействуются веб-сервис мерчанта, один из интерфейсов и платёжная платформа Ecommpay, а также технические средства сервиса одного из банков. ![](images/pm/ru_banks_vietnam_functional.svg) ### Основные операции {#section_rnx_4cl_ggb .section} Для проведения платежей и выполнения операций с использованием метода Vietnamese Online Banking могут применяться различные интерфейсы платёжной платформы. Так, оплаты могут проводиться через Payment Page, Gate и Dashboard \(с применением платёжных ссылок\), а выплаты — через Gate и Dashboard. При этом, независимо от используемых интерфейсов, для этого метода характерны следующие свойства и ограничения. ||Суммы, [VND](references/ru/currencies/VND.md)|Время¹| |минимум|максимум|базовое|предельное| |--|---------------------------------------------|------| |-------|--------|-------|----------| |Оплаты|100 000|300 000 000|\*|\*| |Выплаты|100 000|300 000 000|\*|\*| **Прим.:** 1. Ограничения по времени выполнения операций зависят от банков, поддерживающих оплату этим методом. Базовое и предельное время определяются следующим образом: - Базовое время — среднее расчётное время проведения платежа от момента его инициирования на стороне платёжной платформы до момента отправки инициатору оповещения о результате. Это время определяется для условий штатной работы всех технических средств и каналов связи, а также типичных действий со стороны пользователя. Базовое время рекомендуется использовать для реагирования на отсутствие оповещений о результате платежа и выполнения опроса состояния платежа \([подробнее](ru_Gate_payment_status_request.md#)\). - Предельное время — максимально допустимое время проведения платежа от момента его инициирования на стороне платёжной платформы до момента отправки инициатору оповещения о результате. Если платёж не был проведён или отклонён за это время, он автоматически переводится в статус `decline`. Для индивидуальной настройки предельного времени следует обращаться к специалистам технической поддержки Ecommpay. ### Сценарии использования {#section_fgt_sdl_ggb .section} Проведение оплат с использованием метода Vietnamese Online Banking осуществляется с перенаправлением пользователей к сервису банка, проведение выплат — с уведомлением пользователей через веб-сервис мерчанта. Пользовательский сценарий оплаты через Payment Page \(в базовом варианте с выбором пользователем метода и банка и перенаправлением с итоговой страницы платёжной формы к веб-сервису\) выглядит следующим образом. ![](images/pm/pp_scenario/ru_pp_customer_scenario_vietnam_1.svg "Переход к оплате") ![](images/pm/pp_scenario/ru_pp_customer_scenario_vietnam_2.svg "Выбор метода") ![](images/pm/pp_scenario/ru_pp_customer_scenario_vietnam_3.svg "Выбор банка") ![](images/pm/pp_scenario/ru_pp_customer_scenario_vietnam_4.svg "Аутентификация") ![](images/pm/pp_scenario/ru_pp_customer_scenario_vietnam_5.svg "Подтверждение платежа") ![](images/pm/pp_scenario/ru_pp_customer_scenario_vietnam_6.svg "Возвращение к форме") ![](images/pm/pp_scenario/ru_pp_customer_scenario_vietnam_7.svg "Возвращение к веб-сервису") Общие сценарии проведения оплат и выплат можно представить следующим образом. ![](images/pm/ru_banks_overview_pp.svg "Оплата через Payment Page") ![](images/pm/ru_banks_overview_gate_purchase.svg "Оплата через Gate") ![](images/pm/ru_banks_overview_gate_payout.svg "Выплата через Gate") Вместе с тем, к особенностям работы с методом Vietnamese Online Banking можно отнести то, что для каждого платежа с использованием этого метода должен быть выбран конкретный банк. При работе через Payment Page, как правило, выбор банка осуществляется пользователем уже в платёжной форме, но при вызовах Payment Page с предварительным выбором метода и банка, а также при инициировании оплат и выплат через Gate банк должен быть выбран на стороне веб-сервиса и в запросах должен указываться идентификатор этого банка. Возможные варианты выбора банка при работе через Payment Page описаны в разделе [Оплаты через Payment Page](pm_vietnam.md#) этой статьи, а способы работы с идентификаторами банков — в следующем подразделе, [Поддержка со стороны банков](pm_vietnam.md#section_rqp_zdl_ggb). ### Поддержка со стороны банков {#section_rqp_zdl_ggb .section} В следующей таблице в ознакомительных целях приведены названия и идентификаторы банков, поддерживающих работу с методом Vietnamese Online Banking. |Банк|ID|Оплаты|Выплаты| |----|--|------|-------| |Agribank|139|+|+| |Asia Commercial Bank|150|+|+| |Bank for Investment and Development of Vietnam|136|+|+| |DongA Joint Stock Commercial Bank|130|+|+| |Eximbank Vietnam|135|+|+| |Joint Stock Commercial Bank for Foreign Trade of Vietnam|133|+|+| |Sai Gon Thuong Tin Commercial Joint Stock Bank|131|+|+| |VietinBank|134|+|+| |Vietnam Technological and Commercial Joint- stock Bank|132|+|+| Поскольку со временем состав доступных банков может меняться, для получения актуальной информации рекомендуется использовать POST-запрос к конечным точкам `/v2/info/banks/vietnam/sale/list` \(для оплат\) и `/v2/info/banks/vietnam/payout/list` \(для выплат\), которые относятся к группе конечных точек [/v2/info/banks/\{payment\_method\}/\{operationType\}/list](https://api-developers.ecommpay.com/api-specification/requests-for-information/post-v2-info-banks-payment-method-operation-type-list) Gate API.В этом запросе должны указываться идентификатор проекта, идентификатор, валюта и сумма платежа и подпись к этим данным; при этом рекомендуется передавать реальные данные о платеже, но допускается и указание произвольных значений. ```language-json { "general": { "project_id": 200, "payment_id": "ORDER_155860015", "signature": "K6jllym+PtObocZtr345st...==" }, "payment": { "amount": 1000, "currency": "VND" } } ``` ```language-json [ { "id": 135, // Индентификатор банка "abbr": "EXIM", // Служебная аббревиатура банка, используемая в платформе "name": "EXIM", // Основное (международное) название банка "nativeName": "Eximbank", // Локальное (национальное или региональное) название банка "currencies": [ // Массив с информацией о валютах, поддерживаемых банком { "id": 104, // Идентификатор валюты в платёжной платформе "alpha_3_4217": "VND", // Буквенный код валюты платежа в формате ISO-4217 alpha-3 "number_3_4217": "704", // Цифровой код валюты платежа в формате ISO-4217 alpha-3 "exponent": 0 // Число дробных разрядов валюты } ] }, { "id": 132, "abbr": "TCB", "name": "TCB", "nativeName": "Techomank", "currencies": [ { "id": 104, "alpha_3_4217": "VND", "number_3_4217": "704", "exponent": 0 } ] }, { "id": 134, "abbr": "VTB", "name": "VTB", "nativeName": "VietinBank", "currencies": [ { "id": 104, "alpha_3_4217": "VND", "number_3_4217": "704", "exponent": 0 } ] } ] ``` С вопросами о работе с банками, поддерживающими метод Vietnamese Online Banking, можно обращаться к курирующему менеджеру Ecommpay. ## Оплаты через Payment Page {#ru_pm_vietnam_pp_purchase} ### Общая информация {#section_gtg_vxk_m2b .section} Для проведения оплаты через Payment Pageс использованием метода Vietnamese Online Banking со стороны веб-сервиса необходимо отправить запрос, содержащий требуемые параметры и подпись, на рабочий URL Ecommpay и принять оповещение о результате.Полная схема проведения оплаты выглядит следующим образом. ![](images/pm/ru_banks_vietnam_uml_pp.svg) 1. Пользователь на стороне веб-сервиса инициирует оплату. 2. От веб-сервиса на заданный URL Ecommpay передаётся запрос на проведение оплаты через Payment Page. 3. Запрос на проведение оплаты поступает в платёжную платформу. 4. В платёжной платформе выполняется приём запроса, с проверкой наличия обязательных параметров и корректной подписи. 5. Осуществляется подготовка Payment Page согласно параметрам проекта и вызова. 6. Пользователю отображается платёжная форма. 7. Пользователь выбирает для оплаты метод Vietnamese Online Banking. 8. Запрос на проведение оплаты через выбранный банк поступает в платёжную платформу. 9. В платёжной платформе выполняются обработка полученного запроса и его отправка в сервис банка. 10. В сервисе банка выполняется обработка запроса на оплату. 11. От сервиса банка к платёжной платформе передаются данные для перенаправления пользователя к сервису банка. 12. Данные для перенаправления пользователя передаются к Payment Page. 13. Пользователь перенаправляется к сервису банка. 14. Пользователь выполняет необходимые действия для оплаты. 15. В сервисе банка выполняется обработка платежа. 16. Информация о результате оплаты отображается пользователю в сервисе банка. 17. Пользователь перенаправляется к Payment Page. 18. От сервиса банка к платёжной платформе направляется информация о результате оплаты. 19. От платёжной платформы к веб-сервису направляется оповещение о результате оплаты. 20. От платёжной платформы к Payment Page направляется информация о результате оплаты. 21. Информация о результате оплаты отображается пользователю на Payment Page. Как правило, после того как пользователь на стороне веб-сервиса подтверждает готовность перейти к оплате, он перенаправляется к Payment Page, выбирает платёжный метод и, в случае работы с методом Vietnamese Online Banking, дополнительно выбирает один из доступных банков. Вместе с тем, в некоторых ситуациях могут быть актуальны другие варианты выбора платёжного метода и банка. Например, при открытии Payment Page можно сразу перенаправлять пользователя к выбору банка либо ограничивать список поддерживаемых банков для отдельного платежа и отображать пользователю только кнопки выбора целевых банков. Конкретный вариант выбора платёжного метода и банка определяется через параметры, указанные в запросе на открытие Payment Page \(подробнее [Формат запросов](pm_vietnam.md#section_lpr_swm_g3b)\), при этом допустимы следующие варианты: - 1 — при открытии платёжной формы в ней последовательно отображаются отдельные страницы для выбора метода и банка, и пользователь выбирает сначала метод, а затем банк \(этот вариант используется по умолчанию\); - 2 — при открытии платёжной формы в ней отображается страница с кнопками выбора методов и банков для данного метода, и пользователь выбирает один из этих банков; - 3 — при открытии платёжной формы в ней отображается страница с кнопками выбора всех доступных банков для данного метода, и пользователь выбирает один из этих банков; - 4 — при открытии платёжной формы в ней отображается страница с кнопками выбора заданных банков для данного метода, и пользователь выбирает один из этих банков; - 5 — при открытии платёжной формы в ней отображается страница подтверждения перенаправления к сервису заданного банка, и пользователь соглашается с этим перенаправлением. ![](images/universal/pm/splits/ru_asian_banking_pp_1_vietnam.svg "1 — Выбор метода и банка") ![](images/universal/pm/splits/ru_asian_banking_pp_2_vietnam.svg "2 — Выбор банка среди доступных методов") ![](images/universal/pm/splits/ru_asian_banking_pp_4_vietnam.svg "3 — Выбор среди доступных банков") ![](images/universal/pm/splits/ru_asian_banking_pp_5_vietnam.svg "4 — Выбор среди заданных банков") ![](images/universal/pm/splits/ru_asian_banking_pp_6_vietnam.svg "5 — Перенаправление к сервису заданного банка") Информация о форматах запросов и оповещений, используемых для проведения оплат методом Vietnamese Online Banking через Payment Page, приведена далее в этом разделе; общая информация о работе с Payment Page API — в отдельной статье [Организация взаимодействия](ru_pp_interaction_organisation.md#). ### Формат запросов {#section_lpr_swm_g3b .section} При формировании запросов на открытие платёжной формы с применением метода Vietnamese Online Banking необходимо учитывать следующее: 1. Должен использоваться базовый минимум параметров, обязательный для любого платежа: - `project_id` — идентификатор проекта, полученный от Ecommpay при интеграции; - `payment_id` — идентификатор платежа, уникальный в рамках проекта; - `payment_currency` — код валюты платежа в формате ISO-4217 alpha-3; - `payment_amount` — сумма платежа \(без выделения дробной части, поскольку при работе с валютой [VND](references/ru/currencies/VND.md) дробные единицы не используются\); - `customer_id` — идентификатор пользователя в рамках проекта. 2. Вариант выбора банка может определяться следующим образом: 1. *Через выбор в Payment Page метода и банка \(1\)* — как вариант по умолчанию, применяемый, если не указываются параметр `force_payment_method` и объект `payment_methods_options`, упоминаемые в подпунктах *2–5*. 2. *Через выбор в Payment Page банка среди доступных методов \(2\)* — для этого в объекте `payment_methods_options` необходимо указывать объект `online_vietnam_banks`, содержащий параметр `split_banks` со значением `true`: ```language-json "payment_methods_options": "{\"online_vietnam_banks\": {\"split_banks\": true}}" ``` 3. *Через выбор в Payment Page банка из числа доступных \(3\)* — для этого в параметре `force_payment_method` необходимо указывать код предварительного выбора метода `online-vietnam-banks`. 4. *Через выбор в Payment Page банка из числа заданных \(4\)* — для этого необходимо указывать: - код `online-vietnam-banks` в параметре `force_payment_method`; - объект `payment_methods_options` с объектом `online_vietnam_banks`, который должен содержать параметр `split_banks` со значением `true` и объект `banks_id` с массивом, включающим в себя идентификаторы целевых банков: ```language-json "payment_methods_options": "{\"online_vietnam_banks\": {\"split_banks\": true, \"banks_id\": [134, 132]}}" ``` 5. *Через подтверждение в Payment Page перенаправления к сервису заданного банка \(5\)* — для этого необходимо указывать: - код `online-vietnam-banks` в параметре `force_payment_method`; - объект `payment_methods_options` с объектом `online_vietnam_banks`, который должен содержать параметр `split_banks` со значением `true` и объект `banks_id` с массивом, включающим в себя идентификатор целевого банка: ```language-json "payment_methods_options": "{\"online_vietnam_banks\": {\"split_banks\": true, \"banks_id\": [134]}}" ``` 3. Дополнительно могут использоваться любые другие параметры из числа доступных для работы с Payment Page \([подробнее](ru_PP_Parameters.md)\). 4. После указания всех целевых параметров необходимо составлять подпись \([подробнее](ru_platform_signature.md#)\). Таким образом, корректный запрос на открытие платёжной формы с применением метода Vietnamese Online Banking должен содержать идентификатор проекта, базовые сведения о платеже \(идентификатор, сумму и код валюты\), идентификатор пользователя и подпись. ```language-json { "project_id": 120, "payment_id": "580", "payment_amount": 1000000, "payment_currency": "VND", "customer_id": "customer1", "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg==" } ``` ```language-json { "project_id": 120, "payment_id": "580", "payment_amount": 1000000, "payment_currency": "VND", "customer_id": "customer1", "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg==" } ``` Вместе с тем, в случае с выбором из заданных банков \(4\), запрос на открытие Payment Page может содержать расширенный набор данных. ```language-json { "project_id": 120, "payment_id": "580", "payment_amount": 1000000, "payment_currency": "VND", "customer_id": "customer1", "force_payment_method": "online-vietnam-banks", "payment_methods_options": "{\"online_vietnam_banks\": {\"split_banks\": true, \"banks_id\": [134, 132]}}", "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg==" } ``` ### Формат оповещений {#section_dpx_2hl_ggb .section} Для оповещений о результатах оплат с применением метода Vietnamese Online Banking используется типовой формат, описание которого представлено в разделе [Работа с оповещениями](ru_platform_callbacks.md#). В следующем примере оповещение свидетельствует о том, что в рамках проекта `200` была проведена оплата в размере `100 000 VND`. ```language-json { "project_id": 200, "payment": { "id": "154385980520099", "type": "purchase", "status": "success", "date": "2022-09-07T13:06:32+0000", "method": "Vietnam banks", "sum": { "amount": 100000, "currency": "VND" }, "description": "1543831735980" }, "customer": { "id": "1" }, "operation": { "id": 12919000002116, "type": "sale", "status": "success", "date": "2022-09-07T13:06:32+0000", "created_date": "2022-09-07T13:06:29+0000", "request_id": "41fcbd2791eabee713b7d7e89e53", "sum_initial": { "amount": 100000, "currency": "VND" }, "sum_converted": { "amount": 100000, "currency": "VND" }, "provider": { "id": 1154, "payment_id": "", "auth_code": "" }, "code": "0", "message": "Success" }, "signature": "Cug4rIB6OipZrz00eNLNIwE/eugWw34WpHt5CzEA==" } ``` В следующем примере оповещение свидетельствует об отклонённой оплате. ```language-json { "project_id": 200, "payment": { "id": "TEST_1548313365790", "type": "purchase", "status": "decline", "date": "2022-09-07T09:43:27+0000", "method": "Vietnam banks", "sum": { "amount": 400000000, "currency": "VND" }, "description": "548313365790" }, "customer": { "id": "1" }, "operation": { "id": 3745000002722, "type": "sale", "status": "decline", "date": "2022-09-07T09:43:27+0000", "created_date": "2022-09-07T09:41:49+0000", "request_id": "3a872bd43f92091", "sum_initial": { "amount": 400000000, "currency": "VND" }, "sum_converted": { "amount": 400000000, "currency": "VND" }, "provider": { "id": 1154, "payment_id": "DR0CCTJEPAN6KFWU14VDN", "date": "2022-09-07T09:42:58+0000", "auth_code": "" }, "code": "20000", "message": "General decline" }, "signature": "cQbMiD0pON9eJc5Zugubo0KQiyWj7NWQRmVyHzNTmOX6Zg5w==" } ``` ### Дополнительные материалы {#section_xpz_thl_ggb .section} Для организации работы с оплатами через Payment Page также могут быть полезны следующие материалы: - [Организация взаимодействия](ru_pp_interaction_organisation.md#)— о том, как организовать взаимодействие веб-сервиса с платёжной платформой через Payment Page. - [Работа с подписью к данным](ru_platform_signature.md#)— о порядке создания и проверки подписи в программных запросах и оповещениях при взаимодействии с платёжной платформой. - [Проведение платежей](ru_platform_payment_model.md)— о типах, схемах проведения и возможных статусах поддерживаемых платежей и операций. - [Проведение оплат](ru_pp_purchase.md)— о том, как проводить разовые оплаты через Payment Page. - [Работа с информацией об операциях](ru_platform_payment_info_codes.md)— о служебных кодах, которые используются в платёжной платформе, чтобы фиксировать информацию о выполнении операций. ## Оплаты через Gate {#ru_pm_vietnam_gate_purchase} ### Общая информация {#section_lsx_3jl_ggb .section} Для проведения оплаты через Gate с использованием метода Vietnamese Online Banking со стороны веб-сервиса необходимо: 1. Отправить запрос, содержащий требуемые параметры и подпись, на рабочий URL Ecommpay. 2. Принять промежуточное оповещение от платёжной платформы и осуществить перенаправление пользователя к сервису банка. 3. Принять итоговое оповещение от платёжной платформы. ![](images/pm/ru_banks_vietnam_uml_gate.svg) 1. Пользователь на стороне веб-сервиса инициирует оплату с использованием метода Vietnamese Online Banking. 2. От веб-сервиса на заданный URL Ecommpay передаётся запрос на проведение оплаты через Gate. 3. Запрос на проведение оплаты поступает в платёжную платформу Ecommpay. 4. В платёжной платформе выполняется приём запроса с проверкой наличия обязательных параметров и корректной подписи. 5. От платёжной платформы к веб-сервису направляется ответ с информацией о получении запроса и его корректности \([подробнее](ru_gate_interaction_organisation.md#)\). 6. В платёжной платформе выполняются дальнейшая обработка запроса \(с проверкой согласованности параметров\) и его отправка в сервис банка. 7. В сервисе банка выполняется обработка запроса на оплату. 8. От сервиса банка к платёжной платформе передаются данные для перенаправления пользователя к сервису банка. 9. От платёжной платформы к веб-сервису направляется оповещение с данными для перенаправления пользователя к сервису банка. 10. Пользователь перенаправляется к сервису банка. 11. Пользователь выполняет необходимые действия для оплаты. 12. В сервисе банка выполняется обработка платежа. 13. Пользователю отображается информация о результате оплаты. 14. Пользователь перенаправляется к веб-сервису. 15. От сервиса банка к платёжной платформе направляется информация о результате оплаты. 16. От платёжной платформы к веб-сервису направляется оповещение о результате оплаты. 17. На стороне веб-сервиса обеспечивается информирование пользователя о результате оплаты. Информация о форматах запросов и оповещений, используемых для проведения оплат методом Vietnamese Online Banking через Gate, приведена далее в этом разделе; общая информация о работе с Gate API — в отдельной статье [Организация взаимодействия](ru_gate_interaction_organisation.md#). ### Формат запросов {#section_icy_mxm_g3b .section} При формировании запросов на оплату с применением метода Vietnamese Online Banking необходимо учитывать следующее: 1. Для инициирования каждой оплаты должен использоваться отдельный POST-запрос к конечной точке `/v2/payment/banks/vietnam/sale`. Эта конечная точка относится к группе [/v2/payment/banks/\{payment\_method\}/sale](https://api-developers.ecommpay.com/api-specification/banks/post-v2-payment-banks-payment-method-sale). 2. В каждом запросе должны использоваться следующие объекты и параметры: - `general` — объект, содержащий основные идентификационные сведения запроса: - `project_id` — идентификатор проекта, полученный от Ecommpay при интеграции; - `payment_id` — идентификатор платежа, уникальный в рамках проекта; - `signature` — подпись запроса, составленная после указания всех целевых параметров \(подробнее — в разделе [Работа с подписью к данным](ru_platform_signature.md#)\); - `payment` — объект, содержащий сведения о платеже: - `amount` — сумма платежа \(без выделения дробной части, поскольку при работе с валютой [VND](references/ru/currencies/VND.md) дробные единицы не используются\); - `currency` — код валюты платежав формате ISO-4217 alpha-3; - `customer` — объект, содержащий сведения о пользователе: - `id` — идентификатор пользователя, уникальный в рамках проекта; - `ip_address` — IP-адрес пользователя, актуальный для инициируемого платежа; - `account` — объект, содержащий сведения о банковском счёте пользователя: - `bank_id` — идентификатор банка. 3. Дополнительно могут использоваться любые другие параметры из числа указанных в спецификации. Таким образом, корректный запрос на оплату с применением метода Vietnamese Online Banking должен содержать идентификатор проекта, базовые сведения о платеже \(идентификатор, сумму и код валюты\), идентификатор и IP-адрес пользователя, а также идентификатор банка и подпись. ```language-json { "general": { "project_id": 2990, "payment_id": payment_id, "signature": "PJkV8ej\/UG0Di8hTng6JNIipTv+AWoXW\/9MTO8yJA==" }, "payment": { "amount": 20000000, "currency": "VND" }, "customer": { "id":"2990", "ip_address": "192.0.2.0", }, "account":{ "bank_id": 135 } } ``` ```language-json { "general": { "project_id": 2990, "payment_id": payment_id, "signature": "PJkV8ej\/UG0Di8hTng6JNIipTv+AWoXW\/9MTO8yJA==" }, "payment": { "amount": 20000000, "currency": "VND" }, "customer": { "id":"2990", "ip_address": "192.0.2.0", }, "account":{ "bank_id": 135 } } ``` ### Формат промежуточных оповещений для перенаправления пользователей {#section_x23_cpg_vgb .section} Для перенаправления пользователей от веб-сервиса мерчанта к сервису Vietnamese Online Banking при проведении каждого платежа с использованием метода Vietnamese Online Banking необходимо принять промежуточное оповещение от платёжной платформы и использовать информацию из него, включённую в объект `redirect_data`. Формат таких оповещений является типовым \([подробнее](ru_platform_callbacks.md#)\), при этом в состав объекта `redirect_data` включаются следующие объекты и параметры: - `body` — объект с данными для отправки в теле запроса; - `method` — параметр с указанием HTTP-метода отправки запроса\(`GET` или `POST`\); - `url` — параметр со ссылкой для перенаправления. ```language-json "redirect_data": { "body": {}, "method": "GET", "url": "https://www.example.com/pay" } ``` ### Формат итоговых оповещений {#section_dpx_2hl_ggb .section} Для оповещений о результатах оплат с применением метода Vietnamese Online Banking используется типовой формат, описание которого представлено в разделе [Работа с оповещениями](ru_platform_callbacks.md#). В следующем примере оповещение свидетельствует о том, что в рамках проекта `200` была проведена оплата в размере `300 000 VND`. ```language-json { "project_id": 200, "payment": { "id": "154385980520099", "type": "purchase", "status": "success", "date": "2022-09-07T13:06:32+0000", "method": "Vietnam banks", "sum": { "amount": 300000, "currency": "VND" }, "description": "1543831735980" }, "customer": { "id": "1" }, "operation": { "id": 12919000002116, "type": "sale", "status": "success", "date": "2022-09-07T13:06:32+0000", "created_date": "2022-09-07T13:06:29+0000", "request_id": "41fcbd2791eabee713b7d7e89e53", "sum_initial": { "amount": 300000, "currency": "VND" }, "sum_converted": { "amount": 300000, "currency": "VND" }, "provider": { "id": 1154, "payment_id": "", "auth_code": "" }, "code": "0", "message": "Success" }, "signature": "Cug4rIB6OimEkwmMBi1OfYpeugWw34WpHt5CzEA==" } ``` В следующем примере оповещение свидетельствует об отклонённой оплате. ```language-json { "project_id": 200, "payment": { "id": "TEST_1548313365790", "type": "purchase", "status": "decline", "date": "2022-09-07T09:43:27+0000", "method": "Vietnam banks", "sum": { "amount": 400000000, "currency": "VND" }, "description": "548313365790" }, "customer": { "id": "1" }, "operation": { "id": 3745000002722, "type": "sale", "status": "decline", "date": "2022-09-07T09:43:27+0000", "created_date": "2022-09-07T09:41:49+0000", "request_id": "3a872bd43f92091", "sum_initial": { "amount": 400000000, "currency": "VND" }, "sum_converted": { "amount": 400000000, "currency": "VND" }, "provider": { "id": 1154, "payment_id": "DR0CCTJEPAN6KFWU14VDN", "date": "2022-09-07T09:42:58+0000", "auth_code": "" }, "code": "20000", "message": "General decline" }, "signature": "cQbMiD0pON9eJc5ZugNWQRmVyHzNTmOX6Zg5w==" } ``` ### Дополнительные материалы {#section_xsx_3jl_ggb .section} Для организации работы с оплатами через Gate также могут быть полезны следующие материалы: - [Организация взаимодействия](ru_gate_interaction_organisation.md#)— о том, как взаимодействовать с платёжной платформой через Gate. - [Работа с подписью к данным](ru_platform_signature.md#)— о порядке создания и проверки подписи в программных запросах и оповещениях при взаимодействии с платёжной платформой. - [Проведение платежей](ru_platform_payment_model.md)— о типах, схемах проведения и возможных статусах поддерживаемых платежей и операций. - [Разовая оплата в одну стадию](ru_platform_sms_model.md)— о том, как проводить разовые оплаты через Gate. - [Работа с информацией об операциях](ru_platform_payment_info_codes.md)— о служебных кодах, используемых в платёжной платформе для фиксации информации о выполнении операций. ## Выплаты через Gate {#ru_pm_vietnam_gate_payout} ### Общая информация {#section_lsx_3jl_ggb .section} Для проведения выплаты через Gate с использованием метода Vietnamese Online Banking со стороны веб-сервиса необходимо отправить запрос, содержащий требуемые параметры и подпись, на рабочий URL Ecommpay и принять оповещение о результате.Полная схема проведения выплаты выглядит следующим образом. ![](images/pm/ru_banks_uml_gate_payout.svg) 1. Пользователь на стороне веб-сервиса инициирует выплату через Vietnamese Online Banking. 2. От веб-сервиса на заданный URL Ecommpay передаётся запрос на проведение выплаты через Gate. 3. Запрос на проведение выплаты поступает в платёжную платформу. 4. В платёжной платформе выполняется приём запроса с проверкой наличия обязательных параметров и корректной подписи. 5. От платёжной платформы к веб-сервису направляется ответ с информацией о получении запроса и его корректности. Подробнее — в разделе [Формат ответа](ru_gate_interaction_organisation.md#). 6. В платёжной платформе обеспечиваются дальнейшая обработка запроса \(с проверкой согласованности параметров\) и его отправка в сервис Vietnamese Online Banking. 7. В сервисе Vietnamese Online Banking выполняется обработка выплаты. 8. От сервиса Vietnamese Online Banking к платёжной платформе направляется информация о результате выплаты. 9. От платёжной платформы к веб-сервису направляется оповещение о результате выплаты. 10. На стороне веб-сервиса обеспечивается информирование пользователя о результате выплаты. Информация о форматах запросов и оповещений, используемых для проведения выплат методом Vietnamese Online Banking через Gate, приведена далее в этом разделе; общая информация о работе с Gate API — в отдельной статье [Организация взаимодействия](ru_gate_interaction_organisation.md#). ### Формат запросов {#section_osx_3jl_ggb .section} При формировании запросов на выплату с применением метода Vietnamese Online Banking необходимо учитывать следующее: 1. Для инициирования каждой выплаты должен использоваться отдельный POST-запрос к конечной точке `/v2/payment/banks/vietnam/payout`. Эта точка относится к группе [/v2/payment/banks/\{payment\_method\}/payout](https://api-developers.ecommpay.com/api-specification/banks/post-v2-payment-banks-payment-method-payout). 2. В каждом запросе должны использоваться следующие объекты и параметры: - `general` — объект, содержащий основные идентификационные сведения запроса: - `project_id` — идентификатор проекта, полученный от Ecommpay при интеграции; - `payment_id` — идентификатор платежа, уникальный в рамках проекта; - `signature` — подпись запроса, составленная после указания всех целевых параметров \(подробнее — в разделе [Работа с подписью к данным](ru_platform_signature.md#)\); - `payment` — объект, содержащий сведения о платеже: - `amount` — сумма платежа \(без выделения дробной части, поскольку при работе с валютой [VND](references/ru/currencies/VND.md) дробные единицы не используются\); - `currency` — код валюты платежав формате ISO-4217 alpha-3; - `customer` — объект, содержащий сведения о пользователе: - `id` — идентификатор пользователя, уникальный в рамках проекта; - `ip_address` — IP-адрес пользователя, актуальный для инициируемой выплаты; - `account` — объект, содержащий сведения о банковском счёте пользователя: - `number` — номер счёта; - `customer_name` — имя держателя банковского счета; - `bank_id` — идентификатор банка. 3. Дополнительно могут использоваться любые другие параметры из числа указанных в спецификации. Таким образом, корректный запрос на выплату с применением метода Vietnamese Online Banking должен содержать идентификатор проекта, базовые сведения о платеже \(его идентификатор, сумму и код валюты\), идентификатор и IP-адрес пользователя, информацию о счёте и подпись. ```language-json { "general": { "project_id": 2990, "payment_id": payment_id, "signature": "PJkV8ej\/UG0Di8hTng6JvC7vQsaC6tajQAWoXW\/9MTO8yJA==" }, "payment": { "amount": 350000, "currency": "VND" }, "customer": { "id": "2990", "ip_address": "192.0.2.0" }, "account":{ "bank_id": 137, "customer_name": "Putra account", "number": "314159265358979" } } ``` ```language-json { "general": { "project_id": 2990, "payment_id": payment_id, "signature": "PJkV8ej\/UG0Di8hTng6JvC7vQsaC6tajQAWoXW\/9MTO8yJA==" }, "payment": { "amount": 350000, "currency": "VND" }, "customer": { "id": "2990", "ip_address": "192.0.2.0" }, "account":{ "bank_id": 137, "customer_name": "Putra account", "number": "314159265358979" } } ``` ### Формат оповещений {#section_wsx_3jl_ggb .section} Для оповещений о результатах выплат с применением метода Vietnamese Online Banking используется типовой формат, описание которого представлено в разделе [Работа с оповещениями](ru_platform_callbacks.md#). В следующем примере оповещение свидетельствует о том, что в рамках проекта `200` была проведена выплата в размере `100 001 VND`. ```language-json { "project_id": 200, "payment": { "id": "PAYOUTVIE7896361", "type": "payout", "status": "success", "date": "2022-09-07T12:04:49+0000", "method": "Vietnam banks", "sum": { "amount": 100001, "currency": "VND" }, "description": "" }, "account": { "number": "314159265358979", "bank_id":155 }, "customer": { "id": "1" }, "operation": { "id": 16462000002143, "type": "payout", "status": "success", "date": "2022-09-07T12:04:49+0000", "created_date": "2022-09-07T09:34:44+0000", "request_id": "0885e52e37cc83c5d276ef7128577f8fec89c77f67", "sum_initial": { "amount": 100001, "currency": "VND" }, "sum_converted": { "amount": 100001, "currency": "VND" }, "provider": { "id": 1154, "payment_id": "GKS44OLP7Y92PK6P", "auth_code": "" }, "code": "0", "message": "Success" }, "signature": "qV2FRs/wxoOaywQS0GYQDi+6+EOrpMkoW80mynkaQfSAUJpfQ==" } ``` В следующем примере оповещение свидетельствует об отклонённой выплате. ```language-json { "project_id": 200, "payment": { "id": "PAYOUTVIE789636", "type": "payout", "status": "decline", "date": "2022-09-07T09:32:11+0000", "method": "Vietnam banks", "sum": { "amount": 100001, "currency": "VND" }, "description": "" }, "account": { "number": "314159265358979" }, "customer": { "id": "1" }, "errors": [ { "code": "2801", "message": "Bank ID not found", "description": "Gate. Bank ID was not found in request" } ], "operation": { "id": 17881000002157, "type": "payout", "status": "decline", "date": "2022-09-07T09:32:11+0000", "created_date": "2022-09-07T09:32:11+0000", "request_id": "5f7cbc023e850669659b", "sum_initial": { "amount": 100001, "currency": "VND" }, "sum_converted": { "amount": 100001, "currency": "VND" }, "provider": { "id": 1154, "payment_id": "" }, "code": "2801", "message": "Bank ID not found" }, "signature": "qUOMgCr9BVctnogrHKed3c2jkjnZrKg/8TCLpagJcQ==" } ``` ### Дополнительные материалы {#section_xsx_3jl_ggb .section} Для организации работы с выплатами через Gate также могут быть полезны следующие материалы: - [Организация взаимодействия](ru_gate_interaction_organisation.md#)— о том, как взаимодействовать с платёжной платформой через Gate. - [Работа с подписью к данным](ru_platform_signature.md#)— о порядке создания и проверки подписи в программных запросах и оповещениях при взаимодействии с платёжной платформой. - [Проведение платежей](ru_platform_payment_model.md)— о типах, схемах проведения и возможных статусах поддерживаемых платежей и операций. - [Выплаты](ru_Gate_payout.md)— о том, как проводить выплаты через Gate. - [Работа с информацией об операциях](ru_platform_payment_info_codes.md)— о служебных кодах, используемых в платёжной платформе для фиксации информации о выполнении операций. ## Выплаты через Dashboard {#ru_pm_dash_payout} При использовании интерфейса Dashboard можно проводить *одиночные* и *массовые*выплатыметодом Vietnamese Online Banking с единичной и пакетной отправкой запросов, называемые соответственно *одиночными* и *массовыми*. - Для проведения одиночной выплаты необходимо открыть форму выплаты, задать все необходимые параметры \(включая метод\), отправить запрос и убедиться в проведении выплаты. - Для проведения массовой выплаты необходимо подготовить и загрузить файл с информацией обо всех целевых выплатах, отправить пакет запросов и убедиться в проведении выплат. При этомдолжен использоваться файл формата CSV, структура которого соответствует требованиям, представленным в разделе [Сведения о массовых платежах](ru_dbl_payments.md#), а параметры выплат— требованиям, представленным в разделе [Выплаты через Gate](pm_vietnam.md#) этой статьи \(за исключением пункта о подписи\). Более подробная информация о проведении выплат через Dashboard представлена в [отдельной статье](ru_dbl_payments.md#). ## Тестирование {#ru_pm_vietnam_testing} ### Общая информация {#section_ujs_5q4_zjb .section} Для метода Vietnamese Online Banking доступно тестирование оплат через Payment Page и Gate, а также выплат через Gate. Тестирование может выполняться в рамках тестового проекта, и для подключения и отключения этой функциональности следует обращаться к специалистам технической поддержки Ecommpay. При тестировании платежей следует учитывать, что в запросах должен указываться идентификатор тестового проекта, а интерфейсы эмулятора платёжных форм Payment Page и Vietnamese Online Banking могут отличаться от рабочих. ### Статусы тестовых платежей {#section_vjs_5q4_zjb .section} При тестировании оплат их итоговые статусы определяются исходя из сумм, указанных в запросах: - `decline` — при указании суммы `40000` или `40400`, - `success` — при указании любой другой суммы. При тестировании выплат их итоговые статусы определяются исходя из сумм, указанных в запросах: - `decline` — при указании суммы `40000` или `40400`, - `success` — при указании любой другой суммы. ### Оплаты через Payment Page {#section_syj_bt4_xjb .section} Для проведения тестовой оплаты через Payment Page необходимо: 1. Отправить в платёжную платформу корректный тестовый запрос на открытие Payment Page. 2. Если в запросе не был указан метод `online-vietnam-banks` — выбрать метод Vietnamese Online Banking на странице эмулятора. 3. Если для выбора доступно несколько банков, то выбрать банк; если для выбора доступен только один банк, то щёлкнуть кнопку **Оплатить**. 4. Щёлкнуть кнопку **Success** или **Decline** \(в зависимости от запрашиваемой суммы\). 5. Принять итоговое оповещение с информацией о результате оплаты. Более подробная информация о проведении оплат с использованием метода Vietnamese Online Banking через Payment Page представлена в разделе [Оплаты через Payment Page](pm_vietnam.md#) этой статьи. ### Оплаты через Gate {#section_ul5_gt4_xjb .section} Для проведения тестовой оплаты через Gate необходимо: 1. Отправить в платёжную платформу корректный тестовый запрос на оплату \(с указанием идентификатора банка в параметре `bank_id`, идентификатор следует уточнять у службы технической поддержки Ecommpay\). 2. Принять промежуточное оповещение с данными для перенаправления. 3. Перейти по полученному URL и щёлкнуть кнопку **Success** или **Decline** \(в зависимости от запрашиваемой суммы\) — на странице эмулятора. 4. Принять итоговое оповещение с информацией о результате оплаты. Более подробная информация о проведении оплат с использованием метода Vietnamese Online Banking через Gate представлена в разделе [Оплаты через Gate](pm_vietnam.md#) этой статьи. ### Выплаты через Gate {#section_n22_lt4_xjb .section} Для проведения тестовой выплаты через Gate необходимо отправить в платёжную платформу корректный тестовый запрос и принять итоговое оповещение с информацией о результате. Более подробная информация о проведении выплат с использованием метода Vietnamese Online Banking представлена в разделе [Выплаты через Gate](pm_vietnam.md#) этой статьи. ## Анализ результатов проведения платежей {#ru_pm_vietnam_dash_analysis} Для анализа информации о платежах и операциях, как в отдельности по методу Vietnamese Online Banking, так и в совокупности с другими методами, можно использовать: - инструментарийинтерфейса Dashboard, с различными реестрами и аналитическими панелями; - отчёты в формате CSV, выгружаемые\(как разово, так и периодически\) черезраздел **Отчёты** интерфейса Dashboard; - данные в формате JSON, получаемыепо программным запросам черезинтерфейс Data API. С вопросами по анализу информации можно обращаться к разделам документации \([Dashboard](ru_dbl_about.md) и [Использование Data API](ru_dbl_api_protocol.md)\) и специалистам Ecommpay.