Vietnamese Online Banking

Обзор

Введение

Vietnamese Online Banking — метод, позволяющий проводить платежи в вьетнамских донгах с использованием банковских счетов во Вьетнаме. Для этого метода в платёжной платформе ecommpay поддерживаются оплаты и выплаты.

В этой статье представлена информация о работе с методом Vietnamese Online Banking: обзорный раздел с общими сведениями и последующие разделы с информацией о действиях, необходимых со стороны мерчанта для решения разных задач.

Характеристика

Тип платёжного метода банковские платежи
Платёжные инструменты банковские счета
Регионы использования VN
Валюты платежей VND
Конвертация валют на стороне ecommpay
Разовые оплаты +
Повторяемые оплаты –
Полные возвраты –
Частичные возвраты –
Выплаты +
Опротестования –
Особенности
  • при работе с Payment Page поддерживаются разные варианты выбора банка, подробнее
  • для валюты VND суммы указываются без дробной части
  • в браузере Safari может не поддерживаться перенаправление на сервис банка. Подробности необходимо уточнять у курирующего менеджера ecommpay
Организация и стоимость подключения по согласованию с курирующим менеджером ecommpay; дополнительную информацию можно получить в ecommpay shop

Схема работы

В проведении отдельного платежа с использованием метода Vietnamese Online Banking задействуются веб-сервис мерчанта, один из интерфейсов и платёжная платформа ecommpay, а также технические средства сервиса одного из банков.



Основные операции

Для проведения платежей и выполнения операций с использованием метода Vietnamese Online Banking могут применяться различные интерфейсы платёжной платформы. Так, оплаты могут проводиться через Payment Page, Gate и Dashboard (с применением платёжных ссылок), а выплаты — через Gate и Dashboard. При этом, независимо от используемых интерфейсов, для этого метода характерны следующие свойства и ограничения.

При работе с методом Vietnamese Online Banking, независимо от используемых интерфейсов, актуальны следующие свойства и ограничения.

Суммы, VND Время ¹
минимум максимум базовое предельное
Оплаты 100 000 300 000 000 * *
Выплаты 100 000 300 000 000 * *
Прим.:
  1. Ограничения по времени выполнения операций зависят от банков, поддерживающих оплату этим методом. Базовое и предельное время определяются следующим образом:
    • Базовое время — среднее расчётное время проведения платежа от момента его инициирования на стороне платёжной платформы до момента отправки инициатору оповещения о результате. Это время определяется для условий штатной работы всех технических средств и каналов связи, а также типичных действий со стороны пользователя (там, где они необходимы). Базовое время рекомендуется использовать для реагирования на отсутствие оповещений о результате платежа и выполнения опроса состояния платежа (подробнее).
    • Предельное время — максимально допустимое время проведения платежа от момента его инициирования на стороне платёжной платформы до момента отправки инициатору оповещения о результате. Если платёж не был проведён или отклонён за это время, он автоматически переводится в статус decline. Для индивидуальной настройки предельного времени следует обращаться к специалистам технической поддержки ecommpay.

Сценарии использования

Проведение оплат с использованием метода Vietnamese Online Banking осуществляется с перенаправлением пользователей к сервису банка, проведение выплат — с уведомлением пользователей через веб-сервис мерчанта.

Пользовательский сценарий оплаты через Payment Page (в базовом варианте с выбором пользователем метода и банка и перенаправлением с итоговой страницы платёжной формы к веб-сервису) выглядит следующим образом.

Рис. 1. Переход к оплате


Рис. 2. Выбор метода


Рис. 3. Выбор банка


Рис. 4. Аутентификация


Рис. 5. Подтверждение платежа


Рис. 6. Возвращение к форме


Рис. 7. Возвращение к веб-сервису


Общие сценарии проведения оплат и выплат можно представить следующим образом.

Рис. 8. Оплата через Payment Page


Рис. 9. Оплата через Gate


Рис. 10. Выплата через Gate


