CUP QR
Обзор
Введение
CUP QR — метод, позволяющий проводить платежи в китайских юанях с использованием банковских счетов в Китае. Для этого метода в платёжной платформе ecommpay поддерживаются оплаты.
В этой статье представлена информация о работе с методом CUP QR: обзорный раздел с общими сведениями и последующие разделы с информацией о действиях, необходимых со стороны мерчанта для решения разных задач.
Характеристика
Тип платёжного метода | платежи с помощью QR-кодов |
---|---|
Платёжные инструменты | банковские счета |
Регионы использования | CN |
Валюты платежей | CNY |
Конвертация валют | – |
Разовые оплаты | + |
Повторяемые оплаты | – |
Полные возвраты | – |
Частичные возвраты | – |
Выплаты | – |
Опротестования | – |
Особенности | – |
Организация и стоимость подключения | по согласованию с курирующим менеджером ecommpay |
Схема работы
В проведении отдельного платежа с использованием метода CUP QR задействуются веб-сервис мерчанта, один из интерфейсов и платёжная платформа ecommpay, а также технические средства сервиса CUP QR.
Основные операции
Для проведения платежей и выполнения операций с использованием метода CUP QR могут применяться различные интерфейсы платёжной платформы. Так, оплаты могут проводиться через Payment Page, Gate и Dashboard (с применением платёжных ссылок).
Сценарии использования
Проведение оплат с использованием метода CUP QR осуществляется с отображением QR-кода пользователю.
Рис.: Оплата через Payment Page
Рис.: Оплата через Gate
Оплаты через Payment Page
Общая информация
Для проведения оплаты через Payment Page с использованием метода CUP QR со стороны веб-сервиса необходимо отправить запрос, содержащий требуемые параметры и подпись, на рабочий URL ecommpay и принять оповещение о результате. Полная схема проведения оплаты выглядит следующим образом.
Рис.: Проведение оплаты через Payment Page. Описание шагов
- Пользователь на стороне веб-сервиса инициирует оплату.
- От веб-сервиса на заданный URL ecommpay передаётся запрос на проведение оплаты через Payment Page.
- Запрос на проведение оплаты поступает в платёжную платформу.
- В платёжной платформе выполняется приём запроса, с проверкой наличия обязательных параметров и корректной подписи.
- Осуществляется подготовка Payment Page согласно параметрам проекта и вызова.
- Пользователю отображается платёжная форма.
- Пользователь выбирает для оплаты метод CUP QR.
- Пользователю отображается список доступных банков.
- Пользователь выбирает банк.
- В платёжную платформу передаётся запрос на проведение оплаты с использованием метода CUP QR.
- В платёжной платформе выполняются обработка полученного запроса и его отправка в сервис CUP QR.
- В сервисе CUP QR выполняется обработка запроса на оплату.
- От сервиса CUP QR к платёжной платформе передаются данные для отображения QR-кода пользователю.
- Данные для отображения QR-кода пользователю передаются к Payment Page.
- QR-код отображается пользователю в Payment Page.
- Пользователь сканирует QR-код с помощью мобильного приложения и выполняет необходимые действия для оплаты.
- В сервисе CUP QR выполняется обработка платежа.
- От сервиса CUP QR пользователю направляется письмо по электронной почте с результатом оплаты.
- От сервиса CUP QR к платёжной платформе направляется информация о результате оплаты.
- От платёжной платформы к веб-сервису направляется оповещение о результате оплаты.
- От платёжной платформы к Payment Page направляется информация о результате оплаты.
- Информация о результате оплаты отображается пользователю на Payment Page.
Информация о форматах запросов и оповещений, используемых для проведения оплат методом CUP QR через Payment Page, приведена далее в этом разделе; общая информация о работе с Payment Page API — в отдельной статье Организация взаимодействия.
Формат запросов
При формировании запросов на открытие платёжной формы с применением метода CUP QR необходимо учитывать следующее:
- Должен использоваться базовый минимум параметров, обязательный для любого платежа:
project_id
— идентификатор проекта, полученный от ecommpay при интеграции;payment_id
— идентификатор платежа, уникальный в рамках проекта;payment_currency
— код валюты платежа в формате ISO-4217 alpha-3;payment_amount
— сумма платежа в дробных единицах валюты;customer_id
— идентификатор пользователя в рамках проекта.
- Должен использоваться базовый минимум параметров:
project_id
,payment_id
,payment_currency
,payment_amount
,customer_id
. - Дополнительно рекомендуется указывать следующие параметры:
customer_first_name
— имя пользователя на китайском языке;customer_last_name
— фамилия пользователя на китайском языке;customer_email
— адрес электронной почты пользователя;customer_phone
— номер телефона пользователя;customer_country
— код страны пользователя в формате ISO 3166-1 alpha-2;customer_city
— город проживания пользователя;customer_street
— адрес проживания пользователя;customer_zip
— почтовый индекс пользователя;payment_description
— описание платежа.
Если какие-либо из этих параметров отсутствуют в запросе, в платёжной форме могут отображаться поля для ввода пользователем недостающих значений (подробнее — в разделе Дополнение информации о платежах).
- Валютой платежа может быть только CNY.
- Для предварительного выбора метода CUP QR необходимо указывать код платёжного метода
cup-qr
в параметреforce_payment_method
. - Дополнительно могут использоваться любые другие параметры из числа доступных для работы с Payment Page (подробнее).
- После указания всех целевых параметров необходимо составлять подпись (подробнее).
Таким образом, корректный запрос на открытие платёжной формы с применением метода CUP QR должен содержать идентификатор проекта, базовые сведения о платеже (идентификатор, сумму и код валюты), информацию о пользователе, описание платежа и подпись.
{ "project_id": 120, "payment_id": "580", "payment_amount": 100000, "payment_currency": "CNY", "customer_id": "customer1", "customer_id": "customer121", "customer_first_name": "伍", "customer_last_name": "伍", "customer_email": "paul@example.com", "customer_country": "CH, "customer_city": "倩", "customer_street": "倩", "customer_phone": "13632264147", "customer_zip": "123456", "payment_description: "payment_876543", "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg==" }
Рис.: Пример достаточного набора данных для запроса на оплату
{ "project_id": 120, "payment_id": "580", "payment_amount": 100000, "payment_currency": "CNY", "customer_id": "customer1", "customer_id": "customer121", "customer_first_name": "伍", "customer_last_name": "伍", "customer_email": "paul@example.com", "customer_country": "CH, "customer_city": "倩", "customer_street": "倩", "customer_phone": "13632264147", "customer_zip": "123456", "payment_description: "payment_876543", "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg==" }
Формат оповещений
Для оповещений о результатах оплат с применением метода CUP QR используется типовой формат, описание которого представлено в разделе Оповещения.
В следующем примере оповещение свидетельствует о том, что в рамках проекта 843
была проведена оплата в размере 300,00 CNY
.
Рис.: Пример данных из оповещения о проведении оплаты
"project_id": 843, "payment": { "id": "EP761d-6f6d", "type": "purchase", "status": "success", "date": "2019-12-11T12:20:17+0000", "method": "cup-qr", "sum": { "amount": 30000, "currency": "CNY" }, "description": "123" }, "account": { "number": "qwerty@qwe.fff" }, "customer": { "phone": "2233" }, "operation": { "id": 2000000029, "type": "sale", "status": "success", "date": "2019-12-11T12:20:17+0000", "created_date": "2019-12-11T12:18:04+0000", "request_id": "9a593318e4842a725b60498b-00000003", "sum_initial": { "amount": 30000, "currency": "CNY" }, "sum_converted": { "amount": 30000, "currency": "CNY" }, "code": "0", "message": "Success", "provider": { "id": 1838, "payment_id": "1001905226143910", "auth_code": "", "date": "2019-12-11T12:18:14+0000" } }, "signature": "y/DQVScN32bQi2BHO4YU1gfuiki==" }
В следующем примере оповещение свидетельствует об отклонённой оплате.
Рис.: Пример данных из оповещения об отклонении оплаты
"project_id": 843, "payment": { "id": "EP761d-6f6d", "type": "purchase", "status": "decline", "date": "2019-12-11T12:20:17+0000", "method": "cup-qr", "sum": { "amount": 30000, "currency": "CNY" }, "description": "123" }, "account": { "number": "qwerty@qwe.fff" }, "customer": { "phone": "2233" }, "operation": { "id": 2000000029, "type": "sale", "status": "decline", "date": "2019-12-11T12:20:17+0000", "created_date": "2019-12-11T12:18:04+0000", "request_id": "9a593318e4842a725b60498b-00000003", "sum_initial": { "amount": 30000, "currency": "CNY" }, "sum_converted": { "amount": 30000, "currency": "CNY" }, "code": "20602", "message": "Time-out", "provider": { "id": 1838, "payment_id": "1001905226143910", "auth_code": "", "date": "2019-12-11T12:18:14+0000" } }, "signature": "y/DQVScN32bQi2BHO4YU1gfuikig.==" }
Дополнительные материалы
Для организации работы с оплатами через Payment Page также могут быть полезны следующие материалы:
- Организация взаимодействия — о том, как организовать взаимодействие веб-сервиса с платёжной платформой через Payment Page.
- Работа с подписью к данным — о порядке создания и проверки подписи в программных запросах и оповещениях при взаимодействии с платёжной платформой.
- Модель проведения платежей — о типах, схемах проведения и возможных статусах поддерживаемых платежей и операций.
- Разовая оплата в одну стадию — о том, как проводить разовые оплаты через Payment Page.
- Информация о выполнении операций — о служебных кодах, которые используются в платёжной платформе, чтобы фиксировать информацию о выполнении операций.
Оплаты через Gate
Общая информация
Для проведения оплаты через Gate с использованием метода CUP QR со стороны веб-сервиса необходимо:
- Отправить запрос, содержащий требуемые параметры и подпись, на рабочий URL ecommpay.
- Принять промежуточное оповещение от платёжной платформы и отобразить QR-код пользователю.
- Принять итоговое оповещение от платёжной платформы.
Полная схема проведения оплаты выглядит следующим образом.
Рис.: Проведение оплаты через Gate. Описание шагов
- Пользователь на стороне веб-сервиса инициирует оплату с использованием метода CUP QR.
- От веб-сервиса на заданный URL ecommpay передаётся запрос на проведение оплаты через Gate.
- Запрос на проведение оплаты поступает в платёжную платформу ecommpay.
- В платёжной платформе выполняется приём запроса с проверкой наличия обязательных параметров и корректной подписи.
- От платёжной платформы к веб-сервису направляется ответ с информацией о получении запроса и его корректности (подробнее).
- В платёжной платформе выполняются дальнейшая обработка запроса (с проверкой согласованности параметров) и его оправка в сервис CUP QR.
- В сервисе CUP QR выполняется обработка запроса на оплату.
- От сервиса CUP QR к платёжной платформе передаются данные для перенаправления пользователя к сервису CUP QR.
- От платёжной платформы к веб-сервису направляется оповещение с данными для отображения QR-кода пользователю.
- QR-код отображается пользователю на стороне веб-сервиса.
- Пользователь сканирует QR-код с помощью мобильного приложения и выполняет необходимые действия для оплаты.
- В сервисе CUP QR выполняется обработка платежа.
- От сервиса CUP QR пользователю направляется письмо по электронной почте с результатом оплаты.
- От сервиса CUP QR к платёжной платформе направляется информация о результате оплаты.
- От платёжной платформы к веб-сервису направляется оповещение о результате оплаты.
- На стороне веб-сервиса обеспечивается информирование пользователя о результате оплаты.
Информация о форматах запросов и оповещений, используемых для проведения оплат методом CUP QR через Gate, приведена далее в этом разделе; общая информация о работе с Gate API — в отдельной статье Организация взаимодействия.
Формат запросов
При работе с запросами на оплаты с применением метода CUP QR необходимо учитывать следующее:
- Для инициирования каждой оплаты должен использоваться отдельный POST-запрос к конечной точке /v2/payment/cup/qr/sale.
- В каждом запросе должны использоваться следующие объекты и параметры:
general
— объект, содержащий основные идентификационные сведения запроса:project_id
— идентификатор проекта, полученный от ecommpay при интеграции;,payment_id
— идентификатор платежа, уникальный в рамках проекта;,signature
— подпись запроса, составленная после указания всех целевых параметров (подробнее — в разделе Работа с подписью к данным); (подробнее),
payment
— объект, содержащий сведения о платеже:amount
— сумма платежа в дробных единицах валюты;,currency
— код валюты платежа в формате ISO-4217 alpha-3;,description
— описание или комментарий к платежу;,
customer
— объект, содержащий сведения о пользователе:id
— идентификатор пользователя, уникальный в рамках проекта;,ip_address
— IP-адрес пользователя, актуальный для инициируемого платежа;,first_name
— имя пользователя, только на китайском языке;,last_name
— фамилия пользователя, только на китайском языке;,phone
— номер телефона пользователя без знака "+";,email
— адрес электронной почты пользователя;,zip
— почтовый индекс пользователя;,country
— код страны пользователя в формате ISO 3166-1 alpha-2;,city
— город пользователя на китайском;,street
— адрес пользователя на китайском;,
return_url
— объект, содержащий URL для возврата пользователя с сайта банка в проект мерчанта после совершения оплаты:success
— URL возврата в случае проведённого платежа.
- Валютой платежа может быть только CNY.
- Дополнительно могут использоваться любые другие параметры из числа указанных в спецификации.
Таким образом, корректный запрос на оплату с применением метода CUP QR должен содержать идентификатор проекта, базовые сведения о платеже (идентификатор, сумму и код валюты), информацию о пользователе, описание платежа или комментарий к нему, а также подпись.
{ "general": { "project_id": 200, "payment_id": "ECT_TEST_1559134591371-pz-3", "signature": "pK1YN6fd7yajGSWAzsbYeJo5nvotVBtOijOzgFvAU5Cc8PB...==" }, "customer": { "ip_address": "192.0.2.0", "first_name": "伍", "last_name": "倩文", "phone": "13632264147", "email": "2524243674@email.com", "street":"street", "city": "city", "zip": "123045607", "country": "CH", "id": "123" }, "payment": { "amount": 1000, "currency": "CNY", "description": "payment" }, "return_url: { "success": "http://example.com" } }
Рис.: Пример достаточного набора данных для запроса на оплату
{ "general": { "project_id": 200, "payment_id": "ECT_TEST_1559134591371-pz-3", "signature": "pK1YN6fd7yajGSWAzsbYeJo5nvotVBtOijOzgFvAU5Cc8PB...==" }, "customer": { "ip_address": "192.0.2.0", "first_name": "伍", "last_name": "倩文", "phone": "13632264147", "email": "2524243674@email.com", "street":"street", "city": "city", "zip": "123045607", "country": "CH", "id": "123" }, "payment": { "amount": 1000, "currency": "CNY", "description": "payment" }, "return_url: { "success": "http://example.com" } }
Формат данных для передачи пользователю
Для завершения оплаты необходимо отобразить пользователю QR-код. Информация для отображения QR-кода содержится в оповещении от платёжной платформы в объекте display_data
. Поэтому прежде чем отобразить QR-код, надо принять и обработать такое оповещение.
Данное оповещение отправляется от платёжной платформы ecommpay на URL, указанный в настройках проекта мерчанта. Статус платежа в данном случае будет awaiting customer action
до момента завершения оплаты со стороны пользователя.
Далее приведён фрагмент оповещения, содержащего данные QR-кода для оплаты.
"display_data": [ { "type": "qr_data", "title": "QR Code", "data": "https://cashier.xhepay.com/paygate/union/pay/MDAyMDUxNjk0OTMwNjYyMTQzMTgwOHwwNHw0ODgxMDAwMA==" }, { "type": "add_info", "title": "QR Code Timeout", "data": "600" } ]
Формат итоговых оповещений
Для оповещений о результатах оплат с применением метода CUP QR используется типовой формат, описание которого представлено в разделе Оповещения.
В следующем примере оповещение свидетельствует о том, что в рамках проекта 843
была проведена оплата в размере 300,00 CNY
.
Рис.: Пример данных из оповещения о проведении оплаты
"project_id": 843, "payment": { "id": "EP761d-6f6d", "type": "purchase", "status": "success", "date": "2019-12-11T12:20:17+0000", "method": "cup-qr", "sum": { "amount": 30000, "currency": "CNY" }, "description": "123" }, "account": { "number": "qwerty@qwe.fff" }, "customer": { "phone": "2233" }, "operation": { "id": 2000000029, "type": "sale", "status": "success", "date": "2019-12-11T12:20:17+0000", "created_date": "2019-12-11T12:18:04+0000", "request_id": "9a593318e4842a725b60498b-00000003", "sum_initial": { "amount": 30000, "currency": "CNY" }, "sum_converted": { "amount": 30000, "currency": "CNY" }, "code": "0", "message": "Success", "provider": { "id": 1838, "payment_id": "1001905226143910", "auth_code": "", "date": "2019-12-11T12:18:14+0000" } }, "signature": "y/DQVScN32bQi2BHO4YU1gfuikigFEbA...==" }
В следующем примере оповещение свидетельствует об отклонённой оплате.
Рис.: Пример данных из оповещения об отклонении оплаты
"project_id": 843, "payment": { "id": "EP761d-6f6d", "type": "purchase", "status": "decline", "date": "2019-12-11T12:20:17+0000", "method": "cup-qr", "sum": { "amount": 30000, "currency": "CNY" }, "description": "123" }, "account": { "number": "qwerty@qwe.fff" }, "customer": { "phone": "2233" }, "operation": { "id": 2000000029, "type": "sale", "status": "decline", "date": "2019-12-11T12:20:17+0000", "created_date": "2019-12-11T12:18:04+0000", "request_id": "9a593318e4842a725b60498b-00000003", "sum_initial": { "amount": 30000, "currency": "CNY" }, "sum_converted": { "amount": 30000, "currency": "CNY" }, "code": "20602", "message": "Time-out", "provider": { "id": 1838, "payment_id": "1001905226143910", "auth_code": "", "date": "2019-12-11T12:18:14+0000" } }, "signature": "y/DQVScN32bQi2BHO4YU1gfuikigFEbA...==" }
Дополнительные материалы
Для организации работы с оплатами через Gate также могут быть полезны следующие материалы:
- Организация взаимодействия — о том, как взаимодействовать с платёжной платформой через Gate.
- Работа с подписью к данным — о порядке создания и проверки подписи в программных запросах и оповещениях при взаимодействии с платёжной платформой.
- Модель проведения платежей — о типах, схемах проведения и возможных статусах поддерживаемых платежей и операций.
- Разовая оплата в одну стадию — о том, как проводить разовые оплаты через Gate.
- Информация об операциях — о служебных кодах, используемых в платёжной платформе для фиксации информации о выполнении операций.
Анализ результатов проведения платежей
Для анализа информации о платежах и операциях, как в отдельности по методу CUP QR, так и в совокупности с другими методами, можно использовать:
- инструментарий интерфейса Dashboard, с различными реестрами и аналитическими панелями;,
- отчёты в формате CSV, выгружаемые (как разово, так и периодически) через раздел Отчёты интерфейса Dashboard;,
- данные в формате JSON, получаемые по программным запросам через интерфейс Data API.
С вопросами по анализу информации можно обращаться к разделам документации (Dashboard и Использование Data API) и специалистам ecommpay.