Czy symulator webhooks PayPal może wysyłać do hosta lokalnego?

Nie bezpośrednio. Udostępnij lokalną trasę webhooka za pomocą publicznego tunelu HTTPS, a następnie wprowadź ten adres URL HTTPS w symulatorze. PayPal wymaga słuchacza, do którego może dotrzeć przez Internet.

Dlaczego weryfikacja podpisu PayPal kończy się niepowodzeniem w przypadku zdarzenia symulacyjnego?

Nie można publikować fałszywych zdarzeń symulatora w punkcie końcowym weryfikacji-webhook-signature systemu PayPal. PayPal dokumentuje WEBHOOK_ID w celu samoweryfikacji podpisów na symulatorze; użyj prawdziwego zdarzenia aplikacji sandbox, aby przetestować weryfikację ogłaszania zwrotnego.

Jaka jest różnica między piaskownicą PayPal a webhookami symulatora?

Elementy webhook symulatora to próbne, niezależne od aplikacji ładunki służące do testowania odbiorników. Elementy webhook aplikacji PayPal Sandbox wynikają z aktywności środowiska Sandbox, korzystają z prawdziwego identyfikatora elementu webhook aplikacji, pojawiają się w narzędziach zdarzeń i obsługują normalny przepływ pracy weryfikacyjnej.

Jaki stan HTTP powinien zwrócić webhook PayPal?

Wyślij odpowiedź 2xx po zweryfikowaniu i trwałym zaakceptowaniu zdarzenia. Odrzuć nieprawidłowe podpisy i przenieś powolne prace związane z realizacją lub powiadomieniami do kolejki, aby dostawa nie przekroczyła limitu czasu.

Testowanie webhooków PayPal Sandbox na localhost

Aby przetestować webhooki PayPal Sandbox na hoście lokalnym, uruchom lokalnie odbiornik, ujawnij jego trasę przez publiczny tunel HTTPS, zarejestruj ten adres URL w aplikacji PayPal Sandbox i wywołaj prawdziwą transakcję w środowisku Sandbox lub zdarzenie próbne w symulatorze webhooks PayPal. Pozostaw włączoną weryfikację podpisu: zdarzenia symulatora i zdarzenia Sandbox powiązane z aplikacją podlegają ważnej weryfikacji różnica wyjaśniona poniżej.

Dlaczego PayPal nie może wysyłać bezpośrednio do lokalnego hosta

PayPal dostarcza powiadomienia webhook z własnych serwerów. Adres taki jak http://localhost:3000/api/paypal wskazuje na komputer PayPal z punktu widzenia PayPal, a nie Twojego. tunel localhost nadaje procesowi lokalnemu publiczny adres HTTPS podczas opuszczania aplikacji na komputerze.

Oficjalna dokumentacja PayPal Webhooks Simulator mówi, że jego odbiornik musi być osiągalny przez HTTPS na porcie 443. Tunel obsługuje ten publiczny punkt końcowy TLS i przekazuje żądanie do dowolnego portu lokalnego, takiego jak 3000 lub 8080.

Wybierz właściwą ścieżkę testową PayPal

Próbne zdarzenia symulacyjne dla rozwoju słuchaczy

Symulator może wysyłać reprezentatywne zdarzenia, w tym przechwytywanie płatności, zwroty kosztów i zdarzenia rozliczeniowe, bez tworzenia transakcji. Jest to najszybszy sposób potwierdzania routingu, analizowania JSON, kodów odpowiedzi i wysyłania zdarzeń. Zdarzenia próbne nie są powiązane z aplikacją REST, nie pojawiają się w przeglądarce zdarzeń elementu webhook aplikacji, nie można ich ponownie wysłać i nie reprezentują rzeczywistych transakcji.

Prawdziwe zdarzenia w środowisku Sandbox zapewniające kompleksowe zachowanie

Aby zapewnić realistyczną integrację, utwórz aplikację REST w panelu programisty PayPal, dodaj punkt końcowy tunelu jako element webhook, wybierz wymagane typy zdarzeń i wykonaj operację w środowisku Sandbox lub za pomocą interfejsu API. Te zdarzenia należą do aplikacji PayPal Sandbox i korzystają z tych samych danych uwierzytelniających aplikacji, identyfikatora elementu webhook, przeglądarki zdarzeń i przepływu pracy ponownego wysyłania, których będziesz używać przed rozpoczęciem produkcji.

Skonfiguruj webhook PayPal na localhost

Uruchom aplikację i potwierdź, że trasa działa lokalnie: curl -i -X POST http://localhost:3000/api/webhooks/paypal -H 'content-type: application/json' -d '{"event_type":"LOCAL.PING"}'.
Uruchom npx portpreview 3000 i skopiuj wygenerowany adres URL HTTPS.
Stwórz pełne wywołanie zwrotne, na przykład https://your-subdomain.portpreview.dev/api/webhooks/paypal.
W celu przeprowadzenia próbnych testów wklej je do symulatora webhooks i wybierz zdarzenie. Aby przetestować aplikację, dodaj ją w ustawieniach webhooka aplikacji REST w środowisku Sandbox.
Wyślij zdarzenie i sprawdź metodę przychodzącą, nagłówki PayPal, nieprzetworzoną treść, dzienniki obsługi i odpowiedź HTTP.

Zasubskrybuj tylko zdarzenia obsługiwane przez Twoją aplikację. Szeroka subskrypcja powoduje hałas i ułatwia przypadkowe uruchomienie logiki biznesowej dla zdarzenia, którego nigdy nie modelowałeś.

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);

Potwierdzenie powinno być krótkie. Zapisz wydarzenie, zwróć odpowiedź 2xx i wykonuj powolne prace e-mailowe lub realizacyjne w kolejce. Identyfikator zdarzenia jest naturalnym kluczem idempotencji; wymuszaj unikalne ograniczenie bazy danych, zamiast polegać na zestawie w pamięci.

Zweryfikuj poprawnie podpisy PayPal

PayPal wysyła metadane transmisji w nagłówkach, w tym PAYPAL-AUTH-ALGO, PAYPAL-CERT-URL, PAYPAL-TRANSMISSION-ID, PAYPAL-TRANSMISSION-SIG i PAYPAL-TRANSMISSION-TIME. W przypadku zdarzeń związanych z aplikacją możesz przesłać te wartości, identyfikator webhooka i zdarzenie do interfejsu API środowiska Sandbox /v1/notifications/verify-webhook-signature. Pomyślna odpowiedź HTTP nie wystarczy; wymagają verification_status równego SUCCESS. PayPal dokumentuje również lokalną weryfikację kryptograficzną w swoim przewodniku integracji webhooka.

Ostrzeżenie dotyczące symulatora: Punkt końcowy weryfikacji ogłaszania zwrotnego w systemie PayPal nie obsługuje pozorowanych zdarzeń symulatora. PayPal dokumentuje dosłowny identyfikator webhooka WEBHOOK_ID na potrzeby samodzielnej weryfikacji podpisu symulatora. Nie myl tej specjalnej wartości z prawdziwym identyfikatorem webhooka przypisanym do aplikacji sandbox. Jeśli Twoim bezpośrednim celem jest przetestowanie samego interfejsu API ogłaszania zwrotnego, wygeneruj rzeczywistą transakcję w środowisku Sandbox zamiast pozorowanego zdarzenia symulatora.

Przed pobraniem sprawdź, czy adres URL certyfikatu jest zgodny z udokumentowanymi zasadami PayPal, zachowaj dokładną reprezentację zdarzeń wymaganą przez metodę weryfikacji i nigdy nie rejestruj tokenów dostępu, kluczy tajnych klientów, podpisów ani pełnych ładunków płatności.

Testuj zdarzenia zmieniające pieniądze lub dostęp

PAYMENT.CAPTURE.COMPLETED: realizacja dotacji dopiero po sprawdzeniu oczekiwanych identyfikatorów zamówień, kwoty, waluty i statusu przejęcia.
PAYMENT.CAPTURE.REFUNDED: bezpiecznie odwracaj uprawnienia i wspieraj częściowe zwroty pieniędzy.
Zdarzenia związane z zamówieniem do kasy: rozróżnij zatwierdzenie od zakończonego przechwycenia; Samo zatwierdzenie nie jest dowodem przejęcia środków.
Zdarzenia subskrypcji: aktywacja testu, zawieszenie, anulowanie, nieudana płatność i dostawa poza zamówieniem na urządzeniu ze stanem rozliczeniowym.

Zdarzenia dostawcy to powiadomienia, a nie niekwestionowane polecenia bazy danych. W przypadku wrażliwych przejść pobierz wskazany zasób PayPal z uwierzytelnionymi poświadczeniami API i porównaj go z własnym rekordem zamówienia.

Rozwiązywanie problemów z nieudanymi dostawami lokalnymi

Symulator nie może się połączyć

Potwierdź, że adres URL zaczyna się od https://, zawiera dokładną ścieżkę elementu webhook i nadal wskazuje działający tunel. Przetestuj publiczny adres URL samodzielnie za pomocą curl. Kod 404 zwykle oznacza, że ścieżka lub trasa szkieletowa jest błędna; kod 502 ogólnie oznacza, że tunel nie może dotrzeć do procesu lokalnego.

Program obsługi zwraca 401

Najpierw ustal, czy zdarzenie pochodzi z symulatora, czy z zarejestrowanej aplikacji typu sandbox. Sprawdź odpowiednio identyfikator webhooka i metodę weryfikacji. Następnie sprawdź, czy serwery proxy zachowały wszystkie nagłówki PAYPAL-* i czy nie mieszasz danych uwierzytelniających na żywo z api-m.sandbox.paypal.com.

PayPal ponawia próbę lub oznacza, że dostawa nie powiodła się

Zwróć 2xx dopiero po trwałym zaakceptowaniu zdarzenia. Unikaj przekierowań, stron błędów HTML, oprogramowania pośredniczącego do uwierzytelniania i długich zadań synchronicznych na trasie. Użyj przeglądarki zdarzeń, aby wyświetlić rzeczywiste zdarzenia w aplikacji, oraz wyników symulatora, aby uzyskać próbną diagnostykę dostarczania. Zobacz przewodnik dotyczący ponownych prób i idempotencji, aby zapoznać się z trwałymi wzorcami przetwarzania.

Lista kontrolna bezpieczeństwa przed uruchomieniem

Użyj oddzielnych poświadczeń środowiska Sandbox i klienta na żywo, identyfikatorów webhook i tajnych punktów końcowych.
Zweryfikuj każdy podpis przed analizą pól biznesowych lub zmianą stanu.
Deduplikuj według identyfikatora zdarzenia PayPal i spraw, aby transakcje realizacji były niepodzielne.
Zezwól tylko na POST, ogranicz rozmiar żądania, zastosuj limity szybkości i zachowaj prywatność adresu URL tunelu, jeśli to możliwe.
Usuń dane kupującego i dane uwierzytelniające z logów; obróć wszystko, co zostało ujawnione podczas debugowania.
Zastąp tymczasowy adres URL tunelu stabilnym produkcyjnym punktem końcowym i powtórz testy podpisu i ponów próbę.

Aby uzyskać pełne schematy zdarzeń i weryfikacji, skorzystaj z podstawowego Informacji o interfejsie API Webhooks firmy PayPal. Aby poznać niezależne od platformy szczegółowe informacje na temat surowych treści i bezpiecznych porównań, przeczytaj przewodnik dotyczący weryfikacji podpisu webhooka.