# China UnionPay {#pm_unionpay} **На уровень выше:**[Банковские платежи](ru_pm_bankpayments.md) ## Обзор {#ru_pm_unionpay_overview} статья о работе с платёжным методом China UnionPay, который позволяет проводить платежи в разных валютах с использованием платёжных карт в разных странах и для которого в платформе Ecommpay поддерживаются оплаты и возврат ### Введение {#section_ql3_5fj_stb .section} China UnionPay — метод, позволяющий проводить платежи в разных валютах с использованием платёжных карт в разных странах. Для этого метода в платёжной платформе Ecommpay поддерживаются оплатыи возвраты. В этой статье представлена информация о работе с методом China UnionPay: обзорный раздел с общими сведениями и последующие разделы с информацией о действиях, необходимых со стороны мерчанта для решения разных задач. ### Характеристика {#section_tbf_2zk_ggb .section} |Тип платёжного метода|банковские платежи| |Платёжные инструменты|платёжные карты| |Регионы использования|[AE](references/ru/countries/AE.md), [AG](references/ru/countries/AG.md), [AT](references/ru/countries/AT.md), [AU](references/ru/countries/AU.md), [AZ](references/ru/countries/AZ.md), [BD](references/ru/countries/BD.md), [BE](references/ru/countries/BE.md), [BN](references/ru/countries/BN.md), [BY](references/ru/countries/BY.md), [CA](references/ru/countries/CA.md), [CN](references/ru/countries/CN.md), [DE](references/ru/countries/DE.md), [ES](references/ru/countries/ES.md), [FI](references/ru/countries/FI.md), [FR](references/ru/countries/FR.md), [GB](references/ru/countries/GB.md), [GE](references/ru/countries/GE.md), [HK](references/ru/countries/HK.md), [HU](references/ru/countries/HU.md), [ID](references/ru/countries/ID.md), [IE](references/ru/countries/IE.md), [IT](references/ru/countries/IT.md), [JP](references/ru/countries/JP.md), [KE](references/ru/countries/KE.md), [KG](references/ru/countries/KG.md), [KH](references/ru/countries/KH.md), [KR](references/ru/countries/KR.md), [KZ](references/ru/countries/KZ.md), [LB](references/ru/countries/LB.md), [LI](references/ru/countries/LI.md), [LK](references/ru/countries/LK.md), [LT](references/ru/countries/LT.md), [LU](references/ru/countries/LU.md), [MG](references/ru/countries/MG.md), [MN](references/ru/countries/MN.md), [MO](references/ru/countries/MO.md), [MT](references/ru/countries/MT.md), [MU](references/ru/countries/MU.md), [MX](references/ru/countries/MX.md), [MY](references/ru/countries/MY.md), [NL](references/ru/countries/NL.md), [NP](references/ru/countries/NP.md), [NZ](references/ru/countries/NZ.md), [PA](references/ru/countries/PA.md), [PF](references/ru/countries/PF.md), [PH](references/ru/countries/PH.md), [PT](references/ru/countries/PT.md), [SC](references/ru/countries/SC.md), [SG](references/ru/countries/SG.md), [SI](references/ru/countries/SI.md), [SK](references/ru/countries/SK.md), [SR](references/ru/countries/SR.md), [TH](references/ru/countries/TH.md), [TJ](references/ru/countries/TJ.md), [TZ](references/ru/countries/TZ.md), [US](references/ru/countries/US.md), [VN](references/ru/countries/VN.md) \*| |Валюты платежей|[AUD](references/ru/currencies/AUD.md), [CAD](references/ru/currencies/CAD.md), [CHF](references/ru/currencies/CHF.md), [CNY](references/ru/currencies/CNY.md), [EUR](references/ru/currencies/EUR.md), [GBP](references/ru/currencies/GBP.md), [HKD](references/ru/currencies/HKD.md), [JPY](references/ru/currencies/JPY.md), [NZD](references/ru/currencies/NZD.md), [SGD](references/ru/currencies/SGD.md), [USD](references/ru/currencies/USD.md), [THB](references/ru/currencies/THB.md) \*| |Конвертация валют|–| |Разовые оплаты|+| |Повторяемые оплаты|–| |Полные возвраты|+| |Частичные возвраты|+| |Выплаты|–| |Опротестования|+| |Особенности|при работе с опротестованиями по операциям, которые были выполнены методом China UnionPay, важно учитывать следующие особенности:- порядок работы по таким опротестованиям может отличаться от порядка для классических карточных платежей, описанного в настоящей документации - для таких опротестований не поддерживаются возможности работы через интерфейс Dashboard - при оформлении таких опротестований специалисты Ecommpay сообщают об этом специалистам мерчанта, предоставляют информацию о порядке последующей работы и консультируют по возникающим вопросам - с общими вопросами о порядке работы по таким опротестованиям можно обращаться к курирующему менеджеру Ecommpay | |Организация и стоимость подключения|по согласованию с курирующим менеджером Ecommpay; дополнительную информацию можно получить в [ecommshop](https://ecommpay.com/shop/payment-methods/unionpay-securepay/)| **Прим.:** \* Подробную информацию следует уточнять у курирующего менеджера Ecommpay. ### Схема работы {#section_tsp_gzk_ggb .section} В проведении отдельного платежа с использованием метода China UnionPay задействуются веб-сервис мерчанта, один из интерфейсови платёжная платформа Ecommpay, а также технические средства сервиса China UnionPay. ![](images/pm/ru_chinaunionpay_functional.svg) ### Основные операции {#section_rnx_4cl_ggb .section} Для проведения платежей и выполнения операций с использованием метода China UnionPay могут применяться различные интерфейсы платёжной платформы. Так, оплаты могут проводиться через Payment Page, Gate и Dashboard \(с применением платёжных ссылок\), а возвраты — через Gate и Dashboard. ### Сценарии использования {#section_fgt_sdl_ggb .section} Проведение оплат с использованием метода China UnionPay осуществляется с перенаправлением пользователей к сервису China UnionPay, выполнение возвратов — с заявкой со стороны пользователя и уведомлением со стороны веб-сервиса. ![](images/pm/ru_chinaunionpay_interfaces_pp.svg "Оплата через Payment Page") ![](images/pm/ru_chinaunionpay_interfaces_gate.svg "Оплата через Gate") ![](images/pm/ru_chinaunionpay_interfaces_gate_refund.svg "Возврат через Gate") ## Оплаты через Payment Page {#ru_pm_unionpay_pp_purchase} ### Общая информация {#section_gtg_vxk_m2b .section} Для проведения оплаты через Payment Pageс использованием метода China UnionPay со стороны веб-сервиса необходимо отправить запрос, содержащий требуемые параметры и подпись, на рабочий URL Ecommpay и принять оповещение о результате.Полная схема проведения оплаты выглядит следующим образом. ![](images/pm/ru_chinaunionpay_uml_pp.svg) 1. Пользователь на стороне веб-сервиса инициирует оплату. 2. От веб-сервиса на заданный URL Ecommpay передаётся запрос на проведение оплаты через Payment Page. 3. Запрос на проведение оплаты поступает в платёжную платформу. 4. В платёжной платформе выполняется приём запроса, с проверкой наличия обязательных параметров и корректной подписи. 5. Осуществляется подготовка Payment Page согласно параметрам проекта и вызова. 6. Пользователю отображается платёжная форма. 7. Пользователь выбирает для оплаты метод China UnionPay. 8. В платёжную платформу передаётся запрос на проведение оплаты с использованием метода China UnionPay. 9. В платёжной платформе выполняются обработка полученного запроса и его отправка в сервис China UnionPay. 10. В сервисе China UnionPay выполняется обработка запроса на оплату. 11. От сервиса China UnionPay к платёжной платформе передаются данные для перенаправления пользователя к сервису China UnionPay. 12. Данные для перенаправления пользователя передаются к Payment Page. 13. Пользователь перенаправляется к сервису China UnionPay. 14. Пользователь выполняет необходимые действия для оплаты. 15. В сервисе China UnionPay выполняется обработка платежа. 16. Информация о результате оплаты отображается пользователю в сервисе China UnionPay. 17. Пользователь перенаправляется к Payment Page. 18. От сервиса China UnionPay к платёжной платформе направляется информация о результате оплаты. 19. От платёжной платформы к веб-сервису направляется оповещение о результате оплаты. 20. От платёжной платформы к Payment Page направляется информация о результате оплаты. 21. Информация о результате оплаты отображается пользователю на Payment Page. Информация о форматах запросов и оповещений, используемых для проведения оплат методом China UnionPay через Payment Page, приведена далее в этом разделе; общая информация о работе с Payment Page API — в отдельной статье [Организация взаимодействия](ru_pp_interaction_organisation.md#). ### Формат запросов {#section_p5j_fgl_ggb .section} При формировании запросов на открытие платёжной формы с применением метода China UnionPay необходимо учитывать следующее: 1. Должен использоваться базовый минимум параметров, обязательный для любого платежа: - `project_id` — идентификатор проекта, полученный от Ecommpay при интеграции; - `payment_id` — идентификатор платежа, уникальный в рамках проекта; - `payment_currency` — код валюты платежа в формате ISO-4217 alpha-3; - `payment_amount` — сумма платежа в дробных единицах валюты; - `customer_id` — идентификатор пользователя в рамках проекта. 2. Дополнительно, в зависимости от провайдера, обрабатывающего платёж, может потребоваться указать фамилию пользователя в рамках проекта в параметре `customer_last_name` \(для предотвращения ошибок при проведении платежей рекомендуется указывать не менее 3 и не более 100 символов\). Если какие-либо из этих параметров отсутствуют в запросе, в платёжной форме могут отображаться поля для ввода пользователем недостающих значений \(подробнее — в разделе [Дополнение информации о платежах](ru_pp_clarification.md)\). 3. Валютой платежа может быть одна из следующих валют [AUD](references/ru/currencies/AUD.md), [CAD](references/ru/currencies/CAD.md), [CHF](references/ru/currencies/CHF.md), [CNY](references/ru/currencies/CNY.md), [EUR](references/ru/currencies/EUR.md), [GBP](references/ru/currencies/GBP.md), [HKD](references/ru/currencies/HKD.md), [JPY](references/ru/currencies/JPY.md), [NZD](references/ru/currencies/NZD.md), [SGD](references/ru/currencies/SGD.md), [USD](references/ru/currencies/USD.md), [THB](references/ru/currencies/THB.md). Информацию о доступных валютах следует уточнять у курирующего менеджера Ecommpay. 4. Payment Page можно открывать на китайском языке. Для этого необходимо передавать код языка `zh` в параметре `language_code` \(подробнее — в разделе [Управление языком платёжной формы](ru_PP_WigetLanguages.md)\). 5. Для предварительного выбора метода China UnionPay необходимо указывать код этого метода в параметре `force_payment_method` — `cup-union`. 6. Дополнительно могут использоваться любые другие параметры из числа доступных для работы с Payment Page \([подробнее](ru_PP_Parameters.md)\). 7. После указания всех целевых параметров необходимо составлять подпись \([подробнее](ru_platform_signature.md#)\). Таким образом, корректный запрос на открытие платёжной формы с применением метода China UnionPay должен содержать идентификатор проекта, базовые сведения о платеже \(идентификатор, сумму и код валюты\), идентификатор и фамилию пользователя, а также подпись. ```language-json { "project_id": 120, "payment_id": "580", "payment_amount": 1000, "payment_currency": "USD", "customer_id": "customer1", "customer_last_name": "Johnson", "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg==" } ``` ```language-json { "project_id": 120, "payment_id": "580", "payment_amount": 1000, "payment_currency": "USD", "customer_id": "customer1", "customer_last_name": "Johnson", "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg==" } ``` ### Формат оповещений {#section_dpx_2hl_ggb .section} Для оповещений о результатах оплат с применением метода China UnionPay используется типовой формат, описание которого представлено в разделе [Работа с оповещениями](ru_platform_callbacks.md#). В следующем примере оповещение свидетельствует о том, что в рамках проекта `198` была проведена оплата в размере `10,00 USD`. ```language-json "callbackBody": { "project_id": 198, "payment": { "id": "TEST_154402240162030", "type": "purchase", "status": "success", "date": "2018-12-06T13:33:33+0000", "method": "unionpay", "sum": { "amount": 100, "currency": "USD" }, "description": "TEST_154402240162930" }, "operation": { "id": 7458000002161, "type": "sale", "status": "success", "date": "2018-12-06T13:33:33+0000", "created_date": "2018-12-06T13:31:41+0000", "request_id": "986be38f02e8fe3fb8-c1990f3e7af3", "sum_initial": { "amount": 100, "currency": "USD" }, "sum_converted": { "amount": 100, "currency": "USD" }, "provider": { "id": 410, "payment_id": "74580000021610207055371314024366", "date": "2018-12-06T13:31:42+0000", "auth_code": "" }, "code": "0", "message": "Success" }, "signature": "lci0uOA7aWgJ5nwyImqQjXAfdP+nEzyXwb/t9G1E1U8+5vDkdb...==" } ``` В следующем примере оповещение свидетельствует об отклонённой оплате. ```language-json "callbackBody": { "project_id": 198, "payment": { "id": "TEST_1548340290097231", "type": "purchase", "status": "decline", "date": "2019-01-26T14:36:35+0000", "method": "unionpay", "sum": { "amount": 2000000, "currency": "CNY" }, "description": "TEST_1548340290097" }, "customer": { "id": "1" }, "operation": { "id": 4723000002794, "type": "sale", "status": "decline", "date": "2019-01-26T14:36:35+0000", "created_date": "2019-01-24T14:36:33+0000", "request_id": "72b28ec3f95271699dcade", "sum_initial": { "amount": 2000000, "currency": "CNY" }, "sum_converted": { "amount": 294684, "currency": "USD" }, "provider": { "id": 410, "payment_id": "47230000027940105280386327826886", "date": "2019-01-24T14:36:35+0000", "auth_code": "" }, "code": "20000", "message": "General decline" }, "signature": "vOpSHO5fMolQhUGItTilgFKcVkbdmBMaf2cD7FsIB...==" } ``` ### Дополнительные материалы {#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_unionpay_gate_purchase} ### Общая информация {#section_lsx_3jl_ggb .section} Для проведения оплаты через Gate с использованием метода China UnionPay со стороны веб-сервиса необходимо: 1. Отправить запрос, содержащий требуемые параметры и подпись, на рабочий URL Ecommpay. 2. Принять промежуточное оповещение от платёжной платформы и осуществить перенаправление пользователя к сервису China UnionPay. 3. Принять итоговое оповещение от платёжной платформы. Полная схема проведения оплаты выглядит следующим образом. ![](images/pm/ru_chinaunionpay_uml_gate.svg) 1. Пользователь на стороне веб-сервиса инициирует оплату с использованием метода China UnionPay. 2. От веб-сервиса на заданный URL Ecommpay передаётся запрос на проведение оплаты через Gate. 3. Запрос на проведение оплаты поступает в платёжную платформу Ecommpay. 4. В платёжной платформе выполняется приём запроса с проверкой наличия обязательных параметров и корректной подписи. 5. От платёжной платформы к веб-сервису направляется ответ с информацией о получении запроса и его корректности \([подробнее](ru_gate_interaction_organisation.md#)\). 6. В платёжной платформе выполняются дальнейшая обработка запроса \(с проверкой согласованности параметров\) и его отправка в сервис China UnionPay. 7. В сервисе China UnionPay выполняется обработка запроса на оплату. 8. От сервиса China UnionPay к платёжной платформе передаются данные для перенаправления пользователя к сервису China UnionPay. 9. От платёжной платформы к веб-сервису направляется оповещение с данными для перенаправления пользователя к сервису China UnionPay. 10. Пользователь перенаправляется к сервису China UnionPay. 11. Пользователь выполняет необходимые действия для оплаты. 12. В сервисе China UnionPay выполняется обработка платежа. 13. Пользователю отображается информация о результате оплаты. 14. Пользователь перенаправляется к веб-сервису. 15. От сервиса China UnionPay к платёжной платформе направляется информация о результате оплаты. 16. От платёжной платформы к веб-сервису направляется оповещение о результате оплаты. 17. На стороне веб-сервиса обеспечивается информирование пользователя о результате оплаты. Информация о форматах запросов и оповещений, используемых для проведения оплат методом China UnionPay через Gate, приведена далее в этом разделе; общая информация о работе с Gate API — в отдельной статье [Организация взаимодействия](ru_gate_interaction_organisation.md#). ### Формат запросов {#section_osx_3jl_ggb .section} При формировании запросов на оплату с применением метода China UnionPay необходимо учитывать следующее: 1. Для инициирования каждой оплаты должен использоваться отдельный POST-запрос к конечной точке [/v2/payment/cup/union/sale](https://api-developers.ecommpay.com/api-specification/china-unionpay/post-v2-payment-cup-union-sale). 2. В каждом запросе должны использоваться следующие объекты и параметры: - `general` — объект, содержащий основные идентификационные сведения запроса: - `project_id` — идентификатор проекта, полученный от Ecommpay при интеграции; - `payment_id` — идентификатор платежа, уникальный в рамках проекта; - `signature` — подпись запроса, составленная после указания всех целевых параметров \(подробнее — в разделе [Работа с подписью к данным](ru_platform_signature.md#)\); - `payment` — объект, содержащий сведения о платеже: - `amount` — сумма платежа в дробных единицах валюты; - `currency` — код валюты платежав формате ISO-4217 alpha-3; - `customer` — объект, содержащий сведения о пользователе: - - `id` — идентификатор пользователя, уникальный в рамках проекта; - `ip_address` — IP-адрес пользователя, актуальный для инициируемого платежа; - `last_name*` — фамилия \(для предотвращения ошибок при проведении платежей рекомендуется указывать не менее 3 и не более 100 символов\). Если параметр не указан в запросе, то он дополнительно запрашивается в оповещении о необходимости дополнить данные \(подробнее — в разделе [Дополнение информации о платеже](ru_Gate_Clarification.md)\); - `return_url*` — объект, содержащий URL для перенаправления пользователя в веб-сервис: - `success*` — URL для перенаправления пользователя после проведения оплаты, - `return*` — URL для перенаправления пользователя на любом шаге оплаты. **Прим.:** \*Информацию обязательности этих параметров необходимо уточнять у курирующего менеджера Ecommpay. 3. Валютой платежа может быть одна из следующих валют [AUD](references/ru/currencies/AUD.md), [CAD](references/ru/currencies/CAD.md), [CHF](references/ru/currencies/CHF.md), [CNY](references/ru/currencies/CNY.md), [EUR](references/ru/currencies/EUR.md), [GBP](references/ru/currencies/GBP.md), [HKD](references/ru/currencies/HKD.md), [JPY](references/ru/currencies/JPY.md), [NZD](references/ru/currencies/NZD.md), [SGD](references/ru/currencies/SGD.md), [USD](references/ru/currencies/USD.md), [THB](references/ru/currencies/THB.md). Информацию о доступных валютах следует уточнять у курирующего менеджера Ecommpay. 4. Дополнительно могут использоваться любые другие параметры из числа указанных в спецификации. Таким образом, корректный запрос на оплату с применением метода China UnionPay должен содержать идентификатор проекта, базовые сведения о платеже \(идентификатор, сумму и код валюты\), информацию о пользователе, URL для перенаправления, а также подпись. ```language-json { "general": { "project_id": 198, "payment_id": "TEST_15532590003171111", "signature": "dMNfpKk0MnZhXWKjAKWTckxgEoNbjNhOYQMh6lB4C9J7gksH...==" }, "customer": { "ip_address": "192.0.2.0", "last_name": "Johnson" "id": "123" }, "payment": { "amount": 1000, "currency": "USD" }, "return_url": { "success": "https://example.com/success", "return": "https://example.com/return" } } ``` ```language-json { "general": { "project_id": 198, "payment_id": "TEST_15532590003171111", "signature": "dMNfpKk0MnZhXWKjAKWTckxgEoNbjNhOYQMh6lB4C9J7gksH...==" }, "customer": { "ip_address": "192.0.2.0", "last_name": "Johnson" "id": "123" }, "payment": { "amount": 1000, "currency": "USD" }, "return_url": { "success": "https://example.com/success", "return": "https://example.com/return" } } ``` ### Формат промежуточных оповещений для перенаправления пользователей {#section_x23_cpg_vgb .section} Для перенаправления пользователей от веб-сервиса мерчанта к сервису China UnionPay при проведении каждого платежа с использованием метода China UnionPay необходимо принять промежуточное оповещение от платёжной платформы и использовать информацию из него, включённую в объект `redirect_data`. Формат таких оповещений является типовым \([подробнее](ru_platform_callbacks.md#)\), при этом в состав объекта `redirect_data` включаются следующие объекты и параметры: - `body` — объект с данными для отправки в теле запроса; - `method` — параметр с указанием HTTP-метода отправки запроса\(`GET` или `POST`\); - `url` — параметр со ссылкой для перенаправления. ```language-json "redirect_data": { "body": {}, "method": "GET", "url": "https://www.example.com/pay" } ``` ### Формат итоговых оповещений {#section_dpx_2hl_ggb .section} Для оповещений о результатах оплат с применением метода China UnionPay используется типовой формат, описание которого представлено в разделе [Работа с оповещениями](ru_platform_callbacks.md#). В следующем примере оповещение свидетельствует о том, что в рамках проекта `198` была проведена оплата в размере `10,00 USD`. ```language-json "callbackBody": { "project_id": 198, "payment": { "id": "TEST_154402240162030", "type": "purchase", "status": "success", "date": "2018-12-06T13:33:33+0000", "method": "unionpay", "sum": { "amount": 100, "currency": "USD" }, "description": "TEST_154402240162930" }, "operation": { "id": 7458000002161, "type": "sale", "status": "success", "date": "2018-12-06T13:33:33+0000", "created_date": "2018-12-06T13:31:41+0000", "request_id": "986be38f02e8fe3fb8-c1990f3e7af3", "sum_initial": { "amount": 100, "currency": "USD" }, "sum_converted": { "amount": 100, "currency": "USD" }, "provider": { "id": 410, "payment_id": "74580000021610207055371314024366", "date": "2018-12-06T13:31:42+0000", "auth_code": "" }, "code": "0", "message": "Success" }, "signature": "lci0uOA7aWgJ5nwyImqQjXAfdP+nEzyXwb/t9G1E1U8+5vDkdb...==" } ``` В следующем примере оповещение свидетельствует об отклонённой оплате. ```language-json "callbackBody": { "project_id": 198, "payment": { "id": "TEST_1548340290097231", "type": "purchase", "status": "decline", "date": "2019-01-26T14:36:35+0000", "method": "unionpay", "sum": { "amount": 2000000, "currency": "CNY" }, "description": "TEST_1548340290097" }, "customer": { "id": "1" }, "operation": { "id": 4723000002794, "type": "sale", "status": "decline", "date": "2019-01-26T14:36:35+0000", "created_date": "2019-01-24T14:36:33+0000", "request_id": "72b28ec3f95271699dcade", "sum_initial": { "amount": 2000000, "currency": "CNY" }, "sum_converted": { "amount": 294684, "currency": "USD" }, "provider": { "id": 410, "payment_id": "47230000027940105280386327826886", "date": "2019-01-24T14:36:35+0000", "auth_code": "" }, "code": "20000", "message": "General decline" }, "signature": "vOpSHO5fMolQhUGItTilgFKcVkbdmBMaf2cD7FsIB...==" } ``` ### Дополнительные материалы {#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)— о служебных кодах, используемых в платёжной платформе для фиксации информации о выполнении операций. ## Возвраты через Gate {#ru_pm_unionpay_gate_refund} ### Общая информация {#section_lsx_3jl_ggb .section} Для выполнения возврата через Gate с использованием метода China UnionPay со стороны веб-сервиса необходимо отправить запрос, содержащий требуемые параметры и подпись, на рабочий URL Ecommpay и принять оповещение о результате.В некоторых случаях, по одному платежу вы можете выполнить только один частичный возврат, далее для совершения дополнительных возвратов по этому платежу вам необходимо обратиться в службу технической поддержки платежной системы. Полная схема выполнения возврата выглядит следующим образом. ![](images/pm/ru_chinaunionpay_uml_gate_refund.svg) 1. Пользователь инициирует возврат. 2. От веб-сервиса на заданный URL Ecommpay передаётся запрос на выполнение возврата. 3. Запрос на выполнение возврата поступает в платёжную платформу Ecommpay. 4. В платёжной платформе выполняется приём запроса с проверкой наличия обязательных параметров и корректной подписи. 5. От платёжной платформы к веб-сервису направляется ответ с информацией о получении запроса и его корректности \([подробнее](ru_gate_interaction_organisation.md#)\). 6. В платёжной платформе обеспечиваются дальнейшая обработка запроса \(с проверкой согласованности параметров\) и его отправка в сервис China UnionPay. 7. В сервисе China UnionPay выполняется обработка возврата. 8. От сервиса China UnionPay к платёжной платформе направляется информация о результате возврата. 9. От платёжной платформы к веб-сервису направляется оповещение о результате возврата. 10. На стороне веб-сервиса обеспечивается информирование пользователя о результате возврата. Информация о форматах запросов и оповещений, используемых для выполнения возвратов методом China UnionPay через Gate, приведена далее в этом разделе; общая информация о работе с Gate API — в отдельной статье [Организация взаимодействия](ru_gate_interaction_organisation.md#). ### Формат запросов {#section_osx_3jl_ggb .section} При работе с запросами на возвраты с применением метода China UnionPay необходимо учитывать следующее: 1. Для инициирования каждого возврата должен использоваться отдельный POST-запрос к конечной точке [/v2/payment/unionpay/refund](https://api-developers.ecommpay.com/api-specification/china-unionpay/post-v2-payment-unionpay-refund). 2. В каждом запросе должны использоваться следующие объекты и параметры: - `general` — объект, содержащий основные идентификационные сведения запроса: - `project_id` — идентификатор проекта, полученный от Ecommpay при интеграции; - `payment_id` — идентификатор платежа, для которого необходимо выполнить возврат; - `signature` — подпись запроса, составленная после указания всех целевых параметров \(подробнее — в разделе [Работа с подписью к данным](ru_platform_signature.md#)\); - `payment` — объект, содержащий сведения о возврате: - `description` — комментарий к возврату или его описание; - `amount` — сумма возврата в дробных единицах валюты \(является обязательной при частичном возврате\); - `currency` — код валюты возврата в формате ISO-4217 alpha-3\(является обязательным при частичном возврате\); - `customer` — объект, содержащий сведения о пользователе: - `ip_address` — IP-адрес пользователя, актуальный для инициируемого возврата. 3. Дополнительно могут использоваться любые другие параметры из числа указанных в спецификации. Таким образом, корректный запрос на возврат с применением метода China UnionPay должен содержать идентификаторы проекта и платежа, описание возврата, IP-адрес пользователя, подпись, а также, при необходимости, код валюты и сумму возврата. ```language-json { "general": { "project_id": 210, "payment_id": "test_payment", "signature": "PJkV8ej\/UG0Di8hTng6JvipTv+AWoXW\/9MTO8yJA==" }, "payment": { "description": "test refund", "amount": 1000, "currency": "USD" }, "customer": { "ip_address": "192.0.2.0" } } ``` ```language-json { "general": { "project_id": 210, "payment_id": "test_payment", "signature": "PJkV8ej\/UG0Di8hTng6JvipTv+AWoXW\/9MTO8yJA==" }, "payment": { "description": "test refund", "amount": 1000, "currency": "USD" }, "customer": { "ip_address": "192.0.2.0" } } ``` ### Формат оповещений {#section_wsx_3jl_ggb .section} Для оповещений о результатах возврата с применением метода China UnionPay используется типовой формат, описание которого представлено в разделе [Работа с оповещениями](ru_platform_callbacks.md#). В следующем примере оповещение свидетельствует о том, что в рамках проекта `198` был выполнен возврат в размере `10,00 USD`. ```language-json "callbackBody": { "project_id": 198, "payment": { "id": "TEST_154402240162030", "type": "purchase", "status": "refunded", "date": "2018-12-06T14:24:08+0000", "method": "unionpay", "sum": { "amount": 1000, "currency": "USD" }, "description": "TEST_154402240162930" }, "operation": { "id": 7458000002162, "type": "refund", "status": "success", "date": "2018-12-06T14:24:08+0000", "created_date": "2018-12-06T14:23:58+0000", "request_id": "758cf8a4a495acf7f27eb0c1b", "sum_initial": { "amount": 1000, "currency": "USD" }, "sum_converted": { "amount": 1000, "currency": "USD" }, "provider": { "id": 410, "payment_id": "", "date": "2018-12-06T22:24:04+0000", "auth_code": "" }, "code": "0", "message": "Success" }, "signature": "pHyB8h89qctuJ3ksW9xsERYpVSi3SDWAAWnknJw4o9f...==" } ``` В следующем примере оповещение свидетельствует об отклонённом возврате. ```language-json "callbackBody": { "project_id": 198, "payment": { "id": "TEST_1542789072282111", "type": "purchase", "status": "partially refunded", "date": "2018-11-21T12:33:38+0000", "method": "unionpay", "sum": { "amount": 50, "currency": "USD" }, "description": "TEST_1542789072282" }, "customer": { "id": "1" }, "errors": [ { "code": "2701", "message": "Rules Failed Code", "description": "fatal: RULES_FAILED_CODE" } ], "operation": { "id": 16115000001979, "type": "refund", "status": "decline", "date": "2018-11-21T12:49:38+0000", "created_date": "2018-11-21T12:49:38+0000", "request_id": "3abc68c33b2298127", "sum_initial": { "amount": 50, "currency": "USD" }, "sum_converted": { "amount": 50, "currency": "USD" }, "provider": { "id": 410, "payment_id": "" }, "code": "2701", "message": "Rules Failed Code" }, "signature": "hAS3NXs1LmLl0xYtaHqLrRCAANBq1Z+/g26NVka...==" } ``` ### Дополнительные материалы {#section_xsx_3jl_ggb .section} Для организации работы с возвратами через Gate также могут быть полезны следующие материалы: - [Организация взаимодействия](ru_gate_interaction_organisation.md#)— о том, как взаимодействовать с платёжной платформой через Gate. - [Работа с подписью к данным](ru_platform_signature.md#)— о порядке создания и проверки подписи в программных запросах и оповещениях при взаимодействии с платёжной платформой. - [Проведение платежей](ru_platform_payment_model.md)— о типах, схемах проведения и возможных статусах поддерживаемых платежей и операций. - [Возвраты средств после оплат](ru_Gate_Refund.md)— о том, как выполнять возвраты через Gate. - [Работа с информацией об операциях](ru_platform_payment_info_codes.md)— о служебных кодах, используемых в платёжной платформе для фиксации информации о выполнении операций. ## Анализ результатов проведения платежей {#ru_pm_unionpay_dash_analysis} Для анализа информации о платежах и операциях, как в отдельности по методу China UnionPay, так и в совокупности с другими методами, можно использовать: - инструментарийинтерфейса Dashboard, с различными реестрами и аналитическими панелями; - отчёты в формате CSV, выгружаемые\(как разово, так и периодически\) черезраздел **Отчёты** интерфейса Dashboard; - данные в формате JSON, получаемыепо программным запросам черезинтерфейс Data API. С вопросами по анализу информации можно обращаться к разделам документации \([Dashboard](ru_dbl_about.md) и [Использование Data API](ru_dbl_api_protocol.md)\) и специалистам Ecommpay.