Интеграции Uniteller: API, Hosted Checkout, SDK и модули

Получить CloudPayments бесплатно

Интеграции Uniteller: API, Hosted Checkout, SDK и модули

Подходы к интеграции

Hosted Checkout (Redirect): быстро, безопасно, минимальные требования к PCI DSS. Идеально для MVP.
Прямое API‑подключение: полная кастомизация UX и логики, больше ответственности за безопасность.
Готовые плагины CMS: минимальная разработка, интеграция «из коробки».
Мобильные SDK: нативная оплата внутри приложений iOS/Android.

Выбор зависит от ресурса разработки, требований к UX, кастомным сценариям (рекурренты, предавторизация, сплит‑платежи).

Архитектура и поток платежа

Базовый сценарий:

Frontend отправляет заказ вашему бэкенду.
Бэкенд создает платеж (API) или получает ссылку Hosted Checkout.
Покупатель платит (3‑D Secure при необходимости).
Провайдер отправляет webhook со статусом (paid/failed/authorized).
Ваш бэкенд валидирует подпись события и обновляет заказ.

Рекомендации:

Используйте idempotency‑ключи для создания платежей и возвратов.
Логируйте корреляционный ID платежа/заказа.

API: создание платежа и подтверждение

В API обычно есть сущности: payment, refund, capture, cancel. В запросе создания платежа передаются сумма, валюта, описание, внешний ID заказа, данные клиента и URL‑ы возврата.

Получить CloudPayments бесплатно

Пример псевдо‑запроса:

POST /payments
Headers: Authorization: Bearer <token>, Idempotency-Key: <uuid>
Body: {
  "amount": 2500,
  "currency": "RUB",
  "orderId": "ORD-100500",
  "description": "Оплата заказа #100500",
  "customer": { "email": "[email protected]" },
  "receipt": { /* данные 54‑ФЗ */ },
  "returnUrl": "https://shop.example/success",
  "failUrl": "https://shop.example/fail"
}

Всегда валидируйте ответ и сохраняйте идентификатор платежа провайдера. Для capture/cancel используйте отдельные вызовы (при предавторизации).

Webhooks: статусы и идемпотентность

Подпишите URL webhooks и проверяйте подпись каждого события (HMAC/секрет).
Обрабатывайте статусы: created, authorized, paid, failed, refunded, partially_refunded.
Разрешайте повторную доставку событий и сравнивайте eventId с журналом, чтобы избежать дубликатов.

Хорошая практика — возвращать 2xx только после успешной фиксации в БД и постановки фоновых задач (чек, e‑mail, отгрузка).

Безопасность: подпись, ключи, IP

Храните секреты в защищенном хранилище (Vault, KMS).
Разделяйте ключи на тест/прод, используйте разные Idempotency Key namespaces.
Ограничьте доступ к админ‑эндпоинтам по IP и включите HTTPS‑TLS 1.2+.
Маскируйте PAN/даты в логах и исключайте чувствительные данные из telemetry.

Подробнее см. «Безопасность: PCI DSS и 3‑D Secure».

Тестовая среда и данные

Используйте тестовые карты/сценарии успеха/отказа/3DS.
Имитируйте возврат, частичный возврат, отмену, таймауты.
Прогоните крайние случаи: повторный webhook, idempotency, сетевые сбои.

Мобильные SDK

SDK упрощают сбор карточных данных и выполнение 3DS внутри приложения. Проверьте:

совместимость с версией iOS/Android;
обработку background/foreground и таймеров 3DS;
UX ретраев и локализацию.

Плагины для CMS

Доступны модули для 1C‑Bitrix, WooCommerce, OpenCart и других платформ. Проверьте:

совместимость версии CMS и PHP/DB;
корректность URL‑ов успеха/ошибки, webhook‑ов;
поддержку СБП и «пэй»‑методов в плагине.

Подробнее — раздел «Модули для CMS».

Чек‑лист перед продом

Все методы оплаты протестированы (карты/СБП/кошельки).
Webhooks подписаны и обрабатываются идемпотентно.
Настроены ретраи и таймауты API.
Фискализация чека выполняется для всех сценариев (оплата/возврат).
Логи и алерты по ошибкам/отказам подключены.
Доступы к ключам ограничены, 2FA включено в ЛК.

Типичные ошибки и их решение

401/403 при вызовах: проверьте токен, clock‑skew, домен/окружение.
Несовпадение сумм в чеке: синхронизируйте источник цен/скидок и НДС.
Потеря статусов: добавьте механизм опроса статуса в случае, если webhook не пришёл.
Дубликаты платежей: используйте Idempotency‑Key на create и refund.

Получить CloudPayments бесплатно