> ## Documentation Index
> Fetch the complete documentation index at: https://docs.crypto-cash.world/llms.txt
> Use this file to discover all available pages before exploring further.

# Apple Native Pay

> Native-режим Apple Pay в виджете CryptoCash: условия доступности, fallback, успешный сценарий, ограничения.

# Apple Native Pay — нативный Apple Pay в виджете CryptoCash

## Обзор

Виджет CryptoCash поддерживает два режима Apple Pay:

| Режим | Описание |
| - | - |
| **Native Apple Pay** | Платёжная панель iOS открывается прямо в виджете — без редиректа на Mercuryo. Валидация мерчанта и отправка токена выполняются через бэкенд. |
| **Mercuryo Apple Pay** | Пользователя перенаправляют в виджет Mercuryo, где Apple Pay обрабатывается на стороне Mercuryo. |

Native-сценарий даёт более качественный UX: пользователь не покидает виджет, не видит сторонних страниц и может авторизоваться с Face ID или Touch ID.

## Условия доступности

Native-сценарий включается, только когда одновременно выполнены все три условия:

1. **`isNativeAvailable === true`** — сервер подтвердил, что для этого платежа поддерживается native Apple Pay.
2. **`kycLimitExceeded === false`** — пользователь не превысил лимит KYC.
3. **Браузер поддерживает Apple Pay** — устройство и браузер позволяют показать native-панель оплаты (только поддерживаемые окружения Apple).

## Условия fallback

Виджет автоматически переключается на виджет Mercuryo в следующих случаях:

| Причина | Действие |
| - | - |
| `isNativeAvailable === false` | Редирект в виджет Mercuryo |
| `kycLimitExceeded === true` | Редирект в виджет Mercuryo |
| Браузер не поддерживает native Apple Pay | Редирект в виджет Mercuryo |
| Валидация мерчанта завершилась ошибкой | Редирект в виджет Mercuryo |
| Отправка платежа вернула ошибку | Редирект в виджет Mercuryo |
| Статус ответа `kyc_required` или `turnover_limit_exceeded` | Редирект в виджет Mercuryo |
| Пользователь закрыл панель Apple Pay | Возврат к выбору способа оплаты |

Для пользователя большинство случаев выглядит как бесшовный переход в виджет Mercuryo без технических подробностей.

## Успешный сценарий и обработка ошибок

* При успехе (`pending` или `order_scheduled`) панель Apple Pay закрывается, и пользователь перенаправляется либо на `redirectUrl` мерчанта, либо на локальную success-страницу.
* При статусах `kyc_required` или `turnover_limit_exceeded` происходит fallback в виджет Mercuryo.
* При ошибке валидации мерчанта или любой другой ошибке обработки также выполняется fallback в виджет Mercuryo.
* Если пользователь закрыл панель Apple Pay, он возвращается к выбору способа оплаты — редирект не выполняется.
* После успешной отправки платёжный провайдер продолжает обработку транзакции, и мерчант получит финальный статус через webhook (например, `payment::paid` или `payment::failed`).

## Ограничения

* Native Apple Pay доступен только в поддерживаемых окружениях Apple (Safari на iOS, iPadOS, macOS). В остальных браузерах выполняется fallback в виджет Mercuryo.
* Native-сценарий реализован только для способа оплаты `apple_pay`. Google Pay и другие способы всегда проходят через виджет Mercuryo.
* Требуется корректно настроенный merchant-аккаунт Apple Pay с доменом, верифицированным в Apple Developer.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.