Stripe

Где найти в панели: Finance › Payment channels › Stripe (/payments/stripe). Переключатели и комиссии: Finance › Payment channels › Fees & limits (/payments/fees).

Назначение

Stripe принимает платежи с карт для пополнения баланса. С тем же аккаунтом вы можете подключить Apple Pay, Google Pay, Link и Alipay, а также позволить клиентам сохранять карту для автоматического пополнения. Используйте его как основной канал для международных клиентов.

Требования

Параметр	Требование
Аккаунт 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 настраивает это автоматически.
Зависимости	Нет.

Использование одного аккаунта Stripe

NexCMP обрабатывает события webhook только для платежей, созданных им самим, поэтому вы можете использовать аккаунт Stripe параллельно с другими приложениями.

Подготовка инфраструктуры

На стороне Stripe:

1. Войдите в Stripe Dashboard. Включите или отключите Test mode в зависимости от того, проводите ли вы тестирование или запускаете приём платежей. Ключи одного режима не подходят для другого.
2. Перейдите в Developers › API keys. Скопируйте Publishable key, затем откройте и скопируйте Secret key. Храните секретный ключ в безопасности.
3. (Необязательно) Перейдите в Settings › Payment methods и активируйте Alipay, если хотите принимать этот способ оплаты.
4. Создавать webhook вручную не требуется — NexCMP сделает это автоматически (см. шаг 5 ниже). Если вы предпочитаете ручную настройку, создайте endpoint в Developers › Webhooks с URL и событиями, указанными в разделе Webhook.

Подключение в 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://<your-domain>/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.

Webhook

Красный баннер «Missing webhook_secret» отображается до тех пор, пока не сохранён секрет подписи. Без него пополнения через Stripe не зачисляются, даже если средства были успешно списаны со стороны Stripe.

Параметр	Значение
URL	https://<your-domain>/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

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 включенной.

Apple Pay остается неактивным

Для работы Apple Pay необходимо, чтобы файл подтверждения домена возвращал HTTP 200 на вашем публичном домене. Если перед панелью используется Cloudflare или другой прокси, не блокируйте /.well-known/.

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 дней, на странице появится предупреждение.

Проверка

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 (вебхуки для тестового и боевого режимов настраиваются раздельно).

Ограничения и примечания

• Суммы и валюта. Кошельки ведутся в USD. Платежи картой, через кошельки и Link списываются в USD; Alipay отображается клиенту в JPY и конвертируется по вашему курсу.
• Комиссии. Реальная комиссия Stripe не считывается автоматически; размер комиссии, который видит клиент и который зачисляется на кошелек, определяется заданным вами процентом. Выберите Customer pays top-up fee в Fees & limits, чтобы взимать комиссию сверх суммы пополнения.
• Сохраненные карты. Если клиент отмечает Save card for auto top-up, данные карты сохраняются на стороне Stripe, а не на вашем сервере. См. 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://<their-domain>/v1/billing/stripe/webhook/r/<id>); см. Resellers.

Устранение неполадок

Симптом	Причина	Решение
"Секретный ключ должен начинаться с 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 и сохраните ключи.