--- title: PayPal description: Подключение PayPal к NexCMP для пополнения баланса: учетные данные REST-приложения, вебхук, песочница и сохраненные аккаунты. url: https://nexcmp.com/ru/docs/billing/paypal/ applies_to: NexCMP 1.6.1 updated: 2026-11-02 --- # PayPal > **Раздел в панели управления:** Finance › Payment channels › PayPal (`/payments/paypal`). Переключатель активности и комиссии находятся в Finance › Payment channels › Fees & limits (`/payments/fees`). ## Назначение {#what-it-does} Позволяет клиентам пополнять баланс в USD со счета PayPal, банковского счета или привязанной карты. Клиенты также могут разрешить NexCMP сохранить аккаунт PayPal для [автоматического пополнения](https://nexcmp.com/ru/docs/billing/auto-top-up/). Используйте этот способ вместе со [Stripe](https://nexcmp.com/ru/docs/billing/stripe/) для клиентов, предпочитающих PayPal. ## Требования {#requirements} | Параметр | Требование | |---|---| | Аккаунт 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** отображается наличие обоих разрешений. | | Зависимости | Нет. | ## Подготовка инфраструктуры {#prepare-the-infrastructure} 1. Войдите на [developer.paypal.com](https://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 {#connect-in-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:///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**. ![Страница PayPal с включенным режимом sandbox и введенными тестовыми учетными данными](https://nexcmp.com/ru/docs/images/billing/paypal-01-keys.webp) ### События вебхука {#webhook-events} 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. ## Проверка {#verify} 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 настраиваются отдельно). ## Ограничения и примечания {#limits-notes} - **Как завершается платеж.** Заказ создается в USD; после подтверждения клиентом **сервер** выполняет списание (с идемпотентным request ID) и начисляет средства на баланс ровно один раз. Вебхук и фоновая сверка каждые 10 минут служат страховкой на случай, если клиент закроет браузер. - **Незавершенные и брошенные заказы.** Заказ может оставаться открытым в течение 12 часов. У клиента может быть не более 5 незавершенных заказов одновременно (сервер возвращает `too_many_pending`, HTTP 429). Заказ, списание по которому не произошло в течение 24 часов, помечается как неудавшийся. - **Вебхук не настроен.** Панель отвечает кодом HTTP 503 на все вебхуки PayPal до тех пор, пока не сохранен Webhook ID. Списания через портал и сверка каждые 10 минут по-прежнему зачисляют средства на баланс, однако любые события, передаваемые PayPal через вебхук (споры, возвраты, задержанные списания), не будут обработаны — нажмите **Create webhook**. - **Сохраненный аккаунт PayPal.** Когда клиент решает сохранить PayPal (или выполняет первое пополнение, включающее [автоматическое пополнение](https://nexcmp.com/ru/docs/billing/auto-top-up/)), PayPal сохраняет платежный токен в своем хранилище. NexCMP хранит только идентификатор и e-mail учетной записи PayPal. См. [Сохраненные способы оплаты](https://nexcmp.com/ru/docs/billing/saved-payment-methods/). - **Возвраты и споры** обрабатываются так же, как в Stripe: запросы на возврат подтверждаются в разделе **Finance › Payouts › Card refunds**; при возникновении спора аккаунт клиента блокируется, а предоплаченные услуги приостанавливаются до его урегулирования. - **Комиссии.** Фактическая комиссия PayPal не запрашивается из сервиса; процентная ставка и фиксированная комиссия, заданные в настройках, определяют, какую сумму увидит клиент и сколько будет зачислено. Реальный тариф зависит от вашей страны (в подсказке к форме указано 4.4 % для Вьетнама и 3.49 % для США). ## Устранение неполадок {#troubleshooting} | Симптом | Причина | Решение | |---|---|---| | «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** или не настроен | Включите его и сохраните учетные данные. |