PCI Proxy EU udostępnia dedykowane SDK dla najpopularniejszych języków programowania: Node.js, Python i PHP. Dzięki SDK, integracja tokenizacji w istniejącej aplikacji zajmuje godziny, nie tygodnie. Deweloperzy mogą skupić się na logice biznesowej, nie na zarządzaniu infrastrukturą PCI DSS – to zadanie SDK i vault PCI Proxy EU.
SDK PCI Proxy EU: struktura i uwierzytelnianie
SDK udostępnia klienta singleton, który inicjalizuje się za pomocą klucza API i środowiska (sandbox lub produkcja). Uwierzytelnianie odbywa się przez nagłówek Bearer przy każdym żądaniu HTTP do endpointów PCI Proxy EU. Klient automatycznie obsługuje ponawianie z exponential backoff przy błędach przejściowych (timeout, limit 429) i zgłasza typowane wyjątki przy błędach trwałych, takich jak token nieznaleziony lub wygasła karta.
Struktura pakietu odpowiada konwencjom każdego języka: moduły CommonJS/ESM dla Node.js, pakiet PyPI dla Pythona, pakiet Composer dla PHP. Każde wydanie jest podpisane i publikuje SBOM (Software Bill of Materials), co ułatwia zgodność z politykami bezpieczeństwa łańcucha dostaw. Changelog dokumentuje breaking change i aktualizacje wymagań PCI.
Tokenizacja w Node.js: praktyczny przykład
W backendzie Node.js z Express typowy przepływ polega na odebraniu tokenu wygenerowanego przez hosted field na froncie, wywołaniu metody client.charge(token, amount, currency) i obsłudze odpowiedzi. SDK zwraca ustrukturyzowany obiekt z wynikiem autoryzacji, identyfikatorem transakcji i metadanymi potrzebnymi do uzgodnienia. W przypadku odrzucenia odpowiedź zawiera kod odrzucenia ISO i zlokalizowany komunikat.
Dla płatności cyklicznych metoda client.detokenize(token) pobiera odniesienie do ważnego PAN na potrzeby pojedynczego obciążenia u procesora. Odniesienie jest jednorazowe i wygasa po kilku sekundach, co uniemożliwia ponowne użycie przez atakującego przechwytującego wywołanie. Deweloper nigdy nie otrzymuje PAN w postaci jawnej — otrzymuje wyłącznie tymczasowe odniesienie, którego proxy używa wewnętrznie.
Python i PHP: te same funkcje, ta sama prostota
SDK Pythona stosuje konwencje biblioteki requests i obsługuje zarówno użycie synchroniczne, jak i asynchroniczne przez asyncio. Inicjalizacja odbywa się przez PCIProxyClient(api_key=os.environ["PCI_PROXY_KEY"]), a wszystkie metody przyjmują natywne słowniki Pythona jako parametry. Obsługa błędów korzysta z wyjątków hierarchii PCIProxyError, z podklasami dla błędów uwierzytelniania, walidacji i sieci.
W PHP pakiet Composer automatycznie instaluje zależności Guzzle do wywołań HTTP. Klient korzysta z interfejsów PSR-7 i PSR-18, dzięki czemu jest kompatybilny z każdym frameworkiem zgodnym ze standardami PHP-FIG, od Laravel po Symfony. Metody są udokumentowane pełnym PHPDoc, a pakiet zawiera stuby typów dla IDE. W obu językach przejście z sandboxa do produkcji wymaga jedynie zmiany zmiennej środowiskowej z kluczem produkcyjnym.
Hosted fields i JavaScript SDK dla front-endu
Do integracji front-endowej PCI Proxy EU dostarcza JavaScript SDK do osadzenia hosted fields na stronie. Pola karty są hostowane na domenie PCI Proxy EU w izolowanym iFrame — Twoja strona nie ma dostępu do wartości wpisywanych przez użytkownika. Metoda pcip.mount() montuje pole w wybranym kontenerze, a pcip.tokenize() zwraca token bez przekazywania PAN przez Twój serwer.
Najczęściej zadawane pytania
Czy SDK jest open source?
Kod źródłowy SDK jest dostępny na GitHub na licencji MIT. Każdy może przejrzeć implementację, zgłosić problemy i proponować pull requesty. Rdzeń vault i szyfrowania pozostaje po stronie serwera PCI Proxy EU, ale kod klienta używany w aplikacji jest w pełni przejrzysty i audytowalny.
Jak obsługiwać błędy tokenizacji w SDK?
Każda metoda SDK może zgłaszać typowane wyjątki odpowiadające konkretnym kategoriom błędów. Błędy sieci i timeouty są automatycznie obsługiwane przez mechanizm ponawiania. Błędy semantyczne, takie jak nieprawidłowa karta lub wygasły token, są propagowane ze standaryzowanymi kodami i komunikatami, co pozwala zwrócić klientowi odpowiedni komunikat bez ujawniania szczegółów technicznych.
Czy SDK obsługuje detokenizację dla płatności cyklicznych?
Metoda detokenizacji jest zaprojektowana specjalnie dla płatności cyklicznych i subskrypcji. Token tworzy się raz podczas pierwszej płatności lub rejestracji karty, a następnie jest ponownie używany przy każdym kolejnym obciążeniu bez konieczności ponownego wprowadzania danych przez klienta. Token domyślnie nie wygasa, ale można skonfigurować jawną datę wygaśnięcia zgodnie z polityką firmy.
Gotowy na integrację SDK tokenizacji w swoim stacku? Skorzystaj z dokumentacji i sandboxa i przejdź do produkcji w kilka dni. Odkryj PCI Proxy EU.
Zacznij integrację – SDK dostępny dla sandbox od razu
Zarejestruj się w PCI Proxy EU i pobierz SDK dla swojego języka programowania. Integracja w godzinach.
Porozmawiaj z ekspertem