Vietnamese QR banking

Введение

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

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

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

Схема работы

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

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

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

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

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

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

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

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

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

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

Сценарии выполнения операций через основные интерфейсы платёжной платформы соответствуют представленным на схемах. При использовании дополнительных возможностей (таких как платёжные ссылки) сценарии выполнения операций методом 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.

Поскольку со временем состав доступных банков может меняться, для получения актуальной информации рекомендуется использовать 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 с использованием метода Vietnamese QR banking со стороны веб-сервиса необходимо отправить запрос, содержащий требуемые параметры и подпись, на рабочий URL ecommpay и принять оповещение о результате. Полная схема проведения оплаты выглядит следующим образом.

Информация о форматах запросов и оповещений, используемых для проведения оплат методом 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.
• Работа с подписью к данным — о порядке создания и проверки подписи в программных запросах и оповещениях при взаимодействии с платёжной платформой.
• Модель проведения платежей — о типах, схемах проведения и возможных статусах поддерживаемых платежей и операций.
• Разовая оплата в одну стадию — о том, как проводить разовые оплаты через Payment Page.
• Информация о выполнении операций — о служебных кодах, которые используются в платёжной платформе, чтобы фиксировать информацию о выполнении операций.

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

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

Информация о форматах запросов и оповещений, используемых для проведения оплат методом 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_method — vietnam-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 также могут быть полезны следующие материалы:

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

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

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

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

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

Информация о форматах запросов и оповещений, используемых для проведения оплат методом 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.
• Работа с подписью к данным — о порядке создания и проверки подписи в программных запросах и оповещениях при взаимодействии с платёжной платформой.
• Модель проведения платежей — о типах, схемах проведения и возможных статусах поддерживаемых платежей и операций.
• Разовая оплата в одну стадию — о том, как проводить разовые оплаты через Gate.
• Информация об операциях — о служебных кодах, используемых в платёжной платформе для фиксации информации о выполнении операций.

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

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

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

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

Информация о форматах запросов и оповещений, используемых для проведения оплат методом 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": {
    "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 также могут быть полезны следующие материалы:

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