Vietnamese QR banking

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

Схема работы

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

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

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

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

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

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

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

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

Далее в таблице в ознакомительных целях представлена информация об этих банках. Эту информацию можно уточнять у курирующего менеджера ECommPay, а также с помощью запроса /v2/info/banks/vietnam-qr/sale/list, относящегося к группе запросов /v2/info/banks/{payment_method}/{operationType}/list.

Запрос должен содержать идентификаторы проекта и платежа, подпись, валюту и сумму платежа, как указано в примере. Важно передавать реальные данные о платеже, но в случае если платёж еще не сформирован, для идентификатора платежа в запросе можно указать случайное значение.

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

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

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

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

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

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

1. Должен использоваться базовый минимум параметров — параметры, обязательные для любого платёжного метода:
   • project_id — идентификатор проекта, полученный от ECommPay при интеграции;
   • payment_id — идентификатор платежа, уникальный в рамках проекта;
   • payment_currency — валюта платежа в формате ISO-4217 alpha-3;
   • payment_amount — сумма платежа, без дробной части;
   • customer_id — идентификатор пользователя уникальный в рамках проекта.
2. Валютой платежа может быть только VND.
3. Для предварительного выбора метода Vietnamese QR banking необходимо указывать код платёжного метода vietnam-banks-qr в параметре force_payment_method.
4. Дополнительно можно настроить язык письма (английский или вьетнамский) с результатом оплаты. По умолчанию используется вьетнамский язык. Для изменения на английский необходимо передать в параметре customer.language код en.
5. Дополнительно могут использоваться любые другие параметры из числа доступных для работы с Payment Page. Детальная информация обо всех параметрах приведена в разделе Параметры открытия платежной формы Payment Page.
6. После определения всех параметров необходимо составить подпись. Подробную информацию см. в Работа с подписью к данным.

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

EPayWidget.run(
    { payment_id: 'X03936', 
      payment_amount: 3 000, 
      payment_currency: 'VND', 
      project_id: 100, 
      customer_id: 'customer1',
      signature: "kUi2x9dKHAVNU0FYldJrxh4yo8552Kt8KU+Y1Y4HASCQ9vySO8
                         5/RLCvhtT4DqtVUkDJrOcZzUCwX6R\/ekpZhkIQg=="
    }
)

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

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

В следующем примере оповещение свидетельствует о том, что в рамках проекта 200 для пользователя 1 была успешно проведена оплата в размере 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": "YreiJ0aXQgDVuo74tsBXpZ8tmJi0IRVCyFucJ1aYk4mjybiVRcd/0M
                                       iUb8E9twm5IDxiZ8C2sqcuuncjkbazWKg=="
    }
}

В следующем примере оплата была отклонена из-за несоответствия ограничениям по сумме.

{
        "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": "YreiJ0aXQgDVuo74tsBXpZ8tmJi0IRVCyFucJ1aYk4mjybiVRcd/0M
                                       iUb8E9twm5IDxiZ8C2sqcuuncjkbazWKg=="
    }
}

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

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

• Организация взаимодействия
• Работа с подписью к данным
• Модель проведения платежей
• Информация о выполнении операций

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

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

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

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

Информация о формате запросов и параметрах инициализации оплат методом Vietnamese QR banking через Gate, а также о формате оповещений о результатах оплат приведена далее, общая информация о работе с API см. в разделе Работа с API.

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

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

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

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

{
    "general": {
        "project_id": 603,
        "payment_id": "test_payment_1",
        "signature": "U5LCm6489ly9cXCKIVBNV0mFr4XiCruECSyQEbT1hSXJ70zuH4...=="
    },
    "payment": {
        "amount": 3000,
        "currency": "VND"
    },
    "account": {
        "bank_id": 505
    },
    "customer": {
        "email": "Betelgeuse@gmail.com",
        "ip_address": "248.121.176.220",
        "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 для пользователя 1 была успешно проведена оплата в размере 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": "YreiJ0aXQgDVuo74tsBXpZ8tmJi0IRVCyFucJ1aYk4mjybiVRcd/0M
                                       iUb8E9twm5IDxiZ8C2sqcuuncjkbazWKg=="
    }
}

В следующем примере оплата была отклонена из-за несоответствия ограничениям по сумме.

{
        "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": "YreiJ0aXQgDVuo74tsBXpZ8tmJi0IRVCyFucJ1aYk4mjybiVRcd/0M
                                       iUb8E9twm5IDxiZ8C2sqcuuncjkbazWKg=="
    }
}

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

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

• Организация взаимодействия
• Работа с подписью к данным
• Модель проведения платежей
• Информация о выполнении операций

Как и при работе с другими платёжными методами, которые предоставляет ECommPay, при использовании метода Vietnamese QR banking доступны разные способы анализа информации о платежах и операциях с применением этого метода — как в отдельности, так и в совокупности с другими методами.

Всю необходимую информацию можно получать и анализировать средствами Dashboard (Old Dashboard), в том числе с помощью аналитических панелей на вкладке Analytics.

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

• Dashboard (Old Dashboard) позволяет выгружать данные в форматах CSV и XLS с помощью инструментов на вкладке Платежи. При этом можно выполнять разовые выгрузки информации на локальный компьютер и задействовать периодическую выгрузку и отправку информации на заданные адреса электронной почты.
• Data API позволяет получать информацию в формате JSON и отправлять ее на заданный URL — для этого применяются запросы /operations/get.

С любыми вопросами о возможностях анализа можно обращаться в службу технической поддержки ECommPay.