Тестирование вебхуков PayPal Sandbox на localhost

Чтобы протестировать вебхуки PayPal Sandbox на локальном хосте, запустите прослушиватель локально, откройте его маршрут через общедоступный HTTPS-туннель, зарегистрируйте этот URL-адрес в приложении PayPal Sandbox и инициируйте либо реальную транзакцию Sandbox, либо фиктивное событие в симуляторе вебхуков PayPal. Оставьте проверку подписи включенной: для событий симулятора и событий Sandbox, связанных с приложением, объясняется важная разница в проверке. ниже.

Почему PayPal не может отправлять данные напрямую на локальный хост

PayPal доставляет уведомления вебхука со своих собственных серверов. Такой адрес, как http://localhost:3000/api/paypal, указывает на компьютер PayPal с точки зрения PayPal, а не с вашей. Туннель localhost предоставляет локальному процессу общедоступный адрес HTTPS, оставляя приложение на вашем компьютере.

Официальная документация PayPal Webhooks Simulator гласит, что его прослушиватель должен быть доступен через HTTPS на порту 443. Туннель обрабатывает эту общедоступную конечную точку TLS и перенаправляет запрос на любой локальный порт, например 3000 или 8080.

Выберите правильный путь тестирования PayPal

Мокация событий симулятора для разработки прослушивателей

Имитатор может отправлять типичные события, включая получение платежей, возврат средств и события выставления счетов, без создания транзакции. Это самый быстрый способ подтверждения маршрутизации, анализа JSON, кодов ответов и отправки событий. Фиктивные события не привязаны к REST-приложению, не отображаются в средстве просмотра событий вебхука приложения, не могут быть отправлены повторно и не представляют собой реальные транзакции.

Реальные события Sandbox для сквозного поведения

Для реалистичной интеграции создайте приложение REST на панели инструментов разработчика PayPal, добавьте конечную точку туннеля в качестве вебхука, выберите необходимые типы событий и выполните проверку в Sandbox или операцию API. Эти события принадлежат приложению-Sandbox и используют те же учетные данные приложения, идентификатор вебхука, средство просмотра событий и рабочий процесс повторной отправки, которые вы будете использовать перед рабочей версией.

Настройте веб-хук PayPal на локальном хосте

1. Запустите приложение и убедитесь, что маршрут работает локально: curl -i -X POST http://localhost:3000/api/webhooks/paypal -H 'content-type: application/json' -d '{"event_type":"LOCAL.PING"}'.
2. Запустите npx portpreview 3000 и скопируйте сгенерированный URL-адрес HTTPS.
3. Создайте полный обратный вызов, например https://your-subdomain.portpreview.dev/api/webhooks/paypal.
4. Для пробного тестирования вставьте его в симулятор вебхуков и выберите событие. Для тестирования приложения добавьте его в настройки вебхука REST-приложения в Sandbox.
5. Отправьте событие и проверьте входящий метод, заголовки PayPal, необработанное тело, журналы обработчиков и ответ HTTP.

Подпишитесь только на события, которые обрабатывает ваше приложение. Широкая подписка создает шум и упрощает случайное выполнение бизнес-логики для события, которое вы никогда не моделировали.

A practical Express listener

import express from 'express';

const app = express();
app.use(express.json({ verify: (req, _res, buf) => {
  req.rawBody = Buffer.from(buf);
}}));

app.post('/api/webhooks/paypal', async (req, res) => {
  const event = req.body;

  // Verify first; do not fulfill an order from untrusted JSON.
  const verified = await verifyPayPal(req.headers, event);
  if (!verified) return res.status(401).send('invalid signature');

  // Claim the event ID atomically so retries cannot duplicate work.
  const firstDelivery = await claimEvent(event.id);
  if (!firstDelivery) return res.sendStatus(200);

  if (event.event_type === 'PAYMENT.CAPTURE.COMPLETED') {
    await markOrderPaid(event.resource.id);
  }

  return res.sendStatus(200);
});

app.listen(3000);

Сделайте подтверждение коротким. Сохраните событие, верните ответ 2xx и выполняйте медленную электронную почту или работу по выполнению в очереди. Идентификатор события является естественным ключом идемпотентности; применять уникальное ограничение базы данных, а не полагаться на набор в памяти.

Проверьте правильность подписей PayPal

PayPal отправляет метаданные передачи в заголовках, включая PAYPAL-AUTH-ALGO, PAYPAL-CERT-URL, PAYPAL-TRANSMISSION-ID, PAYPAL-TRANSMISSION-SIG и PAYPAL-TRANSMISSION-TIME. Для событий, связанных с приложением, вы можете отправить эти значения, идентификатор вебхука и событие в API Sandbox /v1/notifications/verify-webhook-signature. Успешного ответа HTTP недостаточно; требуется, чтобы verification_status был равен SUCCESS. PayPal также документирует локальную криптографическую проверку в своем руководстве по интеграции webhook.

.

Предостережение симулятора: Конечная точка проверки обратной передачи PayPal не поддерживает имитационные события симулятора. PayPal документирует буквальный идентификатор вебхука WEBHOOK_ID для самостоятельной проверки подписи симулятора. Не путайте это специальное значение с реальным идентификатором вебхука, присвоенным приложению-Sandbox. Если вашей непосредственной целью является тестирование самого API обратной передачи, сгенерируйте реальную транзакцию Sandbox вместо события имитации симулятора.

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

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

• PAYMENT.CAPTURE.COMPLETED: разрешить выполнение только после проверки ожидаемых идентификаторов заказа, суммы, валюты и статуса захвата.
• PAYMENT.CAPTURE.REFUNDED: безопасное изменение прав и поддержка частичного возврата средств.
• События оформления заказа: отличайте утверждение от завершенного захвата; само по себе одобрение не является доказательством того, что средства были получены.
• События подписки: тестовая активация, приостановка, отмена, неудавшийся платеж и неправильная доставка на вашем конечном автомате выставления счетов.

События поставщика — это уведомления, а не несомненные команды базы данных. Для конфиденциальных переходов получите указанный ресурс PayPal с проверенными учетными данными API и сравните его со своей собственной записью заказа.

Устранение неполадок с неудачной локальной доставкой

Симулятор не может подключиться

Подтвердите, что URL-адрес начинается с https://, включает точный путь вебхука и по-прежнему указывает на работающий туннель. Проверьте общедоступный URL-адрес самостоятельно с помощью curl. Ошибка 404 обычно означает, что путь или маршрут инфраструктуры неверен; 502 обычно означает, что туннель не может связаться с локальным процессом.

Обработчик возвращает 401

Сначала определите, пришло ли событие из симулятора или из зарегистрированного приложения PayPal Sandbox. Проверьте идентификатор вебхука и метод проверки соответственно. Затем убедитесь, что прокси сохранили все заголовки PAYPAL-* и что вы не смешиваете действующие учетные данные с api-m.sandbox.paypal.com.

.

PayPal повторяет попытку или отмечает неудачную доставку

Возвращайте 2xx только после того, как событие было окончательно принято. Избегайте перенаправлений, страниц ошибок HTML, промежуточного программного обеспечения аутентификации и длинных синхронных заданий на маршруте. Используйте средство просмотра событий для реальных событий приложения и результаты моделирования для диагностики имитации доставки. См. руководство по повторным попыткам и идемпотентности для получения информации о устойчивых шаблонах обработки.

Проверочный список безопасности перед запуском в эксплуатацию

• Использовать отдельные учетные данные изолированной программной среды и действующего клиента, идентификаторы вебхуков и секреты конечных точек.
• Проверяйте каждую подпись перед анализом бизнес-полей или изменением состояния.
• Дедупликация по идентификатору события PayPal и атомаризация транзакций выполнения.
• Разрешить только POST, ограничить размер запроса, применить ограничения скорости и по возможности сохранять конфиденциальность URL-адреса туннеля.
• Удалять данные и учетные данные покупателя из журналов; повернуть все, что отображается во время отладки.
• Замените временный URL-адрес туннеля стабильной рабочей конечной точкой, повторите подпись и повторите тесты.

Для получения полных схем событий и проверок используйте основной Справочник API Webhooks PayPal PayPal. Подробные сведения о необработанных телах и безопасных сравнениях, не зависящие от платформы, см. в руководстве по проверке подписи вебхука .

.