Мобильные SDK YooKassa: iOS и Android — UX, безопасность и офлайн‑сценарии
Table of contents
Что такое мобильные SDK YooKassa и зачем они нужны
Мобильные SDK YooKassa — это наборы инструментов для iOS и Android, которые упрощают SDK‑интеграцию платежей в нативные приложения. С их помощью мобильная оплата YooKassa становится быстрее в разработке и удобнее для пользователей: вы получаете нативные экраны ввода карты, поддержку Apple Pay / Google Pay, мобильный 3DS, сохранение платежных данных и единый платежный поток с вашим сервером.
Если вы только исследуете возможности сервиса, начните с раздела Обзор YooKassa. Готовы к запуску? Смотрите дорожную карту в Подключение YooKassa и документацию по API.
Когда выбирать SDK вместо WebView
Мобильный WebView — быстрый старт, но у него есть ограничения. SDK выигрывает, когда важны конверсия и контроль UX.
Выберите yookassa mobile sdk, если:
- Нужен нативный UX: автоподстановка, маски ввода, биометрия и pay‑кнопки.
- Требуется глубокая интеграция: сохранение карт, one‑tap, повторные списания.
- Важны мобильный 3DS и корректные challenge‑потоки в приложении.
- Хотите меньше PCI‑рисков: карточные данные не проходят через ваш бэкенд.
WebView может подойти, если:
- У вас MVP со статическим платежным сценарием.
- B2B‑сценарии оплачиваются по ссылке из письма/мессенджера.
- Вы используете готовый движок магазина. Посмотрите раздел CMS интеграции.
Архитектура и поток платежа
Ниже — типичный поток оплаты с мобильным SDK и вашим бэкендом.
![Схема потока платежа в мобильном приложении YooKassa]
Высокоуровневый сценарий:
- Пользователь выбирает способ оплаты (карта, Apple Pay/Google Pay, кошелек и др.).
- Приложение вызывает SDK для ввода платежных данных или инициирует native pay.
- SDK безопасно токенизирует данные (детали карты не попадают на ваш сервер).
- Приложение отправляет на ваш бэкенд: сумму, описание, customer_id, токен SDK и вспомогательные параметры (идемпотентность, receipt, metadata).
- Ваш сервер создает платеж через API YooKassa и возвращает результат в приложение.
- При необходимости происходит аутентификация (3DS). SDK проводит пользователя через challenge‑экраны.
- SDK сообщает приложению финальный статус. Вы логируете данные и показываете чек/результат.
Советы по проектированию:
- Используйте идемпотентные ключи на вашем сервере.
- Логи и корелляция: прокидывайте внутренний payment_id в metadata.
- Держите время ожидания со стороны клиента разумным и сообщайте о прогрессе.
UX-паттерны: конверсия и удержание
Сильная сторона SDK — контроль UX. Что важно реализовать:
- Сохранение платежных данных. Предложите пользователю сохранить карту для следующего раза; хранение берет на себя YooKassa (токены/идентификаторы), вы оперируете безопасными id.
- Оплата в один тап. Сохраненная карта + биометрия устройства = мгновенная оплата повторных заказов.
- Apple Pay / Google Pay. Подключите pay‑кнопки для бесшовного чекаута.
- Локализация и доступность. Адаптируйте тексты ошибок, поддерживайте dynamic type и VoiceOver/TalkBack.
- Ретрай с прозрачным UX. При сетевой проблеме предложите повторить попытку или сменить метод.
См. список актуальных способов в разделе Платежные методы.
Безопасность: мобильный 3DS, токенизация, антифрод
Безопасность — приоритет. С мобильными SDK вы получаете:
- Мобильный 3DS (3-D Secure 2). SDK инициирует аутентификацию и проводит challenge внутри приложения, с корректным возвратом статуса и fallback на web‑поток при необходимости.
- Токенизация. Данные карты обрабатываются SDK и передаются напрямую в YooKassa; ваш сервер видит только безопасный токен.
- Снижение PCI‑нагрузки. Минимизируйте область соответствия. Детали подходов и обязанности описаны в разделе Безопасность и соблюдение.
- Антифрод‑сигналы. Передавайте device‑параметры и клиентские атрибуты (как metadata или специальные поля), это помогает системам управления рисками.
Практики:
- Не логируйте PAN/CVV, используйте маски и redaction.
- Обновляйте SDK и следите за релиз‑нотами безопасности.
- Для повторных списаний применяйте безопасные токены и подтверждение по 3DS, если требуется вашей моделью риска.
Офлайн‑сценарии: очередь, ретраи и идемпотентность
Часть пользователей оплачивает с нестабильным интернетом. Как обеспечить устойчивость:
- Очередь операций на клиенте. Сериализуйте «намерение оплатить» (order_id, amount, token) в зашифрованное локальное хранилище и отправляйте на сервер при восстановлении сети.
- Идемпотентность. На вашем сервере используйте idempotence‑key на каждый createPayment, чтобы исключить дубли.
- Экспоненциальный ретрай с джиттером. Уменьшает лавинообразные повторные запросы.
- Отложенная фиксация. Для «холд‑капчер» сценариев создавайте платеж с подтверждением продавцом (capture позже), чтобы финализировать заказ только после успешной синхронизации.
- Корректные статусы UX. Пишите “Ожидаем подтверждения” и отправляйте пуш при смене статуса из бэкенда.
Важно: офлайн‑очередь реализуется на уровне вашего приложения. yookassa mobile sdk предоставляет методы и statemachine для безопасной инициации, но хранение/ретраи — ваша зона контроля.
Поддерживаемые методы оплаты
Мобильные SDK работают с популярными сценариями:
- Банковские карты (дебетовые/кредитные), включая сохранение реквизитов.
- Apple Pay (iOS) и Google Pay (Android), где доступно и подключено.
- Электронные кошельки и другие локальные методы — смотрите актуальное покрытие в Платежные методы.
Если требуется split‑платежи или выплаты исполнителям, изучите раздел Выплаты.
Сравнение SDK по ключевым возможностям
| Возможность |
iOS SDK |
Android SDK |
| Нативные экраны карты |
Да |
Да |
| Мобильный 3DS (встроенный challenge) |
Да (fallback на web) |
Да (fallback на web) |
| Apple Pay / Google Pay |
Apple Pay |
Google Pay |
| Сохранение карты и one‑tap |
Да |
Да |
| Биометрия устройства |
Face ID / Touch ID |
Fingerprint / BiometricPrompt |
| Кастомизация UI |
Темы/стили/локализация |
Темы/стили/локализация |
| Работа при кратковременных обрывах |
Через ваши ретраи |
Через ваши ретраи |
| Минимальные версии ОС |
См. релиз‑ноты SDK |
См. релиз‑ноты SDK |
youkassa iOS SDK: настройка и особенности
Интеграция youkassa ios sdk в три шага:
- Установка. Подключите пакет через Swift Package Manager или CocoaPods. Следите за актуальными версиями и совместимостью в релиз‑нотах.
- Инициализация. Передайте ключи/идентификаторы, полученные в Личный кабинет (для ИП — см. Личный кабинет ИП).
- Поток оплаты. Вызовите экран ввода карты или Apple Pay sheet, получите токен, отправьте его на ваш сервер и создайте платеж по API.
Рекомендации по iOS:
- Обработайте App Extensions/SceneDelegate и background‑события для корректного возврата из 3DS.
- Поддержите Dynamic Type и Dark Mode.
- Для Apple Pay проверьте entitlement и мерчант‑идентификатор, выданный вашим провайдером.
youkassa Android SDK: настройка и особенности
Интеграция youkassa android sdk включает:
- Подключение. Добавьте зависимость Gradle из Maven Central. Проверьте совместимость с minSdk/targetSdk.
- Конфигурация. Инициализируйте SDK, задайте локализацию и тему, настройте Google Pay (если требуется) через соответствующие API и манифест‑пермишены.
- Поток оплаты. Покажите форму оплаты, получите токен, передайте его на бэкенд для создания платежа.
Рекомендации по Android:
- Обработайте Activity Result API для 3DS и Google Pay.
- Включите SafetyNet/Play Integrity сигналы там, где это уместно (как часть антифрода).
- Следите за жизненным циклом (process death, конфигурационные изменения) — храните промежуточные состояния безопасно.
Тестирование и отладка в песочнице
Перед продом:
- Используйте тестовый режим в Песочнице: тестовые ключи, карты и mock‑сценарии 3DS.
- Логируйте по уровням: клиентский flow_id, server payment_id, idempotence‑key.
- Нагрузочные тесты бэкенда на создание/подтверждение платежей.
- Ошибки и ретраи: симулируйте таймауты/обрывы сети, убедитесь, что очередь/ретраи не создают дубли (идемпотентность!).
Для сверки итогов и автоматизации бухгалтерии смотрите Отчеты и реконсиляция.
Фискализация, возвраты и отчеты
- 54‑ФЗ: передавайте фискальные реквизиты (позиции, ставки НДС, признак предмета расчета) с платежом/чеком. Подробности — в Фискализация 54‑ФЗ.
- Возвраты и диспуты: делайте частичные и полные возвраты из вашего бэкенда или кабинета. Подробнее — Возвраты и диспуты.
- Сверка и аналитика: используйте выгрузки и webhooks, а также инструменты из раздела Отчеты и реконсиляция.
Тарифы, SLA и соответствие
Финансовые условия и комиссии описаны в разделе Тарифы и эквайринг. Вопросы информационной безопасности, соответствия требованиям и хранение данных — в Безопасность и соблюдение.
Если вы еще не получили доступы и не настроили мерчант‑профиль, начните с Подключение YooKassa и настройте параметры в Личный кабинет.
Частые вопросы
- Можно ли смешивать SDK и WebView? Да, но рекомендуется единообразный UX. Если используете WebView для редких методов, обеспечьте согласованную навигацию и тексты ошибок.
- Как сделать автосписание за подписку? Сохраняйте платежный метод и инициируйте повторные списания сервером через API; 3DS зависит от требований эмитента и вашего риска.
- Что с офлайн‑оплатой «совсем без интернета»? Карточный платеж требует сети для авторизации. Реализуйте отложенный платеж: сохраняйте заказ и завершайте оплату после восстановления сети.
- Можно ли мигрировать с WebView без даунтайма? Да: включите SDK для части пользователей (feature flag), сравните конверсию, затем проведите полную миграцию.
Итоги и что делать дальше
Мобильные SDK YooKassa для iOS и Android дают нативный UX, встроенную поддержку мобильного 3DS, гибкую кастомизацию и безопасную SDK интеграцию платежей. Они помогают повысить конверсию, ускорить повторные оплаты и снизить издержки на соответствие безопасности, а офлайн‑подходы с очередями и идемпотентностью делают процесс надежным даже в нестабильных сетях.
Готовы внедрять? Сделайте следующий шаг:
Если вам нужна консультация по выбору методов, фискализации и отчетам — изучите разделы Платежные методы, Фискализация 54‑ФЗ и Отчеты и реконсиляция. Удачных запусков и высокой конверсии!