Вместе с тем, к особенностям работы с методом Vietnamese Online Banking можно отнести то, что для каждого платежа с использованием этого метода должен быть выбран конкретный банк. При работе через Payment Page, как правило, выбор банка осуществляется пользователем уже в платёжной форме, но при вызовах Payment Page с предварительным выбором метода и банка, а также при инициировании оплат и выплат через Gate банк должен быть выбран на стороне веб-сервиса и в запросах должен указываться идентификатор этого банка. Возможные варианты выбора банка при работе через Payment Page описаны в разделе Оплаты через Payment Page этой статьи, а способы работы с идентификаторами банков — в следующем подразделе, Поддержка со стороны банков.

Вместе с тем, для оплат этим методом поддерживаются разные варианты выбора банка; они описаны в разделе Оплаты через Payment Page этой статьи.

Поддержка со стороны банков

В следующей таблице в ознакомительных целях приведены названия и идентификаторы банков, поддерживающих работу с методом Vietnamese Online Banking.

Рис. 11. Список банков
Банк 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 Gate API. В этом запросе должны указываться идентификатор проекта, идентификатор, валюта и сумма платежа и подпись к этим данным; при этом рекомендуется передавать реальные данные о платеже, но допускается и указание произвольных значений.

Рис. 12. Пример данных из запроса на получение списка банков
{
  "general": {
    "project_id": 200,
    "payment_id": "ORDER_155860015",
    "signature": "K6jllym+PtObocZtr345st...=="
  },
  "payment": {
    "amount": 1000,
    "currency": "VND"
  }
}
Рис. 13. Пример данных из ответа с информацией о банках
[
  {
    "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

Общая информация

Для проведения оплаты через Payment Page с использованием метода Vietnamese Online Banking со стороны веб-сервиса необходимо отправить запрос, содержащий требуемые параметры и подпись, на рабочий URL ecommpay и принять оповещение о результате. Полная схема проведения оплаты выглядит следующим образом.



Рис. 14. Проведение оплаты через Payment Page. Описание шагов
  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 (подробнее Формат запросов), при этом допустимы следующие варианты:

  • 1 — при открытии платёжной формы в ней последовательно отображаются отдельные страницы для выбора метода и банка, и пользователь выбирает сначала метод, а затем банк (этот вариант используется по умолчанию);
  • 2 — при открытии платёжной формы в ней отображается страница с кнопками выбора методов и банков для данного метода, и пользователь выбирает один из этих банков;
  • 3 — при открытии платёжной формы в ней отображается страница с кнопками выбора всех доступных банков для данного метода, и пользователь выбирает один из этих банков;
  • 4 — при открытии платёжной формы в ней отображается страница с кнопками выбора заданных банков для данного метода, и пользователь выбирает один из этих банков;
  • 5 — при открытии платёжной формы в ней отображается страница подтверждения перенаправления к сервису заданного банка, и пользователь соглашается с этим перенаправлением.
Рис. 15. 1 — Выбор метода и банка
Рис. 16. 2 — Выбор банка среди доступных методов
Рис. 17. 3 — Выбор среди доступных банков
Рис. 18. 4 — Выбор среди заданных банков
Рис. 19. 5 — Перенаправление к сервису заданного банка

Информация о форматах запросов и оповещений, используемых для проведения оплат методом Vietnamese Online Banking через Payment Page, приведена далее в этом разделе; общая информация о работе с Payment Page API — в отдельной статье Организация взаимодействия.

Формат запросов

При формировании запросов на открытие платёжной формы с применением метода Vietnamese Online Banking необходимо учитывать следующее:

  1. Должен использоваться базовый минимум параметров, обязательный для любого платежа:
    • project_id — идентификатор проекта, полученный от ecommpay при интеграции;
    • payment_id — идентификатор платежа, уникальный в рамках проекта;
    • payment_currency — код валюты платежа в формате ISO-4217 alpha-3;
    • payment_amount — сумма платежа (без выделения дробной части, поскольку при работе с валютой VND дробные единицы не используются);
    • customer_id — идентификатор пользователя в рамках проекта.
  2. Должен использоваться базовый минимум параметров: project_id, payment_id, payment_currency, payment_amount, customer_id.

  3. Вариант выбора банка может определяться следующим образом:

    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: 
      "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 с массивом, включающим в себя идентификаторы целевых банков:
        "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 с массивом, включающим в себя идентификатор целевого банка:
        "payment_methods_options": "{\"online_vietnam_banks\": {\"split_banks\": true, \"banks_id\": [134]}}"
  4. Дополнительно могут использоваться любые другие параметры из числа доступных для работы с Payment Page (подробнее).
  5. После указания всех целевых параметров необходимо составлять подпись (подробнее).

Таким образом, корректный запрос на открытие платёжной формы с применением метода Vietnamese Online Banking должен содержать идентификатор проекта, базовые сведения о платеже (идентификатор, сумму и код валюты), идентификатор пользователя и подпись.

{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 1000000,
   "payment_currency": "VND",
   "customer_id": "customer1",
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}
Рис. 20. Пример достаточного набора данных для запроса на оплату
{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 1000000,
   "payment_currency": "VND",
   "customer_id": "customer1",
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}

Вместе с тем, в случае с выбором из заданных банков (4), запрос на открытие Payment Page может содержать расширенный набор данных.

{
   "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=="
}

Формат оповещений

Для оповещений о результатах оплат с применением метода Vietnamese Online Banking используется типовой формат, описание которого представлено в разделе Оповещения.

В следующем примере оповещение свидетельствует о том, что в рамках проекта 200 была проведена оплата в размере 100 000 VND.

Рис. 21. Пример данных из оповещения о проведении оплаты
 {
        "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=="
    }

В следующем примере оповещение свидетельствует об отклонённой оплате.

Рис. 22. Пример данных из оповещения об отклонении оплаты
{
        "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=="
    }

Дополнительные материалы

Для организации работы с оплатами через Payment Page также могут быть полезны следующие материалы:

Оплаты через Gate

Общая информация

Для проведения оплаты через Gate с использованием метода Vietnamese Online Banking со стороны веб-сервиса необходимо:

  1. Отправить запрос, содержащий требуемые параметры и подпись, на рабочий URL ecommpay.
  2. Принять промежуточное оповещение от платёжной платформы и осуществить перенаправление пользователя к сервису банка.
  3. Принять итоговое оповещение от платёжной платформы.


Рис. 23. Проведение оплаты через Gate. Описание шагов
  1. Пользователь на стороне веб-сервиса инициирует оплату с использованием метода Vietnamese Online Banking.
  2. От веб-сервиса на заданный URL ecommpay передаётся запрос на проведение оплаты через Gate.
  3. Запрос на проведение оплаты поступает в платёжную платформу ecommpay.
  4. В платёжной платформе выполняется приём запроса с проверкой наличия обязательных параметров и корректной подписи.
  5. От платёжной платформы к веб-сервису направляется ответ с информацией о получении запроса и его корректности (подробнее).
  6. В платёжной платформе выполняются дальнейшая обработка запроса (с проверкой согласованности параметров) и его оправка в сервис банка.
  7. В сервисе банка выполняется обработка запроса на оплату.
  8. От сервиса банка к платёжной платформе передаются данные для перенаправления пользователя к сервису банка.
  9. От платёжной платформы к веб-сервису направляется оповещение с данными для перенаправления пользователя к сервису банка.
  10. Пользователь перенаправляется к сервису банка.
  11. Пользователь выполняет необходимые действия для оплаты.
  12. В сервисе банка выполняется обработка платежа.
  13. Пользователю отображается информация о результате оплаты.
  14. Пользователь перенаправляется к веб-сервису.
  15. От сервиса банка к платёжной платформе направляется информация о результате оплаты.
  16. От платёжной платформы к веб-сервису направляется оповещение о результате оплаты.
  17. На стороне веб-сервиса обеспечивается информирование пользователя о результате оплаты.

Информация о форматах запросов и оповещений, используемых для проведения оплат методом Vietnamese Online Banking через Gate, приведена далее в этом разделе; общая информация о работе с Gate API — в отдельной статье Организация взаимодействия.

Формат запросов

При формировании запросов на оплату с применением метода Vietnamese Online Banking необходимо учитывать следующее:

  1. Для инициирования каждой оплаты должен использоваться отдельный POST-запрос к конечной точке /v2/payment/banks/vietnam/sale. Эта конечная точка относится к группе /v2/payment/banks/{payment_method}/sale.
  2. В каждом запросе должны использоваться следующие объекты и параметры:
    • general — объект, содержащий основные идентификационные сведения запроса:
      • project_id — идентификатор проекта, полученный от ecommpay при интеграции;,
      • payment_id — идентификатор платежа, уникальный в рамках проекта;,
      • signature — подпись запроса, составленная после указания всех целевых параметров (подробнее — в разделе Работа с подписью); (подробнее),
    • payment — объект, содержащий сведения о платеже:
      • amount — сумма платежа (без выделения дробной части, поскольку при работе с валютой VND дробные единицы не используются);,
      • currency — код валюты платежа в формате ISO-4217 alpha-3;,
    • customer — объект, содержащий сведения о пользователе:
      • id — идентификатор пользователя, уникальный в рамках проекта;,
      • ip_address — IP-адрес пользователя, актуальный для инициируемого платежа;,
    • account — объект, содержащий сведения о банковском счёте пользователя:
      • bank_id — идентификатор банка.
  3. Дополнительно могут использоваться любые другие параметры из числа указанных в спецификации.

Таким образом, корректный запрос на оплату с применением метода Vietnamese Online Banking должен содержать идентификатор проекта, базовые сведения о платеже (идентификатор, сумму и код валюты), идентификатор и IP-адрес пользователя, а также идентификатор банка и подпись.

{
    "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 
    }
}
Рис. 24. Пример достаточного набора данных для запроса на оплату
{
    "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 
    }
}

