Vietnamese QR banking

Обзор

Введение

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

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

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

Тип платёжного метода платежи с помощью QR-кодов
Платёжные инструменты банковские счета
Регионы использования VN
Валюты платежей VND
Конвертация валют
Разовые оплаты +
Повторяемые оплаты
Полные возвраты по запросу в техническую поддержку ecommpay
Частичные возвраты
Выплаты *
Опротестования
Особенности
  • * поддерживается проведение выплат с использованием метода Vietnamese Online Banking
  • для валюты VND суммы указываются без дробной части
Организация и стоимость подключения по согласованию с курирующим менеджером ecommpay

Схема работы

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



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

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

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

Суммы, VND (канал 1) Суммы, VND (канал 2) ¹
минимум максимум минимум максимум
Оплаты 2 000 20 000 000 000 * *
Прим.:
  1. Информацию необходимо уточнять у курирующего менеджера ecommpay.

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

Проведение оплат с использованием метода Vietnamese QR banking осуществляется со сканированием QR-кода пользователем с помощью мобильного приложения.

Сценарии выполнения операций через основные интерфейсы платёжной платформы соответствуют представленным на схемах. При использовании дополнительных возможностей (таких как платёжные ссылки) сценарии выполнения операций методом Vietnamese QR banking соответствуют специфике этих возможностей.

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

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

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

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

Табл. 1. Канал 1. Список банков
Банк ID
Agribank 139
An Binh Commercial Joint Stock Bank (ABBANK) 465
Bac A Commercial Joint Stock Bank (Bac A Bank) 439
Bank for Investment and Development of Vietnam 136
Eximbank Vietnam 135
Indovina Bank Ltd. (IVB) 569
Joint Stock Commercial Bank for Foreign Trade of Vietnam 133
Military JSC Bank (MB) 447
Nam A commercial joint stock bank (NamABank) 452
Nam Viet Bank (NaviBank) 441
Orient Commercial Bank (PhuongDong Bank) 467
Saigon Hanoi Commercial Joint Stock Bank (SHB) 451
Sai Gon Joint Stock Commercial Bank (SCB) 460
Tien Phong Commercial Joint Stock Bank (TienPhongBank) 445
VietinBank 134
Vietnam International Bank 138
Vietnam Maritime Commercial Joint Stock Bank (MaritimeBank) 440
Vietnam Prosperity Bank (VPBank) 449
WeChat Pay 570
Табл. 2. Канал 2. Список банков
Банк ID
Asia Commercial Bank 150
Bank for Investment and Development of Vietnam 136
Tien Phong Commercial Joint Stock Bank (TienPhongBank) 445
Vietcombank 133
Vietnam Prosperity Bank (VPBank) 449

Поскольку со временем состав доступных банков может меняться, для получения актуальной информации рекомендуется использовать POST-запрос к конечной точке /v2/info/banks/vietnam-qr/sale/list, которая относится к группе конечных точек /v2/info/banks/{payment_method}/{operationType}/list Gate API. В этом запросе должны указываться идентификатор проекта, идентификатор, валюта и сумма платежа и подпись к этим данным; при этом рекомендуется передавать реальные данные о платеже, но допускается и указание произвольных значений.

Рис.: Пример данных из запроса на получение списка банков

{
  "general": {
    "project_id": 200,
    "payment_id": "ORDER_155860015",
    "signature": "K6jllym+PtObocZtr345st...=="
  },
  "payment": {
    "amount": 1000,
    "currency": "VND"
  }
}

Рис.: Пример данных из ответа с информацией о банках

