Мобильные SDK YooKassa: iOS и Android — UX, безопасность и офлайн‑сценарии

Мобильные SDK YooKassa: iOS и Android — UX, безопасность и офлайн‑сценарии

Что такое мобильные 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]

Высокоуровневый сценарий:

1. Пользователь выбирает способ оплаты (карта, Apple Pay/Google Pay, кошелек и др.).
2. Приложение вызывает SDK для ввода платежных данных или инициирует native pay.
3. SDK безопасно токенизирует данные (детали карты не попадают на ваш сервер).
4. Приложение отправляет на ваш бэкенд: сумму, описание, customer_id, токен SDK и вспомогательные параметры (идемпотентность, receipt, metadata).
5. Ваш сервер создает платеж через API YooKassa и возвращает результат в приложение.
6. При необходимости происходит аутентификация (3DS). SDK проводит пользователя через challenge‑экраны.
7. 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 интеграцию платежей. Они помогают повысить конверсию, ускорить повторные оплаты и снизить издержки на соответствие безопасности, а офлайн‑подходы с очередями и идемпотентностью делают процесс надежным даже в нестабильных сетях.

Готовы внедрять? Сделайте следующий шаг:

• Получите доступы и включите методы в Подключение YooKassa.
• Настройте ключи в Личный кабинет и изучите API.
• Прогоните сценарии в Песочнице и запуститесь с прод‑конфигурацией.

Если вам нужна консультация по выбору методов, фискализации и отчетам — изучите разделы Платежные методы, Фискализация 54‑ФЗ и Отчеты и реконсиляция. Удачных запусков и высокой конверсии!