Формат промежуточных оповещений для перенаправления пользователей

Для перенаправления пользователей от веб-сервиса мерчанта к сервису Vietnamese Online Banking при проведении каждого платежа с использованием метода Vietnamese Online Banking необходимо принять промежуточное оповещение от платёжной платформы и использовать информацию из него, включённую в объект redirect_data. Формат таких оповещений является типовым (подробнее), при этом в состав объекта redirect_data включаются следующие объекты и параметры:

  • body — объект с данными для отправки в теле запроса;
  • method — параметр с указанием HTTP-метода отправки запроса (GET или POST);
  • url — параметр со ссылкой для перенаправления.
Рис. 25. Пример объекта redirect_data
  "redirect_data": {
    "body": {},
    "method": "GET",
    "url": "https://www.example.com/pay"
  }

Формат итоговых оповещений

Для оповещений о результатах оплат с применением метода Vietnamese Online Banking используется типовой формат, описание которого представлено в разделе Оповещения.

В следующем примере оповещение свидетельствует о том, что в рамках проекта 200 была проведена оплата в размере 300 000 VND.

Рис. 26. Пример данных из оповещения о проведении оплаты
 {
        "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=="
    }

В следующем примере оповещение свидетельствует об отклонённой оплате.

Рис. 27. Пример данных из оповещения об отклонении оплаты
{
        "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=="
    }