[
  {
    "id": 139, // Индентификатор банка
    "abbr": "AGB", // Служебная аббревиатура банка, используемая в платформе
    "name": "AGB", // Основное (международное) название банка
    "nativeName": "Agribank", // Локальное (национальное или региональное) название банка
    "currencies": [ // Массив с информацией о валютах, поддерживаемых банком
      {
        "id": 104, // Идентификатор валюты в платёжной платформе
        "alpha_3_4217": "VND", // Буквенный код валюты платежа в формате ISO-4217 alpha-3
        "number_3_4217": "704", // Цифровой код валюты платежа в формате ISO-4217 alpha-3
        "exponent": 0 // Число дробных разрядов валюты
      }
    ]
  },
  {
    "id": 467, 
    "abbr": "OCB", 
    "name": "Orient Commercial Bank (PhuongDong Bank)", 
    "nativeName": "PhuongDong Bank", 
    "currencies": [
      {
        "id": 104,
        "alpha_3_4217": "VND",
        "number_3_4217": "704",
        "exponent": 0
      }
    ]
  },
  {
    "id": 445, 
    "abbr": "TPB", 
    "name": "Tien Phong Commercial Joint Stock Bank (TienPhongBank)", 
    "nativeName": "TienPhongBank", 
    "currencies": [
      {
        "id": 104,
        "alpha_3_4217": "VND",
        "number_3_4217": "704",
        "exponent": 0
      }
    ]
  }
]

С вопросами о работе с банками, поддерживающими метод Vietnamese QR banking, можно обращаться к курирующему менеджеру ecommpay.

Оплаты через Payment Page. Канал 1: без перенаправления пользователя

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

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



Рис.: Проведение оплаты через Payment Page. Описание шагов

  1. Пользователь на стороне веб-сервиса инициирует оплату.
  2. От веб-сервиса на заданный URL ecommpay передаётся запрос на проведение оплаты через Payment Page.
  3. Запрос на проведение оплаты поступает в платёжную платформу.
  4. В платёжной платформе выполняется приём запроса, с проверкой наличия обязательных параметров и корректной подписи.
  5. Осуществляется подготовка Payment Page согласно параметрам проекта и вызова.
  6. Пользователю отображается платёжная форма.
  7. Пользователь выбирает для оплаты метод Vietnamese QR banking.
  8. Пользователю отображается список доступных банков.
  9. Пользователь выбирает банк.
  10. В платёжную платформу передаётся запрос на проведение оплаты с использованием метода Vietnamese QR banking.
  11. В платёжной платформе выполняются обработка полученного запроса и его отправка в сервис Vietnamese QR banking.
  12. В сервисе Vietnamese QR banking выполняется обработка запроса на оплату.
  13. От сервиса Vietnamese QR banking к платёжной платформе передаются данные для отображения QR-кода пользователю.
  14. Данные для отображения QR-кода пользователю передаются к Payment Page.
  15. QR-код отображается пользователю в Payment Page.
  16. Пользователь сканирует QR-код с помощью мобильного приложения и выполняет необходимые действия для оплаты.
  17. В сервисе Vietnamese QR banking выполняется обработка платежа.
  18. От сервиса Vietnamese QR banking пользователю направляется письмо по электронной почте с результатом оплаты.
  19. От сервиса Vietnamese QR banking к платёжной платформе направляется информация о результате оплаты.
  20. От платёжной платформы к веб-сервису направляется оповещение о результате оплаты.
  21. От платёжной платформы к Payment Page направляется информация о результате оплаты.
  22. Информация о результате оплаты отображается пользователю на Payment Page.

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

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

При формировании запросов на открытие платёжной формы с применением метода Vietnamese QR 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. Валютой платежа может быть только VND.
  4. Для предварительного выбора метода Vietnamese QR banking необходимо указывать код платёжного метода vietnam-banks-qr в параметре force_payment_method.
  5. Дополнительно можно настроить язык письма (английский или вьетнамский) с результатом оплаты. По умолчанию используется вьетнамский язык. Для изменения на английский необходимо передать в параметре customer.language код en.
  6. Дополнительно могут использоваться любые другие параметры из числа доступных для работы с Payment Page (подробнее).
  7. После указания всех целевых параметров необходимо составлять подпись (подробнее).

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

