--- title: Stripe description: Подключение Stripe к NexCMP для приема карт, Apple Pay, Google Pay, Link и Alipay: ключи API, вебхук, регистрация домена и тестовый платеж. url: https://nexcmp.com/ru/docs/billing/stripe/ applies_to: NexCMP 1.6.1 updated: 2026-11-02 --- # Stripe > **Где найти в панели:** Finance › Payment channels › Stripe (`/payments/stripe`). Переключатели и комиссии: Finance › Payment channels › Fees & limits (`/payments/fees`). ## Назначение {#what-it-does} Stripe принимает платежи с карт для пополнения баланса. С тем же аккаунтом вы можете подключить **Apple Pay**, **Google Pay**, **Link** и **Alipay**, а также позволить клиентам **сохранять карту** для [автоматического пополнения](https://nexcmp.com/ru/docs/billing/auto-top-up/). Используйте его как основной канал для международных клиентов. ## Требования {#requirements} | Параметр | Требование | |---|---| | Аккаунт Stripe | Аккаунт Stripe с возможностью принимать платежи в **USD**. Платежи через Alipay списываются в JPY и должны быть активированы со стороны Stripe для вашего аккаунта. | | Ключи | Секретный ключ (`sk_live_...` или `sk_test_...`) и публичный ключ (`pk_live_...` или `pk_test_...`). Форма принимает только ключи с этими префиксами. | | Сеть | Панель управления должна быть доступна по HTTPS из интернета (для входящих webhook от Stripe) и иметь исходящий доступ к `api.stripe.com` по порту 443. | | Домен (только для кошельков) | Клиентский домен должен отдавать `/.well-known/apple-developer-merchantid-domain-association` — NexCMP настраивает это автоматически. | | Зависимости | Нет. | ::: info Использование одного аккаунта Stripe NexCMP обрабатывает события webhook только для платежей, созданных им самим, поэтому вы можете использовать аккаунт Stripe параллельно с другими приложениями. ::: ## Подготовка инфраструктуры {#prepare-the-infrastructure} На стороне Stripe: 1. Войдите в [Stripe Dashboard](https://dashboard.stripe.com). Включите или отключите **Test mode** в зависимости от того, проводите ли вы тестирование или запускаете приём платежей. Ключи одного режима не подходят для другого. 2. Перейдите в **Developers › API keys**. Скопируйте **Publishable key**, затем откройте и скопируйте **Secret key**. Храните секретный ключ в безопасности. 3. (Необязательно) Перейдите в **Settings › Payment methods** и активируйте **Alipay**, если хотите принимать этот способ оплаты. 4. Создавать webhook вручную **не требуется** — NexCMP сделает это автоматически (см. шаг 5 ниже). Если вы предпочитаете ручную настройку, создайте endpoint в **Developers › Webhooks** с URL и событиями, указанными в разделе [Webhook](#webhook). ## Подключение в NexCMP {#connect-in-nexcmp} 1. Откройте **Finance › Payment channels › Stripe** (`/payments/stripe`). 2. В блоке **API keys** выберите **Mode** (`live` или `test`), вставьте **Secret key** и **Publishable key**. 3. Нажмите **Save**. Ключи сохраняются в конфигурационном файле на сервере, доступном только сервисной учётной записи NexCMP. Они никогда не передаются обратно в браузер; в дальнейшем на странице отображаются только последние 4 символа. 4. Нажмите **Check**. В диалоговом окне отобразятся статус подключения, режим, доступный и ожидающий баланс, ID аккаунта, доступность списаний, наличие webhook и поддержка Alipay. Красная строка означает, что соответствующий пункт требует внимания. 5. В блоке **Webhook** нажмите **Create webhook** и подтвердите действие. NexCMP запросит у Stripe создание endpoint со всеми необходимыми событиями и автоматически подставит **Webhook signing secret** (`whsec_...`). Предзаполненный в поле URL имеет формат `https:///v1/billing/stripe/webhook`, например `https://cloud.example.com/v1/billing/stripe/webhook`. 6. Откройте **Fees & limits** (`/payments/fees`), оставьте включённым **Card (Stripe)**, укажите ваши фактические тарифы в полях **Stripe fee %** и **Stripe fixed fee (cents)**, после чего нажмите **Save channels & fees**. См. [Payment channels](https://nexcmp.com/ru/docs/billing/payment-channels/#switches-and-fees-fees-limits). ![Страница Stripe с заполненными тестовыми значениями режима, секретного и публичного ключей](https://nexcmp.com/ru/docs/images/billing/stripe-01-keys.webp) ### Webhook {#webhook} Красный баннер «Missing webhook_secret» отображается до тех пор, пока не сохранён секрет подписи. Без него пополнения через Stripe **не зачисляются**, даже если средства были успешно списаны со стороны Stripe. | Параметр | Значение | |---|---| | URL | `https:///v1/billing/stripe/webhook` | | События | `checkout.session.completed`, `payment_intent.succeeded`, `payment_intent.payment_failed`, `charge.refunded`, `charge.dispute.created`, `charge.dispute.closed`, `radar.early_fraud_warning.created`, `refund.updated`, `refund.failed` | | Подпись | Заголовок Stripe `Stripe-Signature`, HMAC-SHA256, допустимое отклонение времени — 300 секунд. Запросы с некорректной подписью получают HTTP 400. | | Идемпотентность | Каждый ID события сохраняется один раз; повторная доставка никогда не приводит к повторному зачислению средств. | Если вы выполнили обновление с версии, регистрировавшей меньшее число событий, нажмите **Create webhook** повторно — старый endpoint сохранится, поэтому после этого удалите его вручную в Stripe Dashboard. Строки **24h events** и **Latest event** в карточке Webhook показывают, доходят ли запросы Stripe до панели. Отдельные события перечислены в **Payment channels › Gateway events** (`/payments/events`, вкладка Stripe), где каждое событие можно просмотреть (**Payload**) или повторить (**Replay**). ### Apple Pay, Google Pay и Link {#apple-pay-google-pay-and-link} 1. В карточке **Wallets (Apple Pay · Google Pay · Link) & Alipay** поле **Customer app Domain registered with Stripe** предварительно заполнено хостом вашего сайта (например, `cloud.example.com`). 2. Нажмите **Register / verify domain** и подтвердите действие. NexCMP зарегистрирует домен в Payment method domains в Stripe и запросит у Stripe его проверку. 3. Результат покажет статус для **Apple Pay**, **Google Pay** и **Link**. Apple Pay отображается только тогда, когда статус равен `active`. 4. В **Fees & limits** оставьте опцию **Apple Pay · Google Pay · Link** включенной. ![Карточка Wallet с зарегистрированным доменом и статусами Apple Pay, Google Pay и Link](https://nexcmp.com/ru/docs/images/billing/stripe-03-wallets.webp) ::: tip Apple Pay остается неактивным Для работы Apple Pay необходимо, чтобы файл подтверждения домена возвращал HTTP 200 на вашем публичном домене. Если перед панелью используется Cloudflare или другой прокси, не блокируйте `/.well-known/`. ::: ### Alipay {#alipay} Alipay подключается по желанию. Включите его в **Stripe Dashboard › Settings › Payment methods**, нажмите **Check** и дождитесь подтверждения доступности Alipay, затем включите **Alipay (Stripe, JPY display)** в **Fees & limits**. Задайте **Alipay fee %**, **Alipay fixed fee**, курс **¥/USD rate** (50–500) и спред **FX spread %** (0–20). Регулярно обновляйте курс ¥/USD: если он старше 7 дней, на странице появится предупреждение. ## Проверка {#verify} 1. В тестовом режиме войдите в портал под тестовым клиентом, откройте **Billing**, нажмите **Deposit**, выберите **Card** и внесите минимальную сумму с помощью тестовой карты Stripe `4242 4242 4242 4242` (любая дата в будущем, любой CVC). 2. Баланс пополнится в течение нескольких секунд, а платеж появится в **Finance › Billing › Top-ups** со статусом *Completed*. 3. Откройте **Payment channels › Gateway events › Stripe**: там должны отображаться `checkout.session.completed` или `payment_intent.succeeded` со временем обработки. 4. При возврате на страницу Stripe значение **24h events** должно быть больше 0. Перед запуском в продакшн переключите **Mode** на `live`, вставьте боевые ключи и снова нажмите **Create webhook** (вебхуки для тестового и боевого режимов настраиваются раздельно). ## Ограничения и примечания {#limits-notes} - **Суммы и валюта.** Кошельки ведутся в USD. Платежи картой, через кошельки и Link списываются в USD; Alipay отображается клиенту в JPY и конвертируется по вашему курсу. - **Комиссии.** Реальная комиссия Stripe не считывается автоматически; размер комиссии, который видит клиент и который зачисляется на кошелек, определяется заданным вами процентом. Выберите **Customer pays top-up fee** в *Fees & limits*, чтобы взимать комиссию сверх суммы пополнения. - **Сохраненные карты.** Если клиент отмечает *Save card for auto top-up*, данные карты сохраняются на стороне Stripe, а не на вашем сервере. См. [Saved payment methods](https://nexcmp.com/ru/docs/billing/saved-payment-methods/). - **Возвраты.** Возврат средств на карту выполняется в два этапа: администратор создает запрос на возврат для завершенного платежа (**Finance › Billing › Top-ups**, действие возврата для платежа), а затем подтверждает его в **Finance › Payouts › Card refunds** (`/billing/payouts`). Возвраты Alipay асинхронны; при неудачном возврате (`refund.failed`) удержанная сумма возвращается на кошелек. - **Споры (Disputes).** При `charge.dispute.created` NexCMP блокирует аккаунт клиента, приостанавливает его предоплаченные услуги (данные не удаляются) и отправляет оповещение администратору. В случае выигрыша спора (`charge.dispute.closed`) сумма возвращается на кошелек. - **Ожидающие платежи.** Если вебхук не поступил, NexCMP самостоятельно сверяет со Stripe платежи, остающиеся в статусе pending более 10 минут, и завершает их. Платежи старше 7 дней игнорируются. - **Resellers** могут подключить собственный аккаунт Stripe (вебхук `https:///v1/billing/stripe/webhook/r/`); см. [Resellers](https://nexcmp.com/ru/docs/customers/resellers/). ## Устранение неполадок {#troubleshooting} | Симптом | Причина | Решение | |---|---|---| | "Секретный ключ должен начинаться с sk_live_/sk_test_" | Вставлен неверный ключ | Вставьте секретный ключ из **Developers › API keys**. | | «Секретный ключ не соответствует режиму live/test» | Несоответствие режима и ключа | Приведите **Mode** в соответствие с префиксом ключа. | | «Публикуемый ключ должен начинаться с pk_» | Неверный ключ | Используйте publishable key. | | Проверка сообщает об ошибке подключения | Неверный ключ, ключ отозван или сервер не может связаться с `api.stripe.com` | Вставьте ключ заново; проверьте подключение с помощью `curl -I https://api.stripe.com` с сервера. | | Красный баннер «Missing webhook_secret» | Секрет подписи не сохранен | Нажмите **Create webhook** или вставьте секрет `whsec_...` из Stripe Dashboard и нажмите **Save**. | | Средства списаны, но баланс не изменился | Вебхук не доставлен или подпись не проходит проверку | Убедитесь, что URL заканчивается на `/v1/billing/stripe/webhook`, секрет соответствует эндпоинту, и повторите событие в **Gateway events**. В Stripe откройте эндпоинт и проверьте попытки доставки (HTTP 400 означает неверный секрет подписи). | | Сбой «Create webhook» | URL не использует HTTPS или недоступен | Используйте ваш публичный домен `https://`. | | Статус Apple Pay не активен | Домен не подтвержден | Нажмите **Register / verify domain** повторно после того, как файл подтверждения домена начнет возвращать ответ 200. | | Alipay недоступен в окне Check | Не активирован в Stripe | Активируйте его в Stripe Dashboard, затем нажмите **Check**. | | Клиент не видит форму карты | Способ **Card (Stripe)** отключен или не указан secret key | Включите его в **Fees & limits** и сохраните ключи. |