Дополнительные материалы

Для организации работы с оплатами через Gate также могут быть полезны следующие материалы:

Выплаты через Gate

Общая информация

Для проведения выплаты через Gate с использованием метода Vietnamese Online Banking со стороны веб-сервиса необходимо отправить запрос, содержащий требуемые параметры и подпись, на рабочий URL ecommpay и принять оповещение о результате. Полная схема проведения выплаты выглядит следующим образом.



Рис. 28. Проведение выплаты через Gate. Описание шагов
  1. Пользователь на стороне веб-сервиса инициирует выплату через Vietnamese Online Banking.
  2. От веб-сервиса на заданный URL ecommpay передаётся запрос на проведение выплаты через Gate.
  3. Запрос на проведение выплаты поступает в платёжную платформу.
  4. В платёжной платформе выполняется приём запроса с проверкой наличия обязательных параметров и корректной подписи.
  5. От платёжной платформы к веб-сервису направляется ответ с информацией о получении запроса и его корректности. Подробнее — в разделе Формат ответа.
  6. В платёжной платформе обеспечиваются дальнейшая обработка запроса (с проверкой согласованности параметров) и его отправка в сервис Vietnamese Online Banking.
  7. В сервисе Vietnamese Online Banking выполняется обработка выплаты.
  8. От сервиса Vietnamese Online Banking к платёжной платформе направляется информация о результате выплаты.
  9. От платёжной платформы к веб-сервису направляется оповещение о результате выплаты.
  10. На стороне веб-сервиса обеспечивается информирование пользователя о результате выплаты.