{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 3 000,
   "payment_currency": "VND",
   "customer_id": "customer1",
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}

Рис.: Пример достаточного набора данных для запроса на оплату

{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 3 000,
   "payment_currency": "VND",
   "customer_id": "customer1",
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}

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

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

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

Рис.: Пример данных из оповещения о проведении оплаты

{
        "project_id": 200,
        "payment": {
            "id": "TEST_1561223423_VND1",
            "type": "purchase",
            "status": "success",
            "date": "2019-07-01T07:54:16+0000",
            "method": "Vietnam banks-qr",
            "sum": {
                "amount": 2000,
                "currency": "VND"
            },
            "description": "TEST_1561714332889"
        },
        "customer": {
            "id": "1",
            "phone": "0914695523"
        },
        "operation": {
            "id": 39811000003358,
            "type": "sale",
            "status": "success",
            "date": "2019-07-01T07:54:16+0000",
            "created_date": "2019-07-01T07:53:19+0000",
            "request_id": "1fb651fe71b5db9db3d6382c995c8f51b08785ff",
            "sum_initial": {
                "amount": 2000,
                "currency": "VND"
            },
            "sum_converted": {
                "amount": 2000,
                "currency": "VND"
            },
            "provider": {
                "id": 1283,
                "payment_id": "56366711",
                "auth_code": "",
                "endpoint_id": "TCB"
            },
            "code": "0",
            "message": "Success"
        },
        "signature": "YreiJ0aXQgDVuo74tsBXpZ8tmJi0IRVCyFkbazWKg=="
    }
}

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

Рис.: Пример данных из оповещения об отклонении оплаты

{
        "project_id": 200,
        "payment": {
            "id": "TEST_1561223423_VND1",
            "type": "purchase",
            "status": "decline",
            "date": "2019-07-01T07:54:16+0000",
            "method": "Vietnam banks-qr",
            "sum": {
                "amount": 1000,
                "currency": "VND"
            },
            "description": "TEST_1561714332889"
        },
        "customer": {
            "id": "1",
            "phone": "0914695523"
        },
        "operation": {
            "id": 39811000003358,
            "type": "sale",
            "status": "success",
            "date": "2019-07-01T07:54:16+0000",
            "created_date": "2019-07-01T07:53:19+0000",
            "request_id": "1fb651fe71b5db9db3d6382c995c8f51b08785ff",
            "sum_initial": {
                "amount": 1000,
                "currency": "VND"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "VND"
            },
            "provider": {
                "id": 1283,
                "payment_id": "56366711",
                "auth_code": "",
                "endpoint_id": "TCB"
            },
            "code": "20101",
            "message": "Decline due to amount or frequency limit"
        },
        "signature": "YreiJ0aXQgDVuo74tsBXpZ8tmJi0IsqcuuncjkbazWKg=="
    }
}

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

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

Оплаты через Payment Page. Канал 2: с перенаправлением пользователя

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

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



Рис.: Проведение оплаты через Payment Page. Описание шагов

  1. Пользователь на стороне веб-сервиса инициирует оплату.
  2. От веб-сервиса на заданный URL ecommpay передаётся запрос на проведение оплаты через Payment Page.
  3. Запрос на проведение оплаты поступает в платёжную платформу.
  4. В платёжной платформе выполняется приём запроса, с проверкой наличия обязательных параметров и корректной подписи.
  5. Осуществляется подготовка Payment Page согласно параметрам проекта и вызова.
  6. Пользователю отображается платёжная форма.
  7. Пользователь выбирает для оплаты метод Vietnamese QR banking.
  8. В платёжную платформу передаётся запрос на проведение оплаты с использованием метода Vietnamese QR banking.
  9. В платёжной платформе выполняются обработка полученного запроса и его отправка в сервис Vietnamese QR banking.
  10. В сервисе Vietnamese QR banking выполняется обработка запроса на оплату.
  11. От сервиса Vietnamese QR banking к платёжной платформе передаются данные для перенаправления пользователя к сервису Vietnamese QR banking.
  12. Данные для перенаправления пользователя передаются к Payment Page.
  13. Пользователь перенаправляется к сервису Vietnamese QR banking.
  14. Пользователь выполняет необходимые действия для оплаты.
  15. В сервисе Vietnamese QR banking выполняется обработка платежа.
  16. Информация о результате оплаты отображается пользователю в сервисе Vietnamese QR banking.
  17. Пользователь перенаправляется к Payment Page.
  18. От сервиса Vietnamese QR banking к платёжной платформе направляется информация о результате оплаты.
  19. От платёжной платформы к веб-сервису направляется оповещение о результате оплаты.
  20. От платёжной платформы к Payment Page направляется информация о результате оплаты.
  21. Информация о результате оплаты отображается пользователю на Payment Page.

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

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

