Интеграции Uniteller: API, Hosted Checkout, SDK и модули
Table of contents
Подходы к интеграции
- 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‑ы возврата.
Пример псевдо‑запроса:
POST /payments
Headers: Authorization: Bearer <token>, Idempotency-Key: <uuid>
Body: {
"amount": 2500,
"currency": "RUB",
"orderId": "ORD-100500",
"description": "Оплата заказа #100500",
"customer": { "email": "buyer@example.com" },
"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.