Настройка модуля «PayPal»

Приём международных платежей через PayPal — более 200 стран, 25 валют. Эта инструкция написана для владельца ADWOS CMS: что подготовить, где включить модуль, какие поля проверить и как понять, что запуск прошел корректно.

Когда стоит подключать модуль

• Площадкам, которые принимают оплату за объявления, заказы, услуги, бронирования или дополнительные опции.
• Владельцам, которым нужно видеть подтвержденный статус платежа внутри ADWOS CMS, а не сверять оплаты вручную.
• Командам, которые хотят сначала проверить тестовую оплату, а затем спокойно включить боевой режим.

Что изменится на сайте

• Пользователь выбирает способ оплаты «PayPal» в платежном сценарии площадки.
• ADWOS CMS получает статус оплаты и может продолжить заказ, бронирование или покупку услуги.
• Владелец площадки разделяет тестовый и боевой режим, чтобы не смешивать проверочные платежи с реальными.
• Ошибки оплаты, отмены и webhook-события проще проверять в одном понятном сценарии.

Что подготовить заранее

Подготовьте доступы и тестовые данные до включения модуля. Так вы проверите сценарий спокойно и не затронете реальные заказы, пользователей или публичные страницы.

• Создайте кабинет мерчанта у провайдера «PayPal» и убедитесь, что он готов к тестовым операциям.
• Подготовьте секретные ключи, webhook-секрет, валюту и адреса страниц успешной оплаты и отмены.
• Проверьте, есть ли у провайдера отдельные ключи для тестового и боевого режима.
• Решите, какой сценарий будет первым тестом: заказ, бронирование, платное объявление или покупка услуги.

Установка в ADWOS CMS

• Откройте административную панель ADWOS CMS под учетной записью администратора.
• В меню выберите раздел «Каталог», затем откройте «Маркетплейс».
• Найдите модуль «PayPal» по названию или через список модулей.
• Если модуль еще не установлен, нажмите «Установить» и дождитесь завершения установки.
• Откройте карточку установленного модуля, выберите «Управлять», затем перейдите в «Настройки».
• Заполните обязательные поля, сохраните настройки и включите модуль переключателем.

Настройка модуля

В настройках модуля заполняйте только те значения, которые относятся к вашему проекту. Секретные ключи храните в защищенных полях и не переносите их в открытые тексты, письма или инструкции для пользователей.

• «URL при отмене оплаты». Укажите полный адрес страницы, callback или webhook, который должен использовать внешний сервис. Значение по умолчанию: /payment/cancel.
• «Client ID». Укажите идентификатор из личного кабинета провайдера. Обычно это публичная часть подключения, но ее все равно стоит хранить в настройках модуля. Поле обязательное.
• «Client Secret». Обязательное секретное поле. Вставьте значение из кабинета провайдера и не публикуйте его в описаниях, письмах или открытых страницах.
• «Валюта по умолчанию». Укажите валюту, в которой площадка будет работать с этим модулем. Используйте формат, который требует провайдер. Значение по умолчанию: USD.
• «Environment (sandbox | live)». Укажите значение, которое соответствует правилам вашей площадки или документации модуля. Если поле необязательное, оставляйте его пустым только когда понимаете, как это повлияет на сценарий. Значение по умолчанию: sandbox.
• «URL после approve». Укажите полный адрес страницы, callback или webhook, который должен использовать внешний сервис. Значение по умолчанию: /payment/success.
• «Webhook ID». Укажите полный адрес страницы, callback или webhook, который должен использовать внешний сервис. Поле обязательное. ID вебхука из настроек PayPal Developer Dashboard. Используется для проверки подписи каждого входящего уведомления.
• «Дополнительный секрет (опционально)». Секретное поле. Вставьте значение из кабинета провайдера и не публикуйте его в описаниях, письмах или открытых страницах. Произвольная строка. Если задана — передавайте её PayPal в notify URL через ?secret= или в заголовке X-Webhook-Secret. Дополнительный фильтр поверх проверки подписи PayPal.

После сохранения обновите страницу панели управления и убедитесь, что модуль остался включенным. Если есть тестовый режим, сначала завершите проверку в нем, а уже потом переходите на боевые ключи.

Проверка перед запуском

• Создайте тестовый заказ или сделку и выберите оплату через «PayPal».
• Проведите тестовую оплату в кабинете провайдера или через тестовую карту, если она доступна.
• Проверьте в ADWOS CMS, что статус заказа изменился автоматически.
• Отдельно проверьте отказ, отмену оплаты и повторный webhook, чтобы увидеть поведение при ошибке.

Частые ошибки

• Статус заказа не меняется после оплаты. Проверьте webhook-секрет, адрес webhook и совпадение тестового или боевого режима.
• Пользователь не возвращается на сайт. Проверьте URL успешной оплаты и URL отмены в настройках модуля и кабинете провайдера.
• Провайдер отклоняет платеж. Проверьте валюту, страну мерчанта, ограничения аккаунта и тестовые реквизиты.
• На сайте не виден способ оплаты. Убедитесь, что модуль включен и доступен для нужного платежного сценария.

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