# QRIS {#pm_qris} **На уровень выше:**[Платежи с помощью QR-кодов](ru_pm_qr.md) ## Обзор {#ru_pm_qris_overview} статья о работе с платёжным методом QRIS, который позволяет проводить платежи в индонезийских рупиях с использованием банковских счетов и электронных кошельков в Индонезии и для которого в платформе Ecommpay поддерживаются оплаты ### Введение {#section_ql3_5fj_stb .section} QRIS — метод, позволяющий проводить платежи в индонезийских рупиях с использованием банковских счетов и электронных кошельков в Индонезии. Для работы с этим методом могут использоваться различные приложения, поддерживающие работу со стандартом [QRIS](https://qris.id/homepage) \(Quick Response Code Indonesian Standard\).Для этого метода в платёжной платформе Ecommpay поддерживаются оплаты. В этой статье представлена информация о работе с методом QRIS: обзорный раздел с общими сведениями и последующие разделы с информацией о действиях, необходимых со стороны мерчанта для решения разных задач. ### Характеристика {#section_tbf_2zk_ggb .section} |Тип платёжного метода|платежи с помощью QR-кодов| |Платёжные инструменты|- банковские счета - электронные кошельки | |Регионы использования|[ID](references/ru/countries/ID.md)| |Валюты платежей|[IDR](references/ru/currencies/IDR.md)| |Конвертация валют|на стороне Ecommpay| |Разовые оплаты|+| |Повторяемые оплаты|–| |Полные возвраты|–| |Частичные возвраты|–| |Выплаты|–| |Опротестования|+| |Особенности|при использовании валюты [IDR](references/ru/currencies/IDR.md) не поддерживается обработка платежей, для которых сумма платежа указана с дробной частью. В запросе на оплату с указанием валюты [IDR](references/ru/currencies/IDR.md) сумму оплаты необходимо округлять до целых чисел. Если в запросе указывается иная валюта, сумма платежа конвертируется на стороне Ecommpay в эквивалентную сумму в валюте [IDR](references/ru/currencies/IDR.md) и также округляется до целых чисел. Информацию об особенностях округления суммы следует уточнять у специалистов технической поддержки Ecommpay.| |Организация и стоимость подключения|по согласованию с курирующим менеджером Ecommpay| ### Схема работы {#section_tsp_gzk_ggb .section} В проведении отдельного платежа с использованием метода QRIS задействуются веб-сервис мерчанта, один из интерфейсов и платёжная платформа Ecommpay, а также технические средства сервиса провайдера. ![](images/pm/ru_qris_functional.svg) ### Основные операции {#section_rnx_4cl_ggb .section} Для проведения платежей и выполнения операций с использованием метода QRIS могут применяться различные интерфейсы платёжной платформы. Так, оплаты могут проводиться через Payment Page, Gate и Dashboard \(с применением платёжных ссылок\). При этом, независимо от используемых интерфейсов, для этого метода характерны следующие ограничения. ||Суммы, [IDR](references/ru/currencies/IDR.md)| |минимум|максимум| |--|---------------------------------------------| |-------|--------| |Оплаты|10 000,00|2 000 000,00| ### Сценарии использования {#section_fgt_sdl_ggb .section} Проведение оплат с использованием метода QRIS осуществляется с отображением платёжной инструкции. Пользовательский сценарий оплаты через Payment Page \(в базовом варианте с выбором пользователем метода и перенаправлением с итоговой страницы платёжной формы к веб-сервису\) выглядит следующим образом. ![](images/pm/pp_scenario/ru_pp_customer_scenario_qris_1.svg "Переход к оплате") ![](images/pm/pp_scenario/ru_pp_customer_scenario_qris_2.svg "Выбор метода") ![](images/pm/pp_scenario/ru_pp_customer_scenario_qris_3.svg "Получение инструкции") ![](images/pm/pp_scenario/ru_pp_customer_scenario_qris_4.svg "Платёж по инструкции") ![](images/pm/pp_scenario/ru_pp_customer_scenario_qris_5.svg "Возвращение к форме") ![](images/pm/pp_scenario/ru_pp_customer_scenario_qris_6.svg "Возвращение к веб-сервису") Общие сценарии проведения оплат можно представить следующим образом. ![](images/pm/ru_qris_interfaces_pp.svg "Оплата через Payment Page") ![](images/pm/ru_qris_interfaces_gate.svg "Оплата через Gate") ## Оплаты через Payment Page {#ru_pm_qris_pp_purchase} ### Общая информация {#section_gtg_vxk_m2b .section} Для проведения оплаты через Payment Pageс использованием метода QRIS со стороны веб-сервиса необходимо отправить запрос, содержащий требуемые параметры и подпись, на рабочий URL Ecommpay и принять оповещение о результате.Полная схема проведения оплаты выглядит следующим образом. ![](images/pm/ru_qris_uml_pp.svg) 1. Пользователь на стороне веб-сервиса инициирует оплату. 2. От веб-сервиса на заданный URL Ecommpay передаётся запрос на проведение оплаты через Payment Page. 3. Запрос на проведение оплаты поступает в платёжную платформу. 4. В платёжной платформе выполняется приём запроса с проверкой наличия обязательных параметров и корректной подписи. 5. Осуществляется подготовка Payment Page согласно параметрам проекта и вызова. 6. Пользователю отображается платёжная форма. 7. Пользователь выбирает для оплаты метод QRIS. 8. В платёжную платформу передаётся запрос на проведение оплаты с использованием метода QRIS. 9. В платёжной платформе обеспечиваются обработка полученного запроса. 10. Данные для отображения платёжной инструкции пользователю передаются к Payment Page. 11. Пользователю отображается платёжная инструкция. 12. Пользователь выполняет необходимые действия для оплаты согласно инструкции. 13. В сервисе провайдера выполняется обработка платежа. 14. От сервиса провайдера к платёжной платформе направляется информация о результате оплаты. 15. От платёжной платформы к веб-сервису направляется оповещение о результате оплаты. 16. От платёжной платформы к Payment Page направляется информация о результате оплаты. 17. Информация о результате оплаты отображается пользователю на Payment Page. Информация о форматах запросов и оповещений, используемых для проведения оплат методом QRIS через Payment Page, приведена далее в этом разделе; общая информация о работе с Payment Page API — в отдельной статье [Организация взаимодействия](ru_pp_interaction_organisation.md#). ### Формат запросов {#section_p5j_fgl_ggb .section} При формировании запросов на открытие платёжной формы с применением метода QRIS необходимо учитывать следующее: 1. Должен использоваться базовый минимум параметров, обязательный для любого платежа: - `project_id` — идентификатор проекта, полученный от Ecommpay при интеграции. - `payment_id` — идентификатор платежа, уникальный в рамках проекта. - `payment_currency` — код валюты платежа в формате ISO-4217 alpha-3. - `payment_amount` — сумма платежа в дробных единицах валюты. При использовании валюты [IDR](references/ru/currencies/IDR.md) в запросе на оплату сумму платежа необходимо округлять до целых чисел. Если в запросе указывается иная валюта, то сумма платежа конвертируется на стороне Ecommpay в эквивалентную сумму в валюте [IDR](references/ru/currencies/IDR.md) и также округляется до целых чисел. Информацию об особенностях округления суммы следует уточнять у специалистов технической поддержки Ecommpay. - `customer_id` — идентификатор пользователя в рамках проекта. 2. Дополнительно может потребоваться указывать имя и фамилию пользователя в параметрах `customer_first_name` и `customer_last_name`. Необходимость использования этих параметров следует уточнять у курирующего менеджера Ecommpay. 3. Для предварительного выбора метода QRIS необходимо указывать код платёжного метода `indonesia-qr` в параметре `force_payment_method`. 4. Дополнительно могут использоваться любые другие параметры из числа доступных для работы с Payment Page \([подробнее](ru_PP_Parameters.md)\). 5. После указания всех целевых параметров необходимо составлять подпись \([подробнее](ru_platform_signature.md#)\). Таким образом, корректный запрос на открытие платёжной формы с применением метода QRIS должен содержать идентификатор проекта, базовые сведения о платеже \(идентификатор, сумму и код валюты\), информацию о пользователе и подпись. ```language-json { "project_id": 120, "payment_id": "580", "payment_amount": 1000000, "payment_currency": "IDR", "customer_id": "customer1", "customer_first_name": "John", "customer_first_name": "Doe", "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg==" } ``` ```language-json { "project_id": 120, "payment_id": "580", "payment_amount": 1000000, "payment_currency": "IDR", "customer_id": "customer1", "customer_first_name": "John", "customer_first_name": "Doe", "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg==" } ``` ### Формат оповещений {#section_dpx_2hl_ggb .section} Для оповещений о результатах оплат с применением метода QRIS используется типовой формат, описание которого представлено в разделе [Работа с оповещениями](ru_platform_callbacks.md#). В следующем примере оповещение свидетельствует о том, что в рамках проекта `1234` была проведена оплата в размере `100 000,00 IDR`. ```language-json { "project_id": 1234, "payment": { "id": "ABC12345", "type": "purchase", "status": "success", "date": "2021-06-03T09:18:49+0000", "method": "indonesia-qr", "sum": { "amount": 10000000, "currency": "IDR" }, "description": "" }, "customer": { "id": "customer1" }, "operation": { "id": 66524010061681, "type": "sale", "status": "success", "date": "2021-06-03T09:18:49+0000", "created_date": "2021-06-03T09:04:56+0000", "request_id": "312be99ad68be48100c724ce274066525", "sum_initial": { "amount": 10000000, "currency": "IDR" }, "sum_converted": { "amount": 10000000, "currency": "IDR" }, "code": "0", "message": "Success", "provider": { "id": 5861, "payment_id": "32376801d1f6b6b6406...a02b4e45c", "auth_code": "", "date": "2021-06-03T09:18:39+0000" } }, "signature": "LaWvR4EPqYRvsuU7Hl0H09l6uYR0trjaJxLAhCBsxA==" } } ``` В следующем примере оповещение свидетельствует об отклонённой оплате. ```language-json { "id": "7890", "type": "purchase", "status": "decline", "date": "2021-06-04T06:19:47+0000", "method": "indonesia-qr", "sum": { "amount": 1000000, "currency": "IDR" }, "description": "" }, "customer": { "id": "1" }, "operation": { "id": 79864010068961, "type": "sale", "status": "decline", "date": "2021-06-04T06:19:47+0000", "created_date": "2021-06-03T06:19:31+0000", "request_id": "1504560d8c125cb12199c320ac41c...079865", "sum_initial": { "amount": 1000000, "currency": "IDR" }, "sum_converted": { "amount": 1000000, "currency": "IDR" }, "code": "20000", "message": "General decline", "provider": { "id": 5861, "payment_id": "3237eceb715dc5ac46eb80edbde6fe2e24d4", "auth_code": "" } }, "signature": "/NAM67hU7V7/tOQHaWOIRg68e8jhN6GIyC5idy9hiQ==" } ``` ### Дополнительные материалы {#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_qris_gate_purchase} ### Общая информация {#section_lsx_3jl_ggb .section} Для проведения оплаты через Gate с использованием метода QRIS со стороны веб-сервиса необходимо: 1. Отправить запрос, содержащий требуемые параметры и подпись, на рабочий URL Ecommpay. 2. Принять промежуточное оповещение от платёжной платформы и отобразить платёжную инструкцию пользователю. 3. Принять итоговое оповещение от платёжной платформы. Полная схема проведения оплаты выглядит следующим образом. ![](images/pm/ru_qris_uml_gate.svg) 1. Пользователь на стороне веб-сервиса инициирует оплату с использованием метода QRIS. 2. От веб-сервиса на заданный URL Ecommpay передаётся запрос на проведение оплаты через Gate. 3. Запрос на проведение оплаты поступает в платёжную платформу Ecommpay. 4. В платёжной платформе выполняется приём запроса с проверкой наличия обязательных параметров и корректной подписи. 5. От платёжной платформы к веб-сервису направляется ответ с информацией о получении запроса и его корректности \([подробнее](ru_gate_interaction_organisation.md#)\). 6. В платёжной платформе выполняются дальнейшая обработка запроса \(с проверкой согласованности параметров\). 7. От платёжной платформы к веб-сервису направляется оповещение с данными для отображения платёжной инструкции пользователю. 8. Пользователю на стороне веб-сервиса отображается платёжная инструкция. 9. Пользователь выполняет необходимые действия для оплаты согласно инструкции. 10. В сервисе провайдера выполняется обработка платежа. 11. От сервиса провайдера к платёжной платформе направляется информация о результате оплаты. 12. От платёжной платформы к веб-сервису направляется оповещение о результате оплаты. 13. На стороне веб-сервиса обеспечивается информирование пользователя о результате оплаты. Информация о форматах запросов и оповещений, используемых для проведения оплат методом QRIS через Gate, приведена далее в этом разделе; общая информация о работе с Gate API — в отдельной статье [Организация взаимодействия](ru_gate_interaction_organisation.md#). ### Формат запросов {#section_osx_3jl_ggb .section} При работе с запросами на оплаты с применением метода QRIS необходимо учитывать следующее: 1. Для инициирования каждой оплаты должен использоваться отдельный POST-запрос к конечной точке `/v2/payment/banks/indonesia-qr/sale`. Эта точка относится к группе [/v2/payment/banks/\{payment\_method\}/sale](https://api-developers.ecommpay.com/api-specification/banks/post-v2-payment-banks-payment-method-sale). 2. В каждом запросе должны использоваться следующие объекты и параметры: - `general` — объект, содержащий основные идентификационные сведения запроса: - `project_id` — идентификатор проекта, полученный от Ecommpay при интеграции. - `payment_id` — идентификатор платежа, уникальный в рамках проекта. - `signature` — подпись запроса, составленная после указания всех целевых параметров \(подробнее — в разделе [Работа с подписью к данным](ru_platform_signature.md#)\). - `payment` — объект, содержащий сведения о платеже: - `amount` — сумма платежа в дробных единицах валюты; При использовании валюты [IDR](references/ru/currencies/IDR.md) в запросе на оплату сумму платежа необходимо округлять до целых чисел. Если в запросе указывается иная валюта, то сумма платежа конвертируется на стороне Ecommpay в эквивалентную сумму в валюте [IDR](references/ru/currencies/IDR.md) и также округляется до целых чисел. Информацию об особенностях округления суммы следует уточнять у специалистов технической поддержки Ecommpay. - `currency` — код валюты платежав формате ISO-4217 alpha-3. - `customer` — объект, содержащий сведения о пользователе: - `id` — идентификатор пользователя, уникальный в рамках проекта. - `ip_address` — IP-адрес пользователя, актуальный для инициируемого платежа. 3. Дополнительно может потребоваться указывать следующие объекты и параметры: - `customer` — объект, содержащий сведения о пользователе: - `first_name` — имя пользователя, - `last_name` — фамилия пользователя; - `return_url` — объект, содержащий URL для перенаправления пользователя в веб-сервис: - `return` — URL для перенаправления пользователя на любом шаге оплаты. Необходимость использования этих параметров следует уточнять у курирующего менеджера Ecommpay. 4. Дополнительно могут использоваться любые другие параметры из числа указанных в спецификации. Таким образом, корректный запрос на оплату с применением метода QRIS должен содержать идентификатор проекта, базовые сведения о платеже \(идентификатор, сумму и код валюты\), информацию о пользователе, URL для перенаправления, а также подпись. ```language-json { "general": { "project_id": 1234567, "payment_id": "12278b5d662764c9506...c5c35", "signature": "GINgwlggTvpF9AnkT8rUUVC7JChDjj40xI5vOA7w==" }, "customer": { "id": "customer1", "ip_address": "192.0.2.0" "first_name": "John", "last_name": "Doe" }, "payment": { "amount": 1000000, "currency": "IDR" }, "return_url": { "return": "https://example.com/return" } } ``` ```language-json { "general": { "project_id": 1234567, "payment_id": "12278b5d662764c9506...c5c35", "signature": "GINgwlggTvpF9AnkT8rUUVC7JChDjj40xI5vOA7w==" }, "customer": { "id": "customer1", "ip_address": "192.0.2.0" "first_name": "John", "last_name": "Doe" }, "payment": { "amount": 1000000, "currency": "IDR" }, "return_url": { "return": "https://example.com/return" } } ``` ### Форматы данных для отображения платёжной инструкции {#section_fq5_ryf_r4b .section} Для отображения платёжной инструкции необходимо принять и обработать оповещение от платёжной платформы, содержащее данные о платеже в массиве `display_data`, и отобразить пользователю платёжную инструкцию. Массив `display_data` содержит следующие параметры: - `type` — тип передаваемых данных \(в значении всегда передаётся `qr_data`\); - `title` — название передаваемых данных, которые необходимо отобразить пользователю \(в значении всегда передаётся `qr_code_data`\); - `data` — строка с закодированным изображением QR-кода. Далее приведён фрагмент оповещения, содержащего данные для отображения пользователю. ```language-json "display_data": [ { "type": "qr_data", "title": "qr_code_data", "data": "00020101021226530012...40014ID.CO.QRIS.WWW0215ID20200311332370303URE5204323753033605405100005502015802ID5911TARGETWIRES6007jakarta61059999962470703A015036323777b2dadc0aa04fdb82a0cc2349be345c63048782" } ] ``` ### Формат итоговых оповещений {#section_wsx_3jl_ggb .section} Для оповещений о результатах оплат с применением метода QRIS используется типовой формат, описание которого представлено в разделе [Работа с оповещениями](ru_platform_callbacks.md#). В следующем примере оповещение свидетельствует о том, что в рамках проекта `1234` была проведена оплата в размере `100 000,00 IDR`. ```language-json { "project_id": 1234, "payment": { "id": "ABC12345", "type": "purchase", "status": "success", "date": "2021-06-03T09:18:49+0000", "method": "indonesia-qr", "sum": { "amount": 10000000, "currency": "IDR" }, "description": "" }, "customer": { "id": "customer1" }, "operation": { "id": 66524010061681, "type": "sale", "status": "success", "date": "2021-06-03T09:18:49+0000", "created_date": "2021-06-03T09:04:56+0000", "request_id": "312be99ad68be48100c724ce274e...066525", "sum_initial": { "amount": 10000000, "currency": "IDR" }, "sum_converted": { "amount": 10000000, "currency": "IDR" }, "code": "0", "message": "Success", "provider": { "id": 5861, "payment_id": "32376801d1f6b6b6406...a02b4e45c", "auth_code": "", "date": "2021-06-03T09:18:39+0000" } }, "signature": "LaWvR4EPqYRvsuU7Hl0H09l6uYR0dCIvFYSK...eiLtrjaJxLAhCBsxA==" } } ``` В следующем примере оповещение свидетельствует об отклонённой оплате. ```language-json { "id": "7890", "type": "purchase", "status": "decline", "date": "2021-06-04T06:19:47+0000", "method": "indonesia-qr", "sum": { "amount": 1000000, "currency": "IDR" }, "description": "" }, "customer": { "id": "1" }, "operation": { "id": 79864010068961, "type": "sale", "status": "decline", "date": "2021-06-04T06:19:47+0000", "created_date": "2021-06-03T06:19:31+0000", "request_id": "1504560d8c125cb12199c320ac41c...079865", "sum_initial": { "amount": 1000000, "currency": "IDR" }, "sum_converted": { "amount": 1000000, "currency": "IDR" }, "code": "20000", "message": "General decline", "provider": { "id": 5861, "payment_id": "3237eceb715dc5ac46eb80edbde6fe2e24d4", "auth_code": "" } }, "signature": "/NAM67hU7V7/tOQHaWOIRg68e8jhN6GIyC5idy9hiQ==" } ``` ### Дополнительные материалы {#section_xsx_3jl_ggb .section} Для организации работы с оплатами через Gate также могут быть полезны следующие материалы: - [Организация взаимодействия](ru_gate_interaction_organisation.md#)— о том, как взаимодействовать с платёжной платформой через Gate. - [Работа с подписью к данным](ru_platform_signature.md#)— о порядке создания и проверки подписи в программных запросах и оповещениях при взаимодействии с платёжной платформой. - [Проведение платежей](ru_platform_payment_model.md)— о типах, схемах проведения и возможных статусах поддерживаемых платежей и операций. - [Разовая оплата в одну стадию](ru_platform_sms_model.md)— о том, как проводить разовые оплаты через Gate. - [Работа с информацией об операциях](ru_platform_payment_info_codes.md)— о служебных кодах, используемых в платёжной платформе для фиксации информации о выполнении операций. ## Анализ результатов проведения платежей {#ru_pm_qris_dash_analysis} Для анализа информации о платежах и операциях, как в отдельности по методу QRIS, так и в совокупности с другими методами, можно использовать: - инструментарийинтерфейса Dashboard, с различными реестрами и аналитическими панелями; - отчёты в формате CSV, выгружаемые\(как разово, так и периодически\) черезраздел **Отчёты** интерфейса Dashboard; - данные в формате JSON, получаемыепо программным запросам черезинтерфейс Data API. С вопросами по анализу информации можно обращаться к разделам документации \([Dashboard](ru_dbl_about.md) и [Использование Data API](ru_dbl_api_protocol.md)\) и специалистам Ecommpay.