При формировании запросов на открытие платёжной формы с применением метода Vietnamese QR 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. Дополнительно, в зависимости от провайдера, рекомендуется указывать адрес электронной почты пользователя в параметре customer_email. Если этот параметр отсутствует в запросе, в платёжной форме может отобразиться поле для ввода пользователем недостающего значения (подробнее — в разделе Дополнение информации о платежах).
  4. Для предварительного выбора метода Vietnamese QR banking необходимо указывать код этого метода в параметре force_payment_methodvietnam-banks-qr.
  5. Дополнительно могут использоваться любые другие параметры из числа доступных для работы с Payment Page (подробнее).
  6. После указания всех целевых параметров необходимо составлять подпись (подробнее).

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

{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 3 000,
   "payment_currency": "VND",
   "customer_id": "customer1",
   "customer_email": "john@example.com"
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}

Рис.: Пример достаточного набора данных для запроса на оплату

{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 3 000,
   "payment_currency": "VND",
   "customer_id": "customer1",
   "customer_email": "john@example.com"
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}

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

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

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

Рис.: Пример данных из оповещения о проведении оплаты

{
        "project_id": 3514,
        "payment": {
            "id": "EPd3f4-9b1a",
            "type": "purchase",
            "status": "success",
            "date": "2020-11-06T13:16:50+0000",
            "method": "Vietnam banks-qr",
            "sum": {
                "amount": 300000,
                "currency": "VND"
            },
            "description": ""
        },
        "customer": {
            "id": "123"
        },
        "operation": {
            "id": 233,
            "type": "sale",
            "status": "success",
            "date": "2020-11-06T13:16:50+0000",
            "created_date": "2020-11-06T13:16:36+0000",
            "request_id": "3fe344d57e581a37b16ddd8e7-00000001",
            "sum_initial": {
                "amount": 300000,
                "currency": "VND"
            },
            "sum_converted": {
                "amount": 300000,
                "currency": "VND"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 2673,
                "payment_id": "160466859929",
                "auth_code": ""
            }
        },
        "signature": "fF9J+3OdjdGux9liAxvDk5/Fublg9sMqOvypzgcMLZXG09ptOg=="
    }

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

Рис.: Пример данных из оповещения об отклонении оплаты

 {
        "project_id": 3514,
        "payment": {
            "id": "EP9ab9-a3a4",
            "type": "purchase",
            "status": "decline",
            "date": "2020-11-06T13:26:48+0000",
            "method": "Vietnam banks-qr",
            "sum": {
                "amount": 350000,
                "currency": "VND"
            },
            "description": ""
        },
        "customer": {
            "id": "456"
        },
        "operation": {
            "id": 236,
            "type": "sale",
            "status": "decline",
            "date": "2020-11-06T13:26:48+0000",
            "created_date": "2020-11-06T13:26:33+0000",
            "request_id": "2e084e9b6736091b032a78fbc46b18431-00000001",
            "sum_initial": {
                "amount": 350000,
                "currency": "VND"
            },
            "sum_converted": {
                "amount": 350000,
                "currency": "VND"
            },
            "code": "20000",
            "message": "General decline",
            "provider": {
                "id": 2673,
                "payment_id": "160466919625",
                "auth_code": ""
            }
        },
        "signature": "H8F+m5SL3ZxjnzCrsvjL5dXP50qJUXTOqqgKkHZA=="
    }

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

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

