Интеграция UnionPay: пошаговое руководство по подключению и настройке

UnionPay – национальная платёжная система Китая, которая сегодня активно расширяется на международный рынок. Подключив её к вашему сайту или мобильному приложению, вы откроете доступ к более чем 1 млрд карт, используемых в Азии, Европе и США. В этой статье мы подробно опишем все этапы интеграции, требования к оборудованию и программному обеспечению, а также полезные советы по тестированию и поддержке;

Что понадобится для подключения

• Банковский аккаунт в финансовом учреждении, поддерживающем UnionPay.
• Терминал или шлюзPayverse, Payoneer, Stripe или любой другой платёжный провайдер, который уже имеет встроенную поддержку UnionPay.
• Тестовые карты UnionPay для отладки:
  • 6210948000000011
  • 6210948000000029
  • 6210948000000052
• Доступ к API платёжного шлюза (REST/JSON или XML).
• SSL‑сертификат на ваш домен (обязательно для передачи платежных данных).

Выбор провайдера

Если вы уже используете сервис Payverse, достаточно включить UnionPay в настройках. Другие популярные платформы (Shopify, WooCommerce, Magento) также предлагают плагины или модули для подключения UnionPay.

Регистрация в системе

Зарегистрируйтесь на портале UnionPay (обычно требуется загрузить документы компании и банковскую выписку).
Получите API‑ключ и секретный ключ для доступа к тестовым и продакшн‑окружениям.
Настройте IP‑whitelisting – разрешите доступ только с ваших серверов.

Пошаговая инструкция по подключению

1. Активация UnionPay в настройках платёжного шлюза
• Откройте панель администратора (например, в Payverse → Settings → Payment Methods).
• Найдите раздел UnionPay и поставьте галочку «Enable».
• Вставьте полученные API‑ключ и секретный ключ.
• Укажите endpoint URL (обычно https://api.unionpay.com/payment).
• Сохраните изменения.
2. Настройка корзины покупок

<button class="unionpay-button">Оплатить UnionPay</button>

• Подключите JavaScript‑библиотеку, предоставленную провайдером (пример: unionpay.js).
• Инициализируйте процесс оплаты, передавая orderId, amount и currency.
3. Тестирование в sandbox‑режиме
• Используйте тестовые карты из пункта 1.1.
• Отправьте запрос на https://api.unionpay.com/mpgs/query с параметром testMode=Y.
• Проверьте ответ: success → карта принята, declined → отказ.
4. Перевод в продакшн
• Удалите параметр testMode или замените его на N.
• Обновите API‑ключ на продакшн‑ключ.
• Включите HTTPS и проверьте сертификат.
• Проведите тестовый платёж реальными деньгами (обычно минимальная сумма 0,01 USD).
5. Подключение к мобильным приложениям
• Для iOS/Android используйте официальную SDK UnionPay (доступна в документации).
• Импортируйте библиотеку и настройте PayUrl на https://unionpay.com/pay.
• Обработайте результат onSuccess и onError в пользовательском интерфейсе.

Особенности работы с UnionPay

Требования к карте

Для онлайн‑платежей подойдут только карты, выпущенные в рамках UnionPay (кредитные, дебетовые или предоплаченные). При оформлении заказа клиенту может потребоваться ввод PIN‑кода (для дебетовых карт) или подпись (для кредитных).

Преимущества

• Низкие комиссии – в некоторых регионах транзакционный сбор ниже, чем у Visa/Mastercard.
• Поддержка QR‑кодов – возможность принимать платежи через мобильное приложение UnionPay QR.
• Прямая интеграция с банковскими системами Азии – удобно для китайских туристов и бизнес‑партнёров.

Безопасность

UnionPay использует 128‑битное SSL‑шифрование и 3‑D Secure (Verified by Visa‑аналог). При первом платеже клиент может быть перенаправлен на страницу UnionPay для ввода данных карты, после чего происходит авторизация.

Часто задаваемые вопросы (FAQ)

1. Можно ли принимать UnionPay без отдельного терминала?
   
   Да. При подключении через платёжный шлюз (Payverse, Stripe и др.) все операции обрабатываются онлайн, без физического терминала.
2. Какие комиссии берёт провайдер?
   
   Комиссия зависит от выбранного тарифного плана. Обычно это 1,5 % + фиксированная плата 0,30 USD за транзакцию.
3. Как обрабатывать возврат средств?
   
   Возврат делается через тот же API‑endpoint, используя transactionId. Для возвратов в течение 24 часов часто не требуется дополнительная авторизация.
4. Поддерживает ли UnionPay международные карточки?
   
   Да, карты, выпущенные в Китае, а также некоторые карты, выпущенные в других странах (например, в России), могут работать, если они имеют логотип UnionPay.
5. Нужна ли локализация страницы оплаты?
   
   Для лучшего пользовательского опыта рекомендуется добавить поддержку китайского и английского языков, а также валюту CNY/USD в зависимости от целевой аудитории.

Подключение UnionPay к вашему онлайн‑магазину – это возможность выйти на огромный рынок, привлечь китайских туристов и повысить средний чек за счёт более низких комиссий. Главное – правильно подготовить техническую инфраструктуру, протестировать работу в sandbox‑режиме и обеспечить надёжную поддержку после перехода в продакшн. Следуя описанным выше шагам, вы сможете быстро и безопасно интегрировать UnionPay в свою платёжную систему.

Если понадобится дополнительная помощь, обратитесь к документации вашего платёжного провайдера или к официальной поддержке UnionPay.

Удачной интеграции!