Jak skonfigurować witrynę do akceptowania webhooków od Stripe

Webhooki pozwalają Stripe na wysyłanie wiadomości z powrotem do Twojej witryny WordPress. Konfiguracja webhooków jest wymagana dla niektórych funkcji WP Simple Pay, takich jak wysyłanie wiadomości e-mail, tworzenie planów ratalnych, umożliwienie klientom aktualizacji szczegółów płatności subskrypcji oraz korzystanie z integracji z AffiliateWP.

WP Simple Pay próbuje automatycznie tworzyć punkty końcowe webhooków. W większości przypadków ręczna konfiguracja, pokazana poniżej, nie będzie konieczna.

Dodaj punkt końcowy w Stripe

Aby dodać odpowiednie punkty końcowe webhooków, w swoim panelu Stripe przejdź do Deweloperzy → Webhooki.

Kliknij Dodaj punkt końcowy, a następnie dodaj adres URL znaleziony w WP Simple Pay → Ustawienia → Stripe → Webhooki.

Nie włączaj opcji Nasłuchuj zdarzeń na kontach połączonych, ponieważ spowoduje to awarię funkcjonalności webhooków WP Simple Pay.

Teraz musisz dodać konkretne zdarzenia do nasłuchiwania, klikając przycisk +Wybierz zdarzenia. Po wykonaniu tej czynności możesz skopiować i wkleić każde z poniższych zdarzeń do pola wyszukiwania Wybierz zdarzenia do wysłania → Wyszukaj zdarzenia.

Po wyszukaniu każdego terminu kliknij pole wyboru, aby go dodać, i wyszukaj dodatkowe terminy. Nie klikaj Dodaj zdarzenia, dopóki nie zaznaczysz wszystkich poniższych zdarzeń:

• payment_intent.processing
• payment_intent.succeeded
• charge.failed
• charge.refunded
• charge.succeeded
• checkout.session.completed
• customer.subscription.deleted
• customer.subscription.updated
• invoice.payment_succeeded
• invoice.upcoming

Szczegóły dotyczące funkcjonalności każdego z tych zdarzeń znajdują się na dole tego dokumentu.

Po dodaniu zdarzeń kliknij Dodaj punkt końcowy , aby zakończyć proces. Po dodaniu punktu końcowego nowy adres URL powinien pojawić się w ustawieniach webhooków.

Konfiguracja tajnego klucza podpisu webhooka

Stripe może podpisywać zdarzenia webhook, które wysyła do Twoich punktów końcowych, w celu zwiększenia bezpieczeństwa i zdecydowanie zalecamy skonfigurowanie tego.

Aby to zrobić, pobierz tajny klucz swojego punktu końcowego z ustawień webhooków w Panelu. Wybierz dodany punkt końcowy, dla którego chcesz uzyskać tajny klucz, a następnie kliknij przycisk Pokaż .

Następnie skopiuj tajny klucz podpisu z Panelu Stripe, wróć do WP Simple Pay → Ustawienia → Stripe → Webhooki w swoim panelu administracyjnym WordPress, a następnie wklej go do pola tekstowego Tajny klucz punktu końcowego dla bieżącego trybu płatności.

Powtórz w trybie testowym

Punkt końcowy webhook musi być również utworzony w trybie testowym. Przełącz przełącznik Tryb testowy w prawym górnym rogu panelu Stripe i powtórz powyższe kroki.

Opisy typów zdarzeń

invoice.payment_succeeded

• Używane do zwiększania planów ratalnych i wysyłania wiadomości e-mail „Potwierdzenie płatności” i „Powiadomienie o płatności” e-maile dla subskrypcji.
• Udostępnia akcję simpay_webhook_subscription_created do dalszego przetwarzania po pomyślnym utworzeniu subskrypcji.
• Udostępnia akcję simpay_webhook_invoice_payment_succeeded do dalszego przetwarzania po przetworzeniu faktury.

<?php
add_action(
	'simpay_webhook_subscription_created',
	/**
	 * Fires when a subscription is created in Stripe.
	 * 
	 * @param \SimplePay\Vendor\Stripe\Event        $event Stripe webhook event.
	 * @param \SimplePay\Vendor\Stripe\Subscription $subscription Stripe Subscription.
	 */
	function( $event, $subscription ) {
		// Do something.
	},
	10,
	2
);

<?php
add_action(
	'simpay_webhook_invoice_payment_succeeded',
	/**
	 * Fires when a subscription invoice payment has succeeded.
	 * Does not fire for the subscription creation (first) invoice.
	 * 
	 * @param \SimplePay\Vendor\Stripe\Event        $event Stripe webhook event.
	 * @param \SimplePay\Vendor\Stripe\Invoice      $invoice Stripe Invoice object.
	 * @param \SimplePay\Vendor\Stripe\Subscription $subscription Stripe Subscription object.
	 */
	function( $event, $invoice, $subscription ) {
		// Do something.
	},
	10,
	3
);

Dowiedz się, jak dodać niestandardowy kod →

payment_intent.succeeded

• Wysyła wiadomości e-mail „Potwierdzenie płatności” i „Powiadomienie o płatności” e-maile dla płatności jednorazowych.
• Udostępnia akcję simpay_webhook_payment_intent_succeeded do dalszego przetwarzania po pomyślnej płatności

<?php
add_action(
	'simpay_webhook_payment_intent_succeeded',
	/**
	 * Fires when a one-time payment has succeeded.
	 * 
	 * @param \SimplePay\Vendor\Stripe\Event         $event Stripe webhook event.
	 * @param \SimplePay\Vendor\Stripe\PaymentIntent $paymentintent Stripe PaymentIntent.
	 */
	function( $event, $paymentintent ) {
		// Do something.
	},
	10,
	2
);

Dowiedz się, jak dodać niestandardowy kod →

invoice.upcoming

• Wysyła przypomnienie e-mailem „Nadchodząca faktura” e-mail o aktualizacji metody płatności. Dowiedz się więcej

checkout.session.completed

• Używane do usuwania wygenerowanych porzuconych rekordów Stripe Checkout.
• Udostępnia akcję simpay_webhook_checkout_session_completed do dalszego przetwarzania w razie potrzeby.

charge.succeeded

• Wysyła wiadomości e-mail „Potwierdzenie płatności” i „Powiadomienie o płatności” e-maile dla płatności jednorazowych przy użyciu obciążenia ACH.
• Udostępnia akcję simpay_webhook_charge_succeeded do dalszego przetwarzania po pomyślnej płatności

charge.failed

• Udostępnia akcję simpay_webhook_charge_failed do dalszego przetwarzania po nieudanej transakcji.

Często zadawane pytania

Czy webhooki są wymagane?

Webhooki nie są wymagane do przetwarzania płatności, a gdy webhook zawiedzie, nie oznacza to, że płatność nie została przetworzona. Jednak webhooki są wykorzystywane do zasilania funkcji, takich jak wykrywanie oszustw, potwierdzenia e-mailem, powiadomienia o nadchodzących fakturach i zarządzanie planami ratalnymi.

Webhooks są wymagane do korzystania z weryfikacji adresu e-mail po wykryciu oszustwa.

Nawet jeśli obecnie nie korzystasz z tych funkcji, zdecydowanie zaleca się upewnienie się, że punkt końcowy webhook został poprawnie skonfigurowany, aby uniknąć nieporozumień, jeśli zdecydujesz się włączyć te funkcje w przyszłości, lub jeśli WP Simple Pay będzie wymagać tych funkcjonalności dla przyszłych funkcji.

Dlaczego widzę komunikat „WP Simple Pay może nie działać poprawnie”?

WP Simple Pay próbuje ostrzec o możliwej błędnej konfiguracji lub błędzie punktu końcowego webhook, aby uniknąć zakłóceń w funkcjach korzystających z funkcjonalności webhook (e-maile, plany ratalne itp.). Jeśli WP Simple Pay nie będzie w stanie zweryfikować oczekiwanego zdarzenia webhook, zobaczysz bańkę powiadomienia w ustawieniach wtyczki i komunikat o błędzie „WP Simple Pay może nie działać poprawnie”.

Jak naprawić błędnie skonfigurowany punkt końcowy webhook?

Aby rozwiązać problem możliwej błędnej konfiguracji punktu końcowego webhook, odwiedź Developers → Webhooks w swoim panelu Stripe (jeśli jesteś w Trybie testowym, wyświetl punkty końcowe trybu testowego).

W sekcji Hosted endpoints powinna znajdować się pozycja zawierająca odbiornik zdarzeń webhook WP Simple Pay: wp-json/wpsp/v1/webhook-receiver. Jeśli nie widzisz tego punktu końcowego, wykonaj kroki konfiguracji opisane na początku tego artykułu.

Kliknij adres URL punktu końcowego WP Simple Pay, aby wyświetlić jego konfigurację. Znajdziesz tu listę zdarzeń webhook, które zostały wysłane do punktu końcowego.

Kliknij kartę Failed, aby wyświetlić listę zdarzeń, które zakończyły się niepowodzeniem.

Jeśli masz nieudane zdarzenia webhook, wybranie jednej z pozycji ujawni odpowiedź otrzymaną z adresu URL punktu końcowego. Ta odpowiedź często zawiera informacje o tym, dlaczego punkt końcowy nie przetworzył zdarzenia w sekcji Response.

Nie udało się połączyć z hostem zdalnym

Stripe nie mógł skomunikować się z Twoim serwerem. Upewnij się, że Twój serwer WWW odpowiada na żądania i jest w stanie odpowiadać na w pełni kwalifikowane nazwy domen i adresy IP Stripe.

Nie znaleziono podpisów pasujących do oczekiwanego podpisu dla ładunku

Stripe nie mógł zweryfikować danych zdarzenia webhook przy użyciu sekretów podpisu podanych w WP Simple Pay → Ustawienia → Stripe → Webhooks. Podczas przeglądania punktu końcowego webhook kliknij Reveal w sekcji Signing Secret i zaktualizuj swoje ustawienia sekretu podpisu w WP Simple Pay dla każdego trybu płatności.

404 ERR <!DOCTYPE html>

Adres URL punktu końcowego webhook jest nieprawidłowy i wskazuje na stronę 404 (nie znaleziono). Odwiedź WP Simple Pay → Ustawienia → Stripe → Webhooks aby znaleźć prawidłową wartość adresu URL punktu końcowego webhook i zaktualizuj punkt końcowy w Stripe.

Zweryfikowałem ustawienia mojego punktu końcowego, dlaczego nadal widzę błąd?

WP Simple Pay celowo nadmiernie reaguje na potencjalne błędy konfiguracji, aby mieć pewność, że prawdziwy błąd nie pozostanie niezauważony. Jednakże, nadal możliwe jest otrzymywanie fałszywych alarmów o błędnie skonfigurowanym zdarzeniu webhook. Może się to zdarzyć, jeśli wystąpi opóźnienie dłuższe niż przeciętne w przesyłaniu danych zdarzenia przez Stripe, lub w niektórych przypadkach Stripe Checkout, gdy strona płatności poza witryną zostanie porzucona.

Jeśli zweryfikowałeś, że na Twoim punkcie końcowym nie ma nieudanych zdarzeń punktu końcowego webhook, możesz wyłączyć powiadomienie o konfiguracji, wykonując poniższe kroki.

Czy mogę wyłączyć powiadomienia o konfiguracji webhook?

Jak wspomniano wcześniej, zdecydowanie zaleca się prawidłowe skonfigurowanie i utrzymanie aktywnego punktu końcowego webhook. Jednakże, na własne ryzyko, jeśli nie chcesz być powiadamiany o potencjalnych błędach konfiguracji lub nieprawidłowo odebranych zdarzeniach, możesz trwale zignorować powiadomienie w WP Simple Pay → Ustawienia → Stripe → Webhooks, klikając Nie pokazuj ponownie.