Информация о форматах запросов и оповещений, используемых для проведения выплат методом Vietnamese Online Banking через Gate, приведена далее в этом разделе; общая информация о работе с Gate API — в отдельной статье Организация взаимодействия.

Формат запросов

При формировании запросов на выплату с применением метода Vietnamese Online Banking необходимо учитывать следующее:

  1. Для инициирования каждой выплаты должен использоваться отдельный POST-запрос к конечной точке /v2/payment/banks/vietnam/payout. Эта точка относится к группе /v2/payment/banks/{payment_method}/payout.
  2. В каждом запросе должны использоваться следующие объекты и параметры:
    • general — объект, содержащий основные идентификационные сведения запроса:
      • project_id — идентификатор проекта, полученный от ecommpay при интеграции;,
      • payment_id — идентификатор платежа, уникальный в рамках проекта;,
      • signature — подпись запроса, составленная после указания всех целевых параметров (подробнее — в разделе Работа с подписью); (подробнее),
    • payment — объект, содержащий сведения о платеже:
      • amount — сумма платежа (без выделения дробной части, поскольку при работе с валютой VND дробные единицы не используются);,
      • currency — код валюты платежа в формате ISO-4217 alpha-3;,
    • customer — объект, содержащий сведения о пользователе:
      • id — идентификатор пользователя, уникальный в рамках проекта;,
      • ip_address — IP-адрес пользователя, актуальный для инициируемой выплаты;,
    • account — объект, содержащий сведения о банковском счёте пользователя:
      • number — номер счёта;,
      • customer_name — имя держателя банковского счета;,
      • bank_id — идентификатор банка.
  3. Дополнительно могут использоваться любые другие параметры из числа указанных в спецификации.

Таким образом, корректный запрос на выплату с применением метода Vietnamese Online Banking должен содержать идентификатор проекта, базовые сведения о платеже (его идентификатор, сумму и код валюты), идентификатор и IP-адрес пользователя, информацию о счёте и подпись.

{
    "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"
    }
}
Рис. 29. Пример достаточного набора данных для запроса на выплату
{
    "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"
    }
}

Формат оповещений

Для оповещений о результатах выплат с применением метода Vietnamese Online Banking используется типовой формат, описание которого представлено в разделе Оповещения.

В следующем примере оповещение свидетельствует о том, что в рамках проекта 200 была проведена выплата в размере 100 001 VND.

Рис. 30. Пример данных из оповещения о проведении выплаты
{
        "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=="
    }

В следующем примере оповещение свидетельствует об отклонённой выплате.

Рис. 31. Пример данных из оповещения об отклонении выплаты
{
        "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=="
    }

Дополнительные материалы

Для организации работы с выплатами через Gate также могут быть полезны следующие материалы:

  • Организация взаимодействия — о том, как взаимодействовать с платёжной платформой через Gate.
  • Работа с подписью — о порядке создания и проверки подписи в программных запросах и оповещениях при взаимодействии с платёжной платформой.
  • Модель проведения платежей — о типах, схемах проведения и возможных статусах поддерживаемых платежей и операций.
  • Выплаты — о том, как проводить выплаты через Gate.
  • Информация об операциях — о служебных кодах, используемых в платёжной платформе для фиксации информации о выполнении операций.

Выплаты через Dashboard

