Integrację API płatniczego w B2B warto zrobić raz, a dobrze. Jeśli w zespole pojawia się presja: „zróbmy szybko, potem poprawimy”, lepiej zatrzymać się na moment – chyba że potem chcesz spędzić długie wieczory w logach z powodu reklamacji, rozjazdów w statusach albo dublowania księgowania Poniżej znajdziesz sposób wdrożenia, który zapewnia stabilność i bezpieczeństwo oraz wskazówki, jak uporać się z najczęstszymi wyzwaniami. Omówimy to na przykładzie REST API od PayU, które pozwala tworzyć zamówienia, pobierać ich stan oraz prowadzić integrację płatności w kontrolowany sposób także na sandboxie.
Integracja API PayU w skrócie
API płatnicze to interfejs komunikacji pomiędzy Twoją aplikacją a platformą płatności. W B2B najczęściej spina warstwę checkoutu z backendem rozliczeń (ERP/CRM, moduł fakturowania, raporty). PayU opisuje przepływy integracyjne w dokumentacji „payment flows” oraz w sekcji „get started”, gdzie widać podział na autoryzację, utworzenie zamówienia i obsługę dalszych etapów [2][3].
Decyzje przed integracją API płatniczego
Zanim weźmiesz się za implementację i testy, warto doprecyzować kilka spraw. Poniżej znajdziesz listę tematów, które realnie wpływają na stabilność integracji i łatwość utrzymania.
-
Źródło prawdy o zamówieniu. Gdzie ostatecznie ma się zgadzać stan płatności – w e-commerce czy w ERP? W B2B często najważniejszy jest backend rozliczeń.
-
Identyfikatory i korelacja logów. Ustalenie, jak mapować extOrderId (Twoje ID) oraz orderId (PayU), plus jeden wspólny identyfikator w logach aplikacji.
-
Środowiska i konfiguracja. Osobne dane dostępowe i endpointy dla sandboxa oraz produkcji. PayU rozdziela domeny secure.snd.payu.com (test) i secure.payu.com (produkcja) [3].
-
Obsługa wyjątków, czyli anulacje, ponowne wywołania, opóźnione potwierdzenia. Ten obszar zwykle generuje najwięcej błędów „po wdrożeniu”.
Integracja krok po kroku: OAuth → zamówienie → status
Poniższy schemat opisany w dokumentacji PayU dobrze działa jako „szkielet” implementacji. Szczegóły endpointów i przykłady requestów warto brać bezpośrednio z PayU Developer Guide [2] oraz referencji API [1].
-
Bezpieczne przechowywanie sekretów i konfiguracja POS.
Dane typu client_id i client_secret powinny żyć poza repozytorium. Wdrażając na kilku środowiskach, rozdziel konfiguracje i nie mieszaj tokenów pomiędzy testem a produkcją. -
Pobranie tokenu OAuth.
PayU opisuje autoryzację OAuth i sposób użycia tokenu w nagłówku Authorization: Bearer … [2]. OAuth 2.0 jako standard jest udokumentowany w RFC 6749, co pomaga przy debugowaniu błędów autoryzacji w integracjach serwer-serwer [6]. -
Utworzenie zamówienia (Create Order).
Tworzenie zamówienia odbywa się przez POST /api/v2_1/orders. Dokumentacja pokazuje adresy dla produkcji oraz sandboxa [3]. Na tym etapie pilnuj spójnego mapowania identyfikatorów oraz tego, co zapisujesz w bazie po stronie backendu: powiązania zamówienia, kwoty, waluty oraz stanu. -
Statusy i aktualizacja stanu po stronie systemu.
W produkcji liczy się jedno: stan płatności w Twoim systemie ma wynikać z wiarygodnych sygnałów, nie z tego, co widzi frontend. W dokumentacji PayU znajdziesz operacje pobierania danych zamówienia po orderId [2][1]. Dobrą praktyką jest idempotencja: to samo zdarzenie nie powinno ponownie księgować, zmieniać stanu magazynu ani generować kolejnej faktury. -
Testy na sandboxie i scenariusze brzegowe.
PayU udostępnia zasoby startowe w sekcji „APIs” (w tym narzędzia ułatwiające testy) [4]. Warto od razu przetestować: przerwanie płatności, błędne dane autoryzacji, ponowne wywołanie oraz opóźnione potwierdzenia.
Bezpieczeństwo w integracji API płatniczego
Bezpieczeństwo integracji API warto oprzeć o trzy filary:
-
szyfrowany transport,
-
kontrolę dostępu,
-
porządek w danych.
Po stronie PayU pomocne jest to, że dane kartowe mogą trafiać do hostowanej strony/formularza płatności PayU, co ogranicza zakres wrażliwych danych obsługiwanych przez system sprzedawcy. W dokumentacji PayU dla płatności kartowych opisano m.in. użycie hostowanego Secure Form i tokenizacji do bezpiecznego wykorzystania karty w przyszłych transakcjach.
Najczęstsze problemy podczas wdrożenia i ich rozwiązania
Problemy w płatnościach często związane są z konfiguracją, środowiskiem lub logiką statusów. Zacznij od krótkiej diagnostyki.
-
401/403 w API: sprawdź, czy token nie wygasł oraz czy pochodzi z tego samego środowiska, z którego jest endpoint [2][3].
-
Zamówienie utworzone, brak aktualizacji w systemie: dołóż mechanizm odświeżania statusu po stronie backendu i idempotencję operacji.
-
Działa na testach, psuje się na produkcji: zweryfikuj domeny secure.snd… vs secure… oraz zestaw danych dostępowych [3].
-
Rozjazdy w rozliczeniach: dopracuj mapowanie extOrderId ↔ orderId oraz logowanie korelacyjne w całym przepływie.
Gdzie i jak najszybciej znaleźć odpowiedzi? Gdzie i jak najszybciej znaleźć odpowiedzi?
Jeśli potrzebujesz jednego miejsca, od którego warto zaczynać integrację API płatniczego, może to być dokumentacja developerska PayU [5]. Referencja API [1] przydaje się, gdy implementujesz konkretną operację. Z kolei sekcje „get started” i „payment flows” prowadzą przez pełny przepływ integracji [2][3]. W sprawach formalnych pomocna jest strona „Documents to download”, gdzie PayU publikuje też aktualne dokumenty do pobrania [7]. Wsparcie i zgłoszenia znajdziesz też na portalu pomocy PayU [8].
Źródła:
-
https://developers.payu.com/europe/pl/docs/payment-flows/auth-and-order/
-
https://developers.payu.com/europe/pl/docs/get-started/integration-overview/accept-payment/
-
https://developers.payu.com/europe/pl/docs/get-started/integration-overview/accept-payment/
-
https://developers.payu.com/europe/pl/
-
https://datatracker.ietf.org/doc/html/rfc6749
- https://poland.payu.com/dokumenty-prawne-do-pobrania/
-
https://poland.support.payu.com/s/?language=pl