Оплаты через Gate. Канал 1: без перенаправления пользователя

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

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

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

Полная схема проведения оплаты выглядит следующим образом.

Рис.: Проведение оплаты через Gate. Описание шагов

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

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

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

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

  1. Для инициирования каждой оплаты должен использоваться отдельный POST-запрос к конечной точке /v2/payment/banks/vietnam-qr/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-адрес пользователя, актуальный для инициируемого платежа;,
      • email — адрес электронной почты пользователя;,
    • account — объект, содержащий сведения о счёте пользователя:
      • bank_id — идентификатор банка.
  3. Валютой платежа может быть только VND.
  4. Дополнительно можно настроить язык письма (английский или вьетнамский) с результатом оплаты. По умолчанию используется вьетнамский язык. Для изменения на английский необходимо передать в параметре customer.language код en.
  5. Дополнительно могут использоваться любые другие параметры из числа указанных в спецификации.

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

{
    "general": {
        "project_id": 603,
        "payment_id": "test_payment_1",
        "signature": "U5LCm6489ly9cXCKIVBT1hSXJ70zuH4=="
    },
    "payment": {
        "amount": 3000,
        "currency": "VND"
    },
    "account": {
        "bank_id": 505
    },
    "customer": {
        "email": "doe@exmaple.com",
        "ip_address": "192.0.2.0",
        "id": "customer123"
    }
}

Рис.: Пример достаточного набора данных для запроса на оплату

{
    "general": {
        "project_id": 603,
        "payment_id": "test_payment_1",
        "signature": "U5LCm6489ly9cXCKIVBT1hSXJ70zuH4=="
    },
    "payment": {
        "amount": 3000,
        "currency": "VND"
    },
    "account": {
        "bank_id": 505
    },
    "customer": {
        "email": "doe@exmaple.com",
        "ip_address": "192.0.2.0",
        "id": "customer123"
    }
}

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

Для завершения оплаты необходимо отобразить пользователям QR-код. Информация для отображения QR-кода содержится в оповещении от платёжной платформы в параметре qr_code в виде закодированного в Base64 изображения, поэтому прежде чем отобразить QR-код, надо принять и обработать такое оповещение.

Данное оповещение отправляется от платёжной платформы ecommpay на URL, указанный в настройках проекта мерчанта, для получения финального результата, а не для получения асинхронного ответа, как в случае с данными для перенаправления пользователей. Статус платежа в данном случае будет awaiting customer action до момента завершения оплаты со стороны пользователя.

Далее приведён фрагмент оповещения, содержащего данные QR-кода для оплаты.

"qr_code": "iVBORw0KGgoAAAANSUhEUgAAAG8AAABvAQMAAADYCwwjAAAABlBMVEX///
8AAABVwtN+AAAACXBIWXMAAA7EAAAOxAGVKw4bAAABG0lEQVQ4jdXTsY3FIAwGYCMXdLBApKxBx0qZ4AILJCvRsQYSC7x0FCg
+J3l3rwPahyj4CiT7lw3wjUcTOYNOIlHqUgH6MIHMDgZo8yZhMbiXIfpQweZxa\nsIhAjqbD/oU2SD3u5nM97/9Bq/vEnT8hNm
gLnRCEjQ7M8JJxwqG/N1CmyLMGycTcLN98l9R6CBY3lW1qCw5ixToNUDBJTFL9nc4HRaiMimT9AB1TBzjGuHnKbJJZWcfkgj4k
qlL4AmUlcN3tk8l8bwmsC6yTxEnHcgH3og+lcEj8ooRxT7vLvDkcEqf18TCpCTvWp+8C3vk8JMOA7yX8ZnbEXqqa+HHEHfK\nG
8AaBshVcZKxPovWJve7E4eZlr/2G/y+8wt5N/rpIH9KkwAAAABJRU5ErkJggg=="

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

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

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

Рис.: Пример данных из оповещения о проведении оплаты

{
        "project_id": 200,
        "payment": {
            "id": "TEST_1561223423_VND1",
            "type": "purchase",
            "status": "success",
            "date": "2019-07-01T07:54:16+0000",
            "method": "Vietnam banks-qr",
            "sum": {
                "amount": 2000,
                "currency": "VND"
            },
            "description": "TEST_1561714332889"
        },
        "customer": {
            "id": "1",
            "phone": "0914695523"
        },
        "operation": {
            "id": 39811000003358,
            "type": "sale",
            "status": "success",
            "date": "2019-07-01T07:54:16+0000",
            "created_date": "2019-07-01T07:53:19+0000",
            "request_id": "1fb651fe71b5db9db3d6382c995c8f51b08785ff",
            "sum_initial": {
                "amount": 2000,
                "currency": "VND"
            },
            "sum_converted": {
                "amount": 2000,
                "currency": "VND"
            },
            "provider": {
                "id": 1283,
                "payment_id": "56366711",
                "auth_code": "",
                "endpoint_id": "TCB"
            },
            "code": "0",
            "message": "Success"
        },
        "signature": "YreiJ0aXQgDVuo74tsBXpZ8tmJiqcuuncjkbazWKg=="
    }
}

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

Рис.: Пример данных из оповещения об отклонении оплаты

{
        "project_id": 200,
        "payment": {
            "id": "TEST_1561223423_VND1",
            "type": "purchase",
            "status": "decline",
            "date": "2019-07-01T07:54:16+0000",
            "method": "Vietnam banks-qr",
            "sum": {
                "amount": 1000,
                "currency": "VND"
            },
            "description": "TEST_1561714332889"
        },
        "customer": {
            "id": "1",
            "phone": "0914695523"
        },
        "operation": {
            "id": 39811000003358,
            "type": "sale",
            "status": "success",
            "date": "2019-07-01T07:54:16+0000",
            "created_date": "2019-07-01T07:53:19+0000",
            "request_id": "1fb651fe71b5db9db3d6382c995c8f51b08785ff",
            "sum_initial": {
                "amount": 1000,
                "currency": "VND"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "VND"
            },
            "provider": {
                "id": 1283,
                "payment_id": "56366711",
                "auth_code": "",
                "endpoint_id": "TCB"
            },
            "code": "20101",
            "message": "Decline due to amount or frequency limit"
        },
        "signature": "YreiJ0aXQgDVuo74tsBXpZ8tmJi0IRVcuuncjkbazWKg=="
    }
}

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

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

Оплаты через Gate. Канал 2: с перенаправлением пользователя

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

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

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

Полная схема проведения оплаты выглядит следующим образом.



Рис.: Проведение оплаты через Gate. Описание шагов

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

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

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

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

  1. Для инициирования каждой оплаты должен использоваться отдельный POST-запрос к конечной точке /v2/payment/banks/vietnam-qr/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-адрес пользователя, актуальный для инициируемого платежа;,
      • email — адрес электронной почты пользователя (обязательность этого параметра зависит от провайдера, который проводит платёж, подробности следует уточнять у курирующего менеджера ecommpay);
    • account — объект, содержащий сведения о счёте пользователя:
      • bank_id — идентификатор банка(обязательность этого параметра зависит от провайдера, который проводит платёж, подробности следует уточнять у курирующего менеджера ecommpay);
    • return_url — объект, содержащий URL для перенаправления пользователя в веб-сервис:
      • success — URL для перенаправления при проведённой оплате.
  3. Дополнительно могут использоваться любые другие параметры из числа указанных в спецификации.

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

{
    "general": {
      "project_id": 211,
      "payment_id": "payment_id",
      "signature": "PJkV8ej\/UG0Di8NN5e7cV+VHq3oXW\/9MTO8yJA=="
    },
    "payment": {
      "amount": 300000,
      "currency": "VND"
    },
    "customer": {
      "id": "123",
      "ip_address": "192.0.2.0",
      "email": "john@example.com"
    },
    "account": {
        "bank_id": 150
    },
    "return_url": {
      "success": "http://example.com/return"
    }  
}

Рис.: Пример достаточного набора данных для запроса на оплату

{
    "general": {
      "project_id": 211,
      "payment_id": "payment_id",
      "signature": "PJkV8ej\/UG0Di8NN5e7cV+VHq3oXW\/9MTO8yJA=="
    },
    "payment": {
      "amount": 300000,
      "currency": "VND"
    },
    "customer": {
      "id": "123",
      "ip_address": "192.0.2.0",
      "email": "john@example.com"
    },
    "account": {
        "bank_id": 150
    },
    "return_url": {
      "success": "http://example.com/return"
    }  
}

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

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

  • body — объект с данными для отправки в теле запроса;
  • method — параметр с указанием HTTP-метода отправки запроса (GET или POST);
  • url — параметр со ссылкой для перенаправления.

Рис.: Пример объекта redirect_data

  "redirect_data": {
    "body": {},
    "method": "GET",
    "url": "https://www.example.com/pay"
  }

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

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

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

Рис.: Пример данных из оповещения о проведении оплаты

{
        "project_id": 3514,
        "payment": {
            "id": "EPd3f4-9b1a",
            "type": "purchase",
            "status": "success",
            "date": "2020-11-06T13:16:50+0000",
            "method": "Vietnam banks-qr",
            "sum": {
                "amount": 300000,
                "currency": "VND"
            },
            "description": ""
        },
        "customer": {
            "id": "123"
        },
        "operation": {
            "id": 233,
            "type": "sale",
            "status": "success",
            "date": "2020-11-06T13:16:50+0000",
            "created_date": "2020-11-06T13:16:36+0000",
            "request_id": "3fe344d57e581a37b16ddd8e7507a65f5bef7dfaafc-00000001",
            "sum_initial": {
                "amount": 300000,
                "currency": "VND"
            },
            "sum_converted": {
                "amount": 300000,
                "currency": "VND"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 2673,
                "payment_id": "160466859929",
                "auth_code": ""
            }
        },
        "signature": "fF9J+3OdjdGux9liAxvDk5/Fublg9sMqOvypzgcMLZXG09ptOg=="
    }

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

Рис.: Пример данных из оповещения об отклонении оплаты

 {
        "project_id": 3514,
        "payment": {
            "id": "EP9ab9-a3a4",
            "type": "purchase",
            "status": "decline",
            "date": "2020-11-06T13:26:48+0000",
            "method": "Vietnam banks-qr",
            "sum": {
                "amount": 350000,
                "currency": "VND"
            },
            "description": ""
        },
        "customer": {
            "id": "456"
        },
        "operation": {
            "id": 236,
            "type": "sale",
            "status": "decline",
            "date": "2020-11-06T13:26:48+0000",
            "created_date": "2020-11-06T13:26:33+0000",
            "request_id": "2e084e9b6736091b032a78c46b18431-00000001",
            "sum_initial": {
                "amount": 350000,
                "currency": "VND"
            },
            "sum_converted": {
                "amount": 350000,
                "currency": "VND"
            },
            "code": "20000",
            "message": "General decline",
            "provider": {
                "id": 2673,
                "payment_id": "160466919625",
                "auth_code": ""
            }
        },
        "signature": "H8F+m5SL3ZxjnzCrsvjPSqQ2L5dXP50qJUXTOqqgKkHZA=="
    }

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

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

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

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

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

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