При использовании интерфейса Dashboard можно проводить одиночные и массовые выплаты методом Vietnamese Online Banking с единичной и пакетной отправкой запросов, называемые соответственно одиночными и массовыми.

  • Для проведения одиночной выплаты необходимо открыть форму выплаты, задать все необходимые параметры (включая метод), отправить запрос и убедиться в проведении выплаты.

  • Для проведения массовой выплаты необходимо подготовить и загрузить файл с информацией обо всех целевых выплатах, отправить пакет запросов и убедиться в проведении выплат.

    При этом должен использоваться файл формата CSV, структура которого соответствует требованиям, представленным в разделе Сведения о массовых платежах, а параметры выплат — должны соответствовать требованиям, представленным в разделе Выплаты через Gate этой статьи (за исключением пункта о подписи).

Более подробная информация о проведении выплат через Dashboard представлена в отдельной статье.

Тестирование

Общая информация

Для метода Vietnamese Online Banking доступно тестирование оплат через Payment Page и Gate, а также выплат через Gate. Тестирование может выполняться в рамках тестового проекта, и для подключения и отключения этой функциональности следует обращаться к специалистам технической поддержки ecommpay.

При тестировании платежей следует учитывать, что в запросах должен указываться идентификатор тестового проекта, а интерфейсы эмулятора платёжных форм Payment Page и Vietnamese Online Banking могут отличаться от рабочих.

Статусы тестовых платежей

При тестировании оплат их итоговые статусы определяются исходя из сумм, указанных в запросах:

  • decline — при указании суммы 40000 или 40400,
  • success — при указании любой другой суммы.

При тестировании выплат их итоговые статусы определяются исходя из сумм, указанных в запросах:

  • decline — при указании суммы 40000 или 40400,
  • success — при указании любой другой суммы.

Оплаты через Payment Page

Для проведения тестовой оплаты через Payment Page необходимо:

  1. Отправить в платёжную платформу корректный тестовый запрос на открытие Payment Page.
  2. Если в запросе не был указан метод online-vietnam-banks — выбрать метод Vietnamese Online Banking на странице эмулятора.
  3. Если для выбора доступно несколько банков, то выбрать банк; если для выбора доступен только один банк, то щёлкнуть кнопку Оплатить.
  4. Щёлкнуть кнопку Success или Decline (в зависимости от запрашиваемой суммы).
  5. Принять итоговое оповещение с информацией о результате оплаты.

Более подробная информация о проведении оплат с использованием метода Vietnamese Online Banking через Payment Page представлена в разделе Оплаты через Payment Page этой статьи.

Оплаты через Gate

Для проведения тестовой оплаты через Gate необходимо:

  1. Отправить в платёжную платформу корректный тестовый запрос на оплату (с указанием идентификатора банка в параметре bank_id, идентификатор следует уточнять у службы технической поддержки ecommpay).
  2. Принять промежуточное оповещение с данными для перенаправления.
  3. Перейти по полученному URL и щёлкнуть кнопку Success или Decline (в зависимости от запрашиваемой суммы) — на странице эмулятора.
  4. Принять итоговое оповещение с информацией о результате оплаты.

Более подробная информация о проведении оплат с использованием метода Vietnamese Online Banking через Gate представлена в разделе Оплаты через Gate этой статьи.

Выплаты через Gate

Для проведения тестовой выплаты через Gate необходимо отправить в платёжную платформу корректный тестовый запрос и принять итоговое оповещение с информацией о результате. Более подробная информация о проведении выплат с использованием метода Vietnamese Online Banking представлена в разделе Выплаты через Gate этой статьи.

Анализ результатов проведения платежей

Для анализа информации о платежах и операциях, как в отдельности по методу Vietnamese Online Banking, так и в совокупности с другими методами, можно использовать:

  • инструментарий интерфейса Dashboard, с различными реестрами и аналитическими панелями;,
  • отчёты в формате CSV, выгружаемые (как разово, так и периодически) через раздел Отчёты интерфейса Dashboard;,
  • данные в формате JSON, получаемые по программным запросам через интерфейс Data API.

С вопросами по анализу информации можно обращаться к разделам документации (Dashboard и Использование Data API) и специалистам ecommpay.