PayPal

Раздел в панели управления: Finance › Payment channels › PayPal (/payments/paypal). Переключатель активности и комиссии находятся в Finance › Payment channels › Fees & limits (/payments/fees).

Назначение

Позволяет клиентам пополнять баланс в USD со счета PayPal, банковского счета или привязанной карты. Клиенты также могут разрешить NexCMP сохранить аккаунт PayPal для автоматического пополнения. Используйте этот способ вместе со Stripe для клиентов, предпочитающих PayPal.

Требования

Параметр	Требование
Аккаунт PayPal	Аккаунт PayPal Business с возможностью приема USD.
REST-приложение	Одно REST-приложение в PayPal Developer Dashboard (Apps & Credentials), предоставляющее Client ID и Client secret. Используйте вкладку Sandbox для тестирования и Live для рабочей среды.
Сеть	Доступность по HTTPS из Интернета (PayPal отправляет запросы к вебхуку) и исходящий доступ к api-m.paypal.com (live) или api-m.sandbox.paypal.com (sandbox), порт 443.
Права доступа	REST-приложению требуются разрешения на возврат средств и работу с вебхуками. В диалоговом окне Check отображается наличие обоих разрешений.
Зависимости	Нет.

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

1. Войдите на developer.paypal.com с учетной записью Business и откройте Apps & Credentials.
2. Выберите Sandbox (тестирование) или Live, затем нажмите Create App. Укажите имя, например «NexCMP».
3. Скопируйте Client ID и Secret приложения.
4. Для тестирования используйте раздел Testing Tools › Sandbox Accounts, чтобы найти или создать тестовый аккаунт Personal (покупатель).
5. Вам не нужно создавать вебхук вручную: NexCMP создает его с помощью кнопки Create webhook.

Подключение в NexCMP

1. Откройте Finance › Payment channels › PayPal (/payments/paypal).
2. В разделе API keys выберите Mode: live (реальные средства, api-m.paypal.com) или sandbox (api-m.sandbox.paypal.com).
3. Вставьте Client ID (не менее 20 символов) и Client secret.
4. Нажмите Check. Проверяются введенные учетные данные (сохранять не требуется) и выводятся сведения о подключении, App ID, режиме, наличии разрешений refund и webhooks, а также сроке действия токена.
5. Нажмите Save.
6. В карточке Webhook убедитесь, что URL указан как https://<your-domain>/v1/billing/paypal/webhook (должен быть https), затем нажмите Create webhook и подтвердите действие. NexCMP запрашивает у PayPal создание или обновление вебхука с 11 событиями и сохраняет полученный Webhook ID. Кнопка использует сохраненные ключи — сохраните изменения, если вы только что их редактировали.
7. Снова нажмите Check: в строке Webhook должно быть указано «exists, 11 events».
8. Откройте Fees & limits, включите PayPal, укажите значения PayPal fee % (по умолчанию 4.4) и PayPal fixed fee (cents) (по умолчанию 30) согласно вашему тарифу и нажмите Save channels & fees.

События вебхука

NexCMP регистрирует следующие 11 событий: CHECKOUT.ORDER.APPROVED, PAYMENT.CAPTURE.COMPLETED, PAYMENT.CAPTURE.PENDING, PAYMENT.CAPTURE.DECLINED, PAYMENT.CAPTURE.REFUNDED, PAYMENT.CAPTURE.REVERSED, CUSTOMER.DISPUTE.CREATED, CUSTOMER.DISPUTE.UPDATED, CUSTOMER.DISPUTE.RESOLVED, RISK.DISPUTE.CREATED, CHECKOUT.PAYMENT-APPROVAL.REVERSED.

Каждый вебхук проверяется через API верификации подписи PayPal, сохраняется один раз и обрабатывается идемпотентно. NexCMP никогда не доверяет сумме из тела вебхука: перед зачислением средств он запрашивает данные о списании напрямую у PayPal.

Проверка

1. Оставьте Mode в значении sandbox. В клиентском портале откройте Billing › Deposit, выберите PayPal, нажмите Continue on PayPal (или кнопку PayPal) и выполните вход под тестовым аккаунтом покупателя sandbox.
2. Подтвердите платеж. Вы вернетесь в портал, баланс увеличится, а платеж появится в разделе Finance › Billing › Top-ups со статусом Completed.
3. Откройте Payment channels › Gateway events › PayPal & USDT: событие PAYMENT.CAPTURE.COMPLETED появится в списке.
4. Убедившись, что все работает, переключите Mode на live, введите боевые учетные данные, нажмите Save, а затем снова Create webhook (вебхуки для sandbox и live настраиваются отдельно).

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

• Как завершается платеж. Заказ создается в USD; после подтверждения клиентом сервер выполняет списание (с идемпотентным request ID) и начисляет средства на баланс ровно один раз. Вебхук и фоновая сверка каждые 10 минут служат страховкой на случай, если клиент закроет браузер.
• Незавершенные и брошенные заказы. Заказ может оставаться открытым в течение 12 часов. У клиента может быть не более 5 незавершенных заказов одновременно (сервер возвращает too_many_pending, HTTP 429). Заказ, списание по которому не произошло в течение 24 часов, помечается как неудавшийся.
• Вебхук не настроен. Панель отвечает кодом HTTP 503 на все вебхуки PayPal до тех пор, пока не сохранен Webhook ID. Списания через портал и сверка каждые 10 минут по-прежнему зачисляют средства на баланс, однако любые события, передаваемые PayPal через вебхук (споры, возвраты, задержанные списания), не будут обработаны — нажмите Create webhook.
• Сохраненный аккаунт PayPal. Когда клиент решает сохранить PayPal (или выполняет первое пополнение, включающее автоматическое пополнение), PayPal сохраняет платежный токен в своем хранилище. NexCMP хранит только идентификатор и e-mail учетной записи PayPal. См. Сохраненные способы оплаты.
• Возвраты и споры обрабатываются так же, как в Stripe: запросы на возврат подтверждаются в разделе Finance › Payouts › Card refunds; при возникновении спора аккаунт клиента блокируется, а предоплаченные услуги приостанавливаются до его урегулирования.
• Комиссии. Фактическая комиссия PayPal не запрашивается из сервиса; процентная ставка и фиксированная комиссия, заданные в настройках, определяют, какую сумму увидит клиент и сколько будет зачислено. Реальный тариф зависит от вашей страны (в подсказке к форме указано 4.4 % для Вьетнама и 3.49 % для США).

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

Симптом	Причина	Решение
«Client ID слишком короткий»	Вставлено менее 20 символов	Скопируйте Client ID полностью.
«Webhook URL должен использовать https»	В URL указан http://	Используйте ваш публичный домен https://.
Check сообщает об ошибке подключения	Неверный режим (боевые ключи в sandbox или наоборот), неверный secret, нет исходящего доступа	Сопоставьте Mode с типом ключа; проверьте curl -I https://api-m.paypal.com с сервера.
В разрешениях refund / webhooks указано «no»	У REST-приложения нет необходимых разрешений	Включите эти функции для приложения в PayPal Developer Dashboard.
Баннер «PayPal key set, NO webhook»	Отсутствует Webhook ID	Нажмите Create webhook.
«Webhook not found» в Check	Вебхук был удален в PayPal или принадлежит другому приложению	Снова нажмите Create webhook.
Клиент получает сообщение, что PayPal отклонил платеж	PayPal отклонил выбранный способ оплаты	Попросите клиента выбрать другой способ оплаты.
Клиент видит ошибку «Too many pending requests»	5 открытых заказов	Дождитесь истечения их срока действия или завершите их.
Отсутствует кнопка PayPal	PayPal отключен в Fees & limits или не настроен	Включите его и сохраните учетные данные.