# VietQR {#pm_vietqr} статья о работе с платёжным методом VietQR, который позволяет проводить платежи в донгах с использованием банковских счетов во Вьетнаме и для которого в платёжной платформе Ecommpay поддерживаются оплаты и возвраты. **На уровень выше:**[Платежи с помощью QR-кодов](ru_pm_qr.md) ## Обзор {#ru_pm_vietqr_overview} ### Введение {#section_ql3_5fj_stb .section} VietQR — метод, позволяющий проводить платежи в донгах с использованием банковских счетов во Вьетнаме. VietQR был разработан Национальной платёжной корпорацией Вьетнама\(National Payment Corporation of Vietnam, NAPAS\) совместно с Ассоциацией банков Вьетнама и широко используется в стране. Для этого метода в платёжной платформе Ecommpay поддерживаются оплаты и возвраты. В рамках оплаты методом VietQR пользователь сканирует QR-код мерчанта через приложение своего банка и переводит деньги мерчанту напрямую со своего банковского счёта. Возврат методом VietQR также выполняется непосредственно на банковский счёт пользователя, который использовался для оплаты. Такой сценарий применения наряду со статусом метода способствует доверию пользователей и активному применению метода. В этой статье представлена информация о работе с методом VietQR: обзорный раздел с общими сведениями и последующие разделы с информацией о действиях, необходимых со стороны мерчанта для решения разных задач. ### Характеристика {#section_tbf_2zk_ggb .section} |Тип платёжного метода|платежи с помощью QR-кодов| |Платёжные инструменты|банковские счета| |Регионы использования|[VN](references/ru/countries/VN.md)| |Валюты платежей|[VND](references/ru/currencies/VND.md)| |Конвертация валют|на стороне Ecommpay| |Разовые оплаты|+| |Повторяемые оплаты|–| |Полные возвраты|+| |Частичные возвраты|–| |Выплаты|–| |Опротестования|–| |Особенности|- поскольку [VND](references/ru/currencies/VND.md) не имеет дробных разрядов, суммы в этой валюте идентичны в целых и дробных единицах - время действия QR-кода на стороне провайдера по умолчанию составляет 20 минут, его можно изменить по согласованию с курирующим менеджером Ecommpay - выполнение возвратов допускается через обращение к специалистам технической поддержки Ecommpay \(подробнее [далее](pm_vietqr.md#section_z4k_knn_bkc)\) | |Организация и стоимость подключения|по согласованию с курирующим менеджером Ecommpay| ### Выполнение возвратов {#section_z4k_knn_bkc .section} Для выполнения возвратов методом VietQR необходимо обратиться в техническую поддержку Ecommpay и предоставить следующие сведения: - идентификатор исходной оплаты \(`payment_id`\) в платёжной платформе Ecommpay; - номер банковского счёта пользователя, использованного для списания средств при исходной оплате; - полное имя владельца указанного банковского счёта \(в соответствии с зарегистрированным в банке написанием\); - актуальное название банка, в котором обслуживается указанный счёт. На основании предоставленных сведений специалисты технической поддержки Ecommpay проверяют возможность возврата средств пользователю, инициируют этот возврат на стороне провайдера и предоставляют информацию о его результате специалистам мерчанта. При этом, если для выполнения возврата требуется дополнительная информация, её также запрашивают у специалистов мерчанта. Если возврат выполняется на стороне провайдера, в платформе регистрируется и выполняется операция `refund` и к веб-сервису отправляется оповещение о её выполнении \(со статусом `success`\). Если возврат отклоняется на стороне провайдера или банка, операция `refund` не регистрируется в платформе, а информация об отклонении возврата направляется специалистам мерчанта напрямую специалистами технической поддержки Ecommpay. Базовое время выполнения возврата по такой модели составляет один рабочий день. ### Схема работы {#section_tsp_gzk_ggb .section} В проведении отдельного платежа с использованием метода VietQR задействуются веб-сервис мерчанта, Gate и платёжная платформа Ecommpay, а также технические средства сервиса провайдера. ![](images/pm/ru_vietqr_functional.svg) ### Основные операции {#section_rnx_4cl_ggb .section} Для проведения платежей и выполнения операций с использованием метода VietQR могут применяться различные интерфейсы платёжной платформы. Так, оплаты могут проводиться через Payment Page и Gate. При этом, независимо от используемых интерфейсов, для каждой оплаты применимы ограничения по сумме и времени — с учётом того, через какой банк эта оплата проводится. ### Сценарии использования {#section_fgt_sdl_ggb .section} Проведение оплат с использованием метода VietQR осуществляется с отображением пользователям платёжной инструкции и QR-кода. ![](images/pm/ru_vietqr_interfaces_pp.svg "Оплата через Payment Page") ![](images/pm/ru_vietqr_interfaces_gate.svg "Оплата через Gate") ## Оплаты через Payment Page {#ru_pm_vietqr_pp_purchase} ### Общая информация {#section_gtg_vxk_m2b .section} Для проведения оплаты через Payment Pageс использованием метода VietQR со стороны веб-сервиса необходимо отправить запрос, содержащий требуемые параметры и подпись, на рабочий URL Ecommpay и принять оповещение о результате.Полная схема проведения оплаты выглядит следующим образом. ![](images/pm/ru_vietqr_uml_pp.svg) 1. Пользователь на стороне веб-сервиса инициирует оплату. 2. От веб-сервиса на заданный URL Ecommpay передаётся запрос на проведение оплаты через Payment Page. 3. Запрос на проведение оплаты поступает в платёжную платформу. 4. В платёжной платформе выполняется приём запроса с проверкой наличия обязательных параметров и корректной подписи. 5. Осуществляется подготовка Payment Page согласно параметрам проекта и вызова. 6. Пользователю отображается платёжная форма. 7. Пользователь выбирает для оплаты метод VietQR. 8. В платёжную платформу передаётся запрос на проведение оплаты с использованием метода VietQR. 9. В платёжной платформе обеспечиваются обработка полученного запроса и его отправка в сервис провайдера. 10. В сервисе провайдера выполняется обработка запроса на оплату. 11. От сервиса провайдера к платёжной платформе передаются данные для отображения платёжной инструкции пользователю. 12. Данные для отображения платёжной инструкции пользователю передаются к Payment Page. 13. Пользователю отображается платёжная инструкция. 14. Пользователь выполняет необходимые действия для оплаты согласно инструкции. 15. В сервисе провайдера выполняется обработка платежа. 16. От сервиса провайдера к платёжной платформе направляется информация о результате оплаты. 17. От платёжной платформы к веб-сервису направляется оповещение о результате оплаты. 18. От платёжной платформы к Payment Page направляется информация о результате оплаты. 19. Информация о результате оплаты отображается пользователю на Payment Page. Информация о форматах запросов и оповещений, используемых для проведения оплат методом VietQR через Payment Page, приведена далее в этом разделе; общая информация о работе с Payment Page API — в отдельной статье [Организация взаимодействия](ru_pp_interaction_organisation.md). ### Формат запросов {#section_p5j_fgl_ggb .section} При формировании запросов на открытие платёжной формы с применением метода VietQR необходимо учитывать следующее: 1. Должен использоваться базовый минимум параметров, обязательный для любого платежа: - `project_id` — идентификатор проекта, полученный от Ecommpay при интеграции; - `payment_id` — идентификатор платежа, уникальный в рамках проекта; - `payment_currency` — буквенный код валюты платежа в формате ISO-4217 alpha-3; - `payment_amount` — сумма платежа в дробных единицах валюты \(для [VND](references/ru/currencies/VND.md) эта сумма соответствует сумме в целых единицах валюты\); - `customer_id` — идентификатор пользователя в рамках проекта. 2. Для предварительного выбора метода VietQR необходимо указывать в параметре `force_payment_method` код платёжного метода — `vietqr`. 3. Дополнительно могут использоваться любые другие параметры из числа доступных для работы с Payment Page \([подробнее](ru_PP_Parameters.md)\). 4. После указания всех целевых параметров необходимо составлять подпись \([подробнее](ru_platform_signature.md)\). Таким образом, корректный запрос на открытие платёжной формы с применением метода VietQR должен содержать идентификатор проекта, базовые сведения о платеже \(идентификатор, сумму и код валюты\), информацию о пользователе и подпись, а также может содержать различные дополнительные параметры. ```language-json { "project_id": 120, "payment_id": "580", "payment_amount": 1000, "payment_currency": "VND", "customer_id": "customer1", "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg==" } ``` ``` {#codeblock_b4k_r4y_2kc .language-json} { "project_id": 120, "payment_id": "580", "payment_amount": 1000, "payment_currency": "VND", "customer_id": "customer1", "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg==" } ``` ### Формат оповещений {#section_dpx_2hl_ggb .section} Для оповещений о результатах оплат с применением метода VietQR используется типовой формат, описание которого представлено в статье [Работа с оповещениями](ru_platform_callbacks.md). В следующем примере оповещение свидетельствует о том, что в рамках проекта `1234` была проведена оплата в размере `300 000 VND`. ``` {#codeblock_o4y_yd5_bkc .language-json} { "project_id": 1234, "payment": { "id": "payment_47", "type": "purchase", "status": "success", "date": "2022-03-25T11:08:45+0000", "method": "VietQR", "sum": { "amount": 300000, "currency": "VND" }, "description": "" }, "customer": { "id": "customer_123" }, "operation": { "id": 28, "type": "sale", "status": "success", "date": "2022-03-25T11:08:45+0000", "created_date": "2022-03-25T11:08:05+0000", "request_id": "9e32835fb27907e042b5cf60a4e17839", "sum_initial": { "amount": 300000, "currency": "VND" }, "sum_converted": { "amount": 300000, "currency": "VND" }, "code": "0", "message": "Success", "provider": { "id": 12345, "payment_id": "123abc123-321", "auth_code": "" } }, "signature": "U7HQO7ToISZhMPkUKQtoYzFvoB3cs9CRd4xeYG2Q==" } ``` В следующем примере оповещение свидетельствует о том, что оплата была отклонена. ``` {#codeblock_gsg_zd5_bkc .language-json} { "project_id": 1234, "payment": { "id": "payment_47", "type": "purchase", "status": "decline", "date": "2022-03-25T11:20:30+0000", "method": "VietQR", "sum": { "amount": 300000, "currency": "VND" }, "description": "" }, "customer": { "id": "customer_123" }, "operation": { "id": 31, "type": "sale", "status": "decline", "date": "2022-03-25T11:20:30+0000", "created_date": "2022-03-25T11:19:53+0000", "request_id": "fff3d5f8d5d31bc460b68b57dc63f4b482e906eb", "sum_initial": { "amount": 300000, "currency": "VND" }, "sum_converted": { "amount": 300000, "currency": "VND" }, "code": "20000", "message": "General decline", "provider": { "id": 15923, "payment_id": "0cf4215c-8978", "auth_code": "" } }, "signature": "J7W15rkqrLzTC4z2iFYv58P4VnHANu445/jmY+g==" } ``` ### Дополнительные материалы {#section_xpz_thl_ggb .section} Для организации работы с оплатами через Payment Page также могут быть полезны следующие материалы: - [Организация взаимодействия](ru_pp_interaction_organisation.md)— о том, как организовать взаимодействие веб-сервиса с платёжной платформой через Payment Page. - [Работа с подписью к данным](ru_platform_signature.md)— о порядке создания и проверки подписи в программных запросах и оповещениях при взаимодействии с платёжной платформой. - [Проведение платежей](ru_platform_payment_model.md)— о типах, схемах проведения и возможных статусах поддерживаемых платежей и операций. - [Проведение оплат](ru_pp_purchase.md)— о том, как проводить разовые оплаты с незамедлительным списанием средств через Payment Page. - [Работа с информацией об операциях](ru_platform_payment_info_codes.md)— о служебных кодах, которые используются в платёжной платформе, чтобы фиксировать информацию о выполнении операций. ## Оплаты через Gate {#ru_pm_vietqr_gate_purchase} ### Общая информация {#section_lsx_3jl_ggb .section} Для проведения оплаты через Gate с использованием метода VietQR со стороны веб-сервиса необходимо: 1. Отправить запрос, содержащий требуемые параметры и подпись, на рабочий URL Ecommpay. 2. Принять промежуточное оповещение от платёжной платформы и отобразить пользователю платёжную инструкцию и QR-код. 3. Принять итоговое оповещение от платёжной платформы. Полная схема проведения оплаты выглядит следующим образом. ![](images/pm/ru_vietqr_uml_gate.svg) 1. Пользователь на стороне веб-сервиса инициирует оплату с использованием метода VietQR. 2. От веб-сервиса на заданный URL Ecommpay передаётся запрос на проведение оплаты через Gate. 3. Запрос на проведение оплаты поступает в платёжную платформу Ecommpay. 4. В платёжной платформе выполняется приём запроса с проверкой наличия обязательных параметров и корректной подписи. 5. От платёжной платформы к веб-сервису направляется ответ с информацией о получении запроса и его корректности \([подробнее](ru_gate_interaction_organisation.md)\). 6. В платёжной платформе выполняются дальнейшая обработка запроса \(с проверкой корректности параметров и соблюдения используемых правил и ограничений\) и его отправка в сервис провайдера. 7. В сервисе провайдера выполняется обработка запроса на оплату. 8. От сервиса провайдера к платёжной платформе передаются данные для отображения инструкции пользователю. 9. От платёжной платформы к веб-сервису направляется оповещение с данными для отображения платёжной инструкции пользователю. 10. Пользователю на стороне веб-сервиса отображается платёжная инструкция. 11. Пользователь выполняет необходимые действия для оплаты согласно инструкции. 12. В сервисе провайдера выполняется обработка оплаты. 13. От сервиса провайдера к платёжной платформе направляется информация о результате оплаты. 14. От платёжной платформы к веб-сервису направляется оповещение о результате оплаты. 15. На стороне веб-сервиса обеспечивается информирование пользователя о результате оплаты. Информация о форматах запросов и оповещений, используемых для проведения оплат методом VietQR через Gate, приведена далее в этом разделе; общая информация о работе с Gate API — в отдельной статье [Организация взаимодействия](ru_gate_interaction_organisation.md). ### Формат запросов {#section_osx_3jl_ggb .section} При работе с запросами на оплаты с применением метода VietQR необходимо учитывать следующее: 1. Для инициирования каждой оплаты должен использоваться отдельный POST-запрос к конечной точке [/v2/payment/vietqr/sale](https://api-developers.ecommpay.com/api-specification/vietqr/post-v2-payment-vietqr-sale). 2. В каждом запросе должны использоваться следующие объекты и параметры: - `general` — объект, содержащий основные идентификационные сведения запроса: - `project_id` — идентификатор проекта, полученный от Ecommpay при интеграции; - `payment_id` — идентификатор платежа, уникальный в рамках проекта; - `signature` — подпись запроса, составленная после указания всех целевых параметров \(подробнее — в разделе [Работа с подписью к данным](ru_platform_signature.md)\); - `payment` — объект, содержащий сведения о платеже: - `amount` — сумма платежа \(для [VND](references/ru/currencies/VND.md) эта сумма соответствует сумме в целых единицах валюты\); - `currency` — буквенный код валюты платежав формате ISO-4217 alpha-3; - `customer` — объект, содержащий сведения о пользователе: - `id` — идентификатор пользователя, уникальный в рамках проекта; - `ip_address` — IP-адрес пользователя, актуальный для инициируемого платежа. 3. Дополнительно могут использоваться любые другие параметры из числа указанных в спецификации. Таким образом, корректный запрос на оплату с применением метода VietQR должен содержать идентификатор проекта, базовые сведения о платеже \(идентификатор, сумму и код валюты\), информацию о пользователе, подпись, а также может содержать различные дополнительные параметры. ```language-json { "general": { "project_id": 210, "payment_id": "test_payment", "signature": "PJkV8ej\/UG0Di8hTng6JvipTv+AWoXW\/9MTO8yJA==" }, "payment": { "amount": 1000, "currency": "VND" }, "customer": { "id": "customer123", "ip_address": "192.0.2.0" } } ``` ``` {#codeblock_a2m_q4y_2kc .language-json} { "general": { "project_id": 210, "payment_id": "test_payment", "signature": "PJkV8ej\/UG0Di8hTng6JvipTv+AWoXW\/9MTO8yJA==" }, "payment": { "amount": 1000, "currency": "VND" }, "customer": { "id": "customer123", "ip_address": "192.0.2.0" } } ``` ### Формат промежуточных оповещений для отображения платёжной инструкции {#section_fq5_ryf_r4b .section} Для отображения пользователям платёжной инструкции при проведении каждого платежа с использованием метода VietQR необходимо принять промежуточное оповещение от платёжной платформы и использовать информацию из него, включённую в массив `display_data`, формат таких оповещений является типовым \([подробнее](ru_platform_callbacks.md)\). В состав массива `display_data` включаются следующие параметры: - `type` — тип передаваемых данных \(в значении всегда передаётся `qr_data`\); - `title` — название передаваемых данных, которые необходимо отобразить пользователю \(в значении всегда передаётся `QR code`\); - `data` — строка, на основании которой на стороне веб-сервиса должен быть создан QR-код \(в соответствии со стандартом [ISO/IEC 18004:2015](https://www.iso.org/standard/62021.html)\). ```language-json "display_data": [ { "type": "qr_data", "title": "QR code", "data": "00020101000005800113C6616TTAE11" } ] ``` ### Формат итоговых оповещений {#section_wsx_3jl_ggb .section} Для итоговых оповещений об оплатах с применением метода VietQR используется типовой формат, описание которого представлено в статье [Работа с оповещениями](ru_platform_callbacks.md). В следующем примере оповещение свидетельствует о том, что в рамках проекта `1234` была проведена оплата в размере `300 000 VND`. ``` {#codeblock_o4y_yd5_bkc .language-json} { "project_id": 1234, "payment": { "id": "payment_47", "type": "purchase", "status": "success", "date": "2022-03-25T11:08:45+0000", "method": "VietQR", "sum": { "amount": 300000, "currency": "VND" }, "description": "" }, "customer": { "id": "customer_123" }, "operation": { "id": 28, "type": "sale", "status": "success", "date": "2022-03-25T11:08:45+0000", "created_date": "2022-03-25T11:08:05+0000", "request_id": "9e32835fb27907e042b5cf60a4e17839", "sum_initial": { "amount": 300000, "currency": "VND" }, "sum_converted": { "amount": 300000, "currency": "VND" }, "code": "0", "message": "Success", "provider": { "id": 12345, "payment_id": "123abc123-321", "auth_code": "" } }, "signature": "U7HQO7ToISZhMPkUKQtoYzFvoB3cs9CRd4xeYG2Q==" } ``` В следующем примере оповещение свидетельствует об отклонённой оплате. ``` {#codeblock_gsg_zd5_bkc .language-json} { "project_id": 1234, "payment": { "id": "payment_47", "type": "purchase", "status": "decline", "date": "2022-03-25T11:20:30+0000", "method": "VietQR", "sum": { "amount": 300000, "currency": "VND" }, "description": "" }, "customer": { "id": "customer_123" }, "operation": { "id": 31, "type": "sale", "status": "decline", "date": "2022-03-25T11:20:30+0000", "created_date": "2022-03-25T11:19:53+0000", "request_id": "fff3d5f8d5d31bc460b68b57dc63f4b482e906eb", "sum_initial": { "amount": 300000, "currency": "VND" }, "sum_converted": { "amount": 300000, "currency": "VND" }, "code": "20000", "message": "General decline", "provider": { "id": 15923, "payment_id": "0cf4215c-8978", "auth_code": "" } }, "signature": "J7W15rkqrLzTC4z2iFYv58P4VnHANu445/jmY+g==" } ``` ### Дополнительные материалы {#section_xsx_3jl_ggb .section} Для организации работы с оплатами через Gate также могут быть полезны следующие материалы: - [Организация взаимодействия](ru_gate_interaction_organisation.md)— о том, как организовать взаимодействие с платёжной платформой через Gate. - [Работа с подписью к данным](ru_platform_signature.md)— о порядке создания и проверки подписи в программных запросах и оповещениях при взаимодействии с платёжной платформой. - [Проведение платежей](ru_platform_payment_model.md)— о типах, схемах проведения и возможных статусах поддерживаемых платежей и операций. - [Оплата в одну стадию](ru_gate_payment_sale.md)— о том, как проводить разовые оплаты с незамедлительным списанием средств через Gate. - [Работа с информацией об операциях](ru_platform_payment_info_codes.md)— о служебных кодах, используемых в платёжной платформе для фиксации информации о выполнении операций. ## Анализ результатов проведения платежей {#ru_pm_vietqr_dash_analysis} Для анализа информации о платежах и операциях, как в отдельности по методу VietQR, так и в совокупности с другими методами, можно использовать: - инструментарийинтерфейса Dashboard, с различными реестрами и аналитическими панелями; - отчёты в формате CSV, выгружаемые\(как разово, так и периодически\) черезраздел **Отчёты** интерфейса Dashboard; - данные в формате JSON, получаемыепо программным запросам черезинтерфейс Data API. С вопросами по анализу информации можно обращаться к разделам документации \([Dashboard](ru_dbl_about.md) и [Использование Data API](ru_dbl_api_protocol.md)\) и специалистам Ecommpay.