Integracja płatności online ze sklepem - Przelewy24, PayU i Stripe od strony technicznej

Notyfikacje i statusy płatności - jak je obsłużyć

Notyfikacja to wiadomość HTTP, którą bramka wysyła na serwer sklepu po zmianie stanu płatności. Od jej poprawnej obsługi zależy cała integracja. Każda z bramek ma tu swoje wymagania.

Przelewy24 - notyfikacja i weryfikacja transakcji

Po opłaceniu transakcji Przelewy24 wysyła notyfikację na adres urlStatus podany przy rejestracji. Sklep sprawdza podpis, porównuje kwotę i walutę z zamówieniem, a następnie wywołuje w API metodę weryfikacji transakcji. Dopiero weryfikacja zamyka transakcję po stronie Przelewy24. Integracja, która pomija ten krok, zmienia status zamówienia w sklepie, ale płatność nie zostaje poprawnie rozliczona - to jeden z najczęstszych błędów, które spotykamy przy przejmowaniu starszych integracji.

PayU - statusy zamówienia i potwierdzanie płatności

PayU przesyła notyfikacje przy każdej zmianie statusu zamówienia: m.in. PENDING, WAITING_FOR_CONFIRMATION, COMPLETED i CANCELED. Podpis znajduje się w nagłówku OpenPayu-Signature i sprawdza się go drugim kluczem z konfiguracji punktu płatności. Jeśli punkt ma wyłączone automatyczne odbieranie płatności, zamówienie zatrzymuje się w statusie WAITING_FOR_CONFIRMATION i sklep musi je potwierdzić lub anulować przez API. Gdy nikt tego nie zrobi, płatność po pewnym czasie zostanie anulowana.

Stripe - webhooki i idempotencja

Stripe informuje o zdarzeniach przez webhooki, np. payment_intent.succeeded, payment_intent.payment_failed czy charge.refunded, a przy Stripe Checkout także checkout.session.completed. Podpis w nagłówku Stripe-Signature weryfikuje się sekretem endpointu, najlepiej funkcją z oficjalnej biblioteki. Przy zapytaniach tworzących płatności i zwroty warto wysyłać nagłówek Idempotency-Key - wtedy ponowione żądanie nie utworzy drugiej operacji. Stripe obsługuje w Polsce m.in. BLIK i Przelewy24 jako metody płatności, więc może zastąpić lokalną bramkę także dla klientów, którzy nie płacą kartą.

[#uwaga] Wszystkie bramki mogą wysłać to samo powiadomienie więcej niż raz, a powiadomienia mogą dotrzeć w innej kolejności niż zmiany statusu. Integracja musi rozpoznawać już przetworzone zdarzenia i nie może cofać zamówienia ze statusu „opłacone” do „oczekuje” tylko dlatego, że spóźniona notyfikacja przyszła po potwierdzeniu.

Ogólne zasady bezpiecznego odbierania takich powiadomień - weryfikację podpisu, szybką odpowiedź i kolejkę - opisujemy szerzej we wpisie webhooki w e-commerce - do czego służą i jak je wdrożyć.

Każda z bramek ma swoje mocne strony i nie zawsze wybór sprowadza się do jednej. Część sklepów prowadzi dwie bramki równolegle, np. lokalną dla BLIK-a i przelewów oraz Stripe dla klientów zagranicznych płacących kartami.

[#chart:wpr18b]

Zwroty i uzgadnianie wpłat przy integracji płatności

Zwrot to druga strona płatności i wymaga tej samej staranności. Wszystkie trzy bramki pozwalają zlecić zwrot przez API - w całości albo częściowo. Dobra integracja zleca zwrot z poziomu sklepu lub systemu obsługi zwrotów, zapisuje identyfikator zwrotu przy zamówieniu i zmienia status dopiero wtedy, gdy bramka potwierdzi wykonanie operacji. Ręczne zwroty w panelu bramki, o których sklep się nie dowiaduje, kończą się rozjazdem między stanem zamówień a pieniędzmi na koncie.

Uzgadnianie wpłat to sprawdzenie, czy pieniądze, które bramka przelała na konto firmowe, odpowiadają opłaconym zamówieniom. Bramki wypłacają środki zbiorczo i zwykle pomniejszone o prowizję, dlatego potrzebny jest raport rozliczeń - dostępny w panelu, a w części bramek także przez API. Na jego podstawie integracja dopasowuje każdą transakcję do zamówienia i wskazuje różnice.

• Zapisuj przy zamówieniu identyfikator transakcji z bramki, a nie tylko numer zamówienia.

• Prowizji bramki nie odejmuj od kwoty sprzedaży - to osobny koszt udokumentowany fakturą od operatora.

• Przy zwrotach częściowych zapisuj kwotę każdego zwrotu osobno.

• Raz dziennie porównuj zamówienia opłacone w sklepie z transakcjami w bramce i oznaczaj różnice.

Opłacone zamówienie zwykle uruchamia wystawienie dokumentu sprzedaży. Jak połączyć płatności z programem do fakturowania, piszemy w artykule integracja sklepu z Fakturownią, wFirmą i InFaktem.

Najczęstsze błędy przy integracji płatności online

Poniżej problemy, które powtarzają się najczęściej w sklepach, które trafiają do nas z prośbą o naprawę płatności. Większość z nich nie wymaga zmiany bramki - wystarczy poprawić obsługę powiadomień.

[#chart:wpr18c]

Gotowa wtyczka czy własna integracja płatności

Dla WooCommerce, Shopera, PrestaShop i Shopify bramki udostępniają gotowe moduły, a w Shoperze i Shopify część metod płatności konfiguruje się bezpośrednio w panelu platformy. W większości sklepów to najlepszy wybór: moduł jest utrzymywany przez operatora bramki, aktualizowany przy zmianach API i obsługuje notyfikacje. Rola programisty sprowadza się wtedy do poprawnej konfiguracji, testów i sprawdzenia, czy inne wtyczki nie zakłócają obsługi powiadomień, np. przez cache strony albo reguły zapory.

Własna integracja ma sens w kilku sytuacjach:

• sklep działa na systemie pisanym na zamówienie, dla którego nie ma modułów,

• płatności trzeba powiązać z nietypowym procesem, np. przedpłatą za zamówienie realizowane w częściach,

• zwroty i uzgadnianie wpłat mają działać automatycznie z poziomu ERP lub systemu obsługi zwrotów,

• sklep obsługuje kilka bramek i chce jednej warstwy, która ujednolica ich statusy.

Bezpieczeństwo danych kart a integracja płatności

Przy płatności przez przekierowanie na stronę bramki albo przez pola płatności osadzone przez bramkę, takie jak Stripe Elements, dane karty nie trafiają na serwer sklepu. To znacznie ogranicza zakres wymagań standardu PCI DSS po stronie sklepu. Dlatego przy własnych integracjach nie budujemy formularzy, które same przyjmują numer karty - zawsze korzystamy z mechanizmów dostarczonych przez bramkę. Klucze API przechowujemy poza kodem źródłowym, a do kluczy produkcyjnych dostęp mają tylko osoby, które naprawdę ich potrzebują.

Co przetestować przed uruchomieniem bramki płatności

Każda z trzech bramek ma środowisko testowe: Przelewy24 i PayU udostępniają sandbox, a Stripe tryb testowy z osobnymi kluczami. Testy na produkcji z prawdziwymi pieniędzmi to ostateczność. Przed uruchomieniem przejdź co najmniej te scenariusze:

[#checklista] Testy integracji płatności: płatność zakończona sukcesem i zmiana statusu zamówienia - płatność odrzucona lub porzucona - zamknięcie karty przed powrotem do sklepu (status musi zmienić się mimo to) - powtórzona notyfikacja (bez podwójnego maila i dokumentu) - notyfikacja z błędnym podpisem (musi zostać odrzucona) - zwrot pełny i częściowy - zmiana kwoty zamówienia po utworzeniu płatności - płatność w obcej walucie, jeśli ją obsługujesz - niedostępność serwera sklepu podczas notyfikacji.

Po uruchomieniu warto przez pierwsze dni codziennie porównywać zamówienia w sklepie z transakcjami w panelu bramki. Rozjazdy w pierwszym tygodniu zwykle pokazują błąd w konfiguracji, który łatwo poprawić, zanim urośnie do setek zamówień. Dobrze jest też ustawić powiadomienie, które informuje zespół, gdy przez określony czas nie przyszła żadna notyfikacja z bramki mimo nowych zamówień.

Jak Vinson pomaga przy integracji płatności online

Programiści Vinson konfigurują i wdrażają bramki Przelewy24, PayU i Stripe w sklepach na WooCommerce, Shoperze, PrestaShop i Shopify oraz piszą integracje płatności dla systemów tworzonych na zamówienie. Sprawdzamy obsługę notyfikacji i podpisów, naprawiamy zamówienia, które utykają w statusie oczekiwania na płatność, wdrażamy zwroty przez API i raporty uzgadniające wpłaty z zamówieniami. Pomagamy też połączyć płatności z programem do fakturowania lub ERP. Szczegóły współpracy znajdziesz na stronie Wsparcie programistyczne dla e-commerce.

Najczęściej zadawane pytania

Dlaczego zamówienie jest opłacone w bramce, a w sklepie ma status „oczekuje na płatność”?

Najczęściej notyfikacja z bramki nie dotarła do sklepu albo została odrzucona, np. przez błędną weryfikację podpisu, zaporę na serwerze lub zły adres powiadomień. W przypadku Przelewy24 przyczyną bywa też brak weryfikacji transakcji. Trzeba sprawdzić historię notyfikacji w panelu bramki i logi serwera sklepu.

Czy można korzystać z dwóch bramek płatności jednocześnie?

Tak, wiele sklepów tak robi, np. lokalna bramka dla BLIK-a i przelewów oraz Stripe dla płatności kartami z zagranicy. Każda bramka wymaga osobnej konfiguracji notyfikacji i osobnego uzgadniania wpłat. Przy zamówieniu trzeba zapisywać, którą bramką zostało opłacone.

Czym różni się integracja Stripe od Przelewy24 i PayU?

Stripe opiera się na obiektach PaymentIntent i webhookach z podpisem w nagłówku Stripe-Signature, a sklep nie musi dodatkowo potwierdzać transakcji. Przelewy24 wymaga weryfikacji transakcji po notyfikacji, a PayU - obsługi statusów i, przy wyłączonym automatycznym odbiorze, potwierdzenia płatności przez API.

Jak przetestować integrację płatności bez prawdziwych pieniędzy?

Przelewy24 i PayU mają środowiska sandbox, a Stripe tryb testowy z kluczami testowymi i testowymi numerami kart. Testy obejmują płatności udane, odrzucone, porzucone, powtórzone notyfikacje i zwroty. Dopiero po nich przełącza się integrację na dane produkcyjne.

Czy zwroty pieniędzy można zautomatyzować?

Tak, wszystkie trzy bramki pozwalają zlecać zwroty pełne i częściowe przez API. Sklep lub system obsługi zwrotów może zlecić zwrot po przyjęciu towaru na magazyn i zapisać jego identyfikator przy zamówieniu. Status zwrotu warto zmieniać dopiero po potwierdzeniu z bramki.

Integracja płatności online działa dobrze wtedy, gdy sklep ufa tylko zweryfikowanym powiadomieniom, obsługuje powtórzenia i regularnie uzgadnia wpłaty z zamówieniami. Jeśli chcesz sprawdzić lub poprawić płatności w swoim sklepie, zajrzyj na stronę wsparcie programistyczne Vinson. Po opłaceniu zamówienia klient dostaje maila z potwierdzeniem - o tym, jak zadbać o ich dostarczalność, piszemy we wpisie maile transakcyjne w sklepie - jak wybrać serwer SMTP.