Klucz API do płatności działa jak karta bankomatowa bez PIN-u. Każdy, kto go przedstawi, może tworzyć faktury, odczytywać dane o płatnościach i – jeśli korzystasz z wypłat – przenosić środki z Twojego salda. Bezpieczeństwo API płatności sprowadza się zatem do trzech nawyków: przechowywania klucza na własnych serwerach, zezwalania API na przyjmowanie go wyłącznie z adresów tych serwerów oraz potwierdzania każdego webhooka przez odczytanie płatności przed podjęciem działania.
Ten przewodnik jest przeznaczony dla kierowników zespołów inżynieryjnych i szefów działów płatności w PSP, EMI, bankach i u sprzedawców, którzy podłączają API płatności kryptowalutami rozliczane w euro. Pokazuje, jak ograniczyć klucz za pomocą adresu IP i zakresu CIDR, gdzie powinien być przechowywany, jak weryfikować webhooki oraz jakie kontrole należy stosować wokół wypłat. Przykłady wykorzystują API i panel ItisPay (dane demonstracyjne).
Najważniejsze momenty
W skrócie
- Klucz API to poświadczenie na okaziciela. GitGuardian odnotował w 2025 roku 28,65 mln nowych zakodowanych na stałe sekretów w publicznych commitach na GitHubie, dlatego planuj na wypadek wycieku klucza, a nie tylko na jego zabezpieczenie.
- Lista dozwolonych adresów IP sprawia, że wyciekły klucz jest bezużyteczny poza Twoją siecią. Wpisz najmniejsze zakresy IPv4 lub IPv6, które obejmują Twoje rzeczywiste adresy wychodzące; pusta lista pozwala na każdy adres.
- Webhook to powiadomienie, a nie dowód. Przed wysłaniem towaru lub zaksięgowaniem wpłaty na koncie ponownie odczytaj fakturę po jej ID, używając swojego klucza.
- Wypłaty wymagają ludzkich kontroli po Twojej stronie: logowania dwuetapowego, zapisanych odbiorców IBAN i portfeli oraz drugiego zatwierdzającego powyżej ustalonej kwoty.
Dlaczego wyciek klucza API do płatności jest tak niebezpieczny?#
Wyciek klucza API do płatności jest niebezpieczny, ponieważ klucz stanowi całą tożsamość Twojej integracji. API ItisPay, podobnie jak większość API płatności, uwierzytelnia każde żądanie jednym nagłówkiem, Api-key, a to samo uwierzytelnienie obejmuje faktury, wypłaty na IBAN lub portfel oraz wypłaty kryptowalut na zewnętrzny adres. Dlatego dokumentacja wymaga, aby klucz „nie był ujawniany w kodzie po stronie klienta ani w publicznych repozytoriach”.
W praktyce klucze wyciekają przez zwyczajne miejsca: kod, logi i czaty. Według raportu GitGuardian „State of Secrets Sprawl 2026” (marzec 2026) w 2025 roku do publicznych commitów na GitHubie dodano 28,65 mln nowych zakodowanych na stałe sekretów, czyli o 34% więcej niż rok wcześniej. Gdy GitGuardian ponownie przetestował sekrety, które wyciekły w 2022 roku, ponad 64% wciąż było ważnych w styczniu 2026 roku. Zespoły publikują klucze, a potem zapominają je wymienić.
OWASP API Security Top 10 (2023) plasuje „Broken Authentication” na drugim miejscu i ostrzega, że „mechanizm uwierzytelniania jest łatwym celem dla atakujących, ponieważ jest dostępny dla wszystkich”. Raport Verizon „2025 Data Breach Investigations Report” wskazuje nadużycie poświadczeń jako najczęstszy początkowy wektor ataku, na poziomie 22%. Sam ciąg znaków to słaba obrona, dlatego pozostała część przewodnika dodaje warstwy, które nadal działają, gdy ciąg wyjdzie na jaw.
Jak lista dozwolonych adresów IP chroni klucz API?#
Lista dozwolonych adresów IP, nazywana czasem białą listą IP, chroni klucz, wiążąc go z miejscami, a nie tylko z ciągiem znaków. API przyjmuje klucz wyłącznie wtedy, gdy żądanie pochodzi z adresu, który wpisałeś; kopia klucza na laptopie dewelopera, w logu CI czy na stronie do wklejania tekstu nie zadziała.
W panelu ItisPay ustawienie znajduje się w sekcji Projekty, następnie Ustawienia, potem Bezpieczeństwo, w polu Dozwolone adresy IP API. Pole przyjmuje listę oddzieloną przecinkami, złożoną z pojedynczych adresów i bloków CIDR. Jego tekst pomocniczy brzmi: „Pozostaw puste, aby zezwolić na wszystkie adresy IP. Obsługiwane są zarówno IPv4, jak i IPv6.” Tę samą listę można ustawić przy tworzeniu projektu przez API, w polu api_allowed_ips, a nieprawidłowy wpis, taki jak 256.256.256.256, zostaje odrzucony z błędem walidacji zamiast zapisany.
Pusta wartość domyślna ma znaczenie. Nowy projekt przyjmuje klucz z dowolnego miejsca, dopóki ktoś nie wypełni pola, więc ten krok umieść na liście rzeczy do zrobienia przed uruchomieniem produkcyjnym, a nie na liście porządków na później. Wartości demonstracyjne na zrzucie ekranu, 203.0.113.10 i 198.51.100.0/24, pochodzą z zakresów zarezerwowanych przez RFC 5737 do celów dokumentacyjnych; Twoja lista będzie zawierać Twoje własne publiczne adresy. Każdy projekt ma własny 64-znakowy klucz i własną listę, więc produkcja może być zablokowana dla dwóch lub trzech serwerów, podczas gdy projekt testowy przyjmuje szerszy zestaw.
Jak zapisywać zakresy CIDR dla IPv4 i IPv6?#
Zapisz najmniejszy zakres, który obejmuje każdy adres, z którego Twoje serwery faktycznie łączą się z API. Większość problemów z listami dozwolonych adresów wynika z zakresu zbyt szerokiego albo z zapomnianej ścieżki wychodzącej.
Odczytywanie prefiksu#
Blok CIDR to adres, po którym następuje ukośnik i długość prefiksu. RFC 4632 definiuje długość prefiksu jako liczbę znaczących bitów: 192.168.99.0/24 ustala pierwsze 24 bity i pozostawia 8 wolnych, co daje 256 adresów. Każdy bit odjęty od prefiksu podwaja blok. /32 to jeden adres IPv4, /29 to 8, /24 to 256, a /16 to 65 536.
IPv6 działa podobnie, na 128 bitach. /128 to jeden adres. RFC 4291 ustala część interfejsową większości adresów IPv6 na 64 bity, więc sieć serwera to zwykle /64, a host może zmieniać swój adres w jej obrębie, na przykład gdy system operacyjny generuje tymczasowe adresy. Jeśli adres IPv6 Twojego hosta się zmienia, a ten /64 należy wyłącznie do Ciebie, wpisz /64 zamiast pojedynczego /128. Zakres dokumentacyjny dla przykładów IPv6 to 2001:db8::/32 (RFC 3849), więc nigdy nie kopiuj go do rzeczywistej listy dozwolonych adresów.
Ustalanie rzeczywistego adresu wychodzącego#
Liczy się adres, który widzi API, a nie ten, który serwer podaje o sobie. Za bramą NAT w chmurze lub za korporacyjną zaporą sieciową wiele maszyn dzieli jeden lub dwa publiczne adresy. Funkcje serverless często wychodzą z puli współdzielonej, chyba że kierujesz je przez stały egress. Sprawdzaj z każdego środowiska, wywołując usługę typu „jaki jest mój IP”, lub odczytaj adres źródłowy z logów zapory sieciowej, a następnie wpisz dokładnie ten adres.
| Konfiguracja | Co wpisać na listę | Ocena |
|---|---|---|
| Jeden serwer ze statycznym publicznym adresem IPv4 | Ten adres jako /32 lub bez maski | Działa |
| Kilka serwerów za chmurową bramką NAT | Publiczne adresy bramki NAT | Działa |
| Host IPv6 o zmieniających się adresach | /64 hosta, jeśli nikt inny go nie używa | Zależy |
| Sieć biurowa do testów ręcznych | Stały adres biura, jeśli dostawca to gwarantuje | Zależy |
| Funkcje serverless bez stałego adresu wyjściowego | Najpierw skieruj je przez bramkę NAT ze statycznym adresem | Nie |
| Cała regionalna pula adresów dostawcy chmury | Nic; obejmuje także innych klientów | Nie |
Zanim zapiszesz zmianę, najpierw dodaj nowy adres, wdróż zmianę, upewnij się, że ruch przepływa, i dopiero wtedy usuń stary. Zapisanie listy, która pomija Twoje działające serwery, zablokuje własny checkout.
Gdzie powinien znajdować się klucz API i kto go widzi?#
Klucz powinien znajdować się na Twoich serwerach, w magazynie sekretów, i nigdzie indziej. Nigdy nie umieszczaj go w przeglądarce ani w aplikacji mobilnej, ponieważ każdy może go tam odczytać. Trzymaj go też z dala od adresów URL: OWASP REST Security Cheat Sheet ostrzega, że klucz w URL może zostać przechwycony w logach serwera WWW. Strona płatności komunikuje się z Twoim zapleczem; zaplecze komunikuje się z API płatności.
Wczytuj klucz z menedżera sekretów lub zmiennych środowiskowych podczas uruchamiania, a nie z pliku konfiguracyjnego w repozytorium. Jeśli kod hostujesz na GitHubie, włącz ochronę przy wypychaniu (push protection): według dokumentacji GitHub, gdy wykryje potencjalny sekret podczas próby wypchnięcia, „zablokuje wypychanie”.
Używaj jednego klucza na środowisko. Każdy projekt ItisPay ma własny klucz i listę dozwolonych adresów, więc osobne projekty dla produkcji i stagingu oznaczają, że wyciekły klucz stagingowy nie może dotknąć płatności na żywo. Ogranicz liczbę osób, które widzą klucz produkcyjny. Wytyczne Europejskiego Urzędu Nadzoru Bankowego (EBA) z 2019 r. dotyczące bezpieczeństwa ICT ustanawiają zasadę dostępu „need-to-know” z „minimalnymi prawami dostępu”, także dla użytkowników technicznych; od 2025 r. Akt o operacyjnej odporności cyfrowej (DORA) nakłada ten obowiązek na większość firm płatniczych.
Następnie zapisz, jak wymienisz klucz, zanim zajdzie taka potrzeba. OWASP Cryptographic Storage Cheat Sheet zaleca rotację kluczy po określonym czasie oraz zawsze, gdy podejrzewasz kompromitację, a także zapewnienie, że „kod i procesy potrzebne do rotacji klucza są gotowe, zanim będą wymagane”.
Jak weryfikować webhooki z API płatności?#
Traktuj webhook jako powiadomienie, że coś się zmieniło, nigdy jako dowód, że zapłacono Ci. Każdy, kto pozna Twój adres callback, może wysłać na niego fałszywą wiadomość „zakończono”. Bezpieczny wzorzec to odczytanie faktury z API za pomocą własnego klucza i działanie na podstawie tego, co zwróci API.
Gdy tworzysz fakturę w ItisPay, pole callback_url określa adres, pod który wysyłane są aktualizacje statusu. Gdy przychodzi webhook, pobierz z niego identyfikator faktury, wywołaj GET na tej fakturze po ID i zrealizuj zamówienie lub zaksięguj płatność tylko wtedy, gdy odpowiedź pokazuje spodziewany status i kwotę, którą wyceniłeś. Dokumentacja opisuje ten endpoint jako zwracający status płatności i szczegóły blockchain „do wyświetlenia użytkownikom lub weryfikacji”.
Kilka zasad utrzymuje obsługę w czystości:
- Przyjmuj webhooki wyłącznie przez HTTPS i odrzucaj zwykłe HTTP.
- Uczyń obsługę idempotentną. Zapisuj identyfikator faktury i status każdego przetworzonego zdarzenia i pomijaj powtórzenia, ponieważ dostawcy wysyłają powiadomienia ponownie.
- Odpowiadaj szybko, a pracę wykonuj w kolejce, aby wolna baza danych nie wywoływała ponownych prób.
- Jeśli dostawca podpisuje webhooki za pomocą HMAC, czyli skrótu z kluczem zdefiniowanego w RFC 2104, przelicz podpis i porównaj go funkcją o stałym czasie. OWASP Webhook Security Cheat Sheet jest stanowczy: „Nigdy nie używaj ==: wycieka informacje o czasie i może zamienić endpoint w wyrocznię podpisów.” Odrzucaj wiadomości, których podpisany znacznik czasu jest zbyt stary.
Testuj przed startem produkcyjnym. ItisPay udostępnia endpoint, który symuluje zmianę statusu dla prawdziwej faktury testowej, oraz drugi, który ponownie wysyła ostatni webhook dla faktury lub identyfikatora zamówienia, dzięki czemu możesz sprawdzić ponowne próby i duplikaty bez prawdziwych pieniędzy.
Jak zabezpieczyć wypłaty i dostęp do panelu?#
Wypłaty to miejsce, w którym skradziony klucz przekłada się na utratę pieniędzy, dlatego otocz je kontrolami wykonywanymi przez ludzi. Przez endpoint wypłat ItisPay wypłata w walucie fiat trafia na IBAN beneficjenta, a wypłata kryptowalutowa na adres portfela, obie z Twojego dostępnego salda. API wykonuje to, o co poproszono; ocena, czy żądanie jest uprawnione, należy do Ciebie.
Kontrole, które działają po Twojej stronie:
- Logowanie dwuetapowe dla wszystkich z dostępem do panelu lub wypłat. Prawo płatnicze UE już stosuje tę ideę wobec użytkowników płatności: przepisy PSD2 o silnym uwierzytelnianiu klienta wymagają co najmniej dwóch niezależnych elementów z kategorii wiedzy, posiadania i cech własnych (inherencji). Stosuj ten sam standard wobec własnego personelu.
- Zapisani beneficjenci. Prowadź własną listę zatwierdzonych numerów IBAN i adresów portfeli, a usługa wypłat niech wysyła środki wyłącznie na pozycje z tej listy. Nowy beneficjent przechodzi osobne zatwierdzenie, najlepiej z okresem oczekiwania (cooling-off).
- Drugi zatwierdzający powyżej progu. Jedna osoba przygotowuje, druga zatwierdza. Ustaw kwotę zgodnie z własnym apetytem na ryzyko.
- Oddzielna usługa wypłat. Uruchamiaj wypłaty z jednej usługi z własnym stałym adresem na liście dozwolonych, oddzielonej od serwerów checkoutu, które tworzą faktury.
| Zabezpieczenie | Co powstrzymuje | Ocena |
|---|---|---|
| Lista dozwolonych adresów IP dla klucza | Użycie wyciekłego klucza spoza Twojej sieci | Działa |
| Klucz tylko na serwerze | Kradzież klucza z przeglądarek, aplikacji i repozytoriów | Działa |
| Ponowne odczytanie faktury po webhooku | Fałszywe powiadomienia „opłacono” | Działa |
| Zapisani odbiorcy i drugi zatwierdzający | Wypłaty na IBAN lub portfel atakującego | Działa |
| Każde z tych zabezpieczeń osobno wobec przejętego serwera znajdującego się na liście | Kradzież przez osobę, która już jest w środku | Nie |
Czego DORA i PCI DSS oczekują od dostępu do API?#
Jeśli jesteś regulowaną firmą finansową w UE, te zabezpieczenia nie są opcjonalnymi dodatkami. Rozporządzenie w sprawie cyfrowej odporności operacyjnej (DORA, rozporządzenie (UE) 2022/2554) ma zastosowanie od 17 stycznia 2025 r., według EBA. Jego art. 9 wymaga od firm, by „wdrożyły polityki ograniczające dostęp fizyczny lub logiczny” do aktywów ICT oraz by „wdrożyły polityki i protokoły dotyczące silnych mechanizmów uwierzytelniania”. Klucz dopuszczony na liście, dostępny tylko na serwerze, z planem rotacji, to rodzaj dowodu, o jaki pyta audytor.
PCI DSS obejmuje dane kart, a nie faktury kryptowalutowe. Jeśli ten sam zespół prowadzi także płatności kartami, wymaganie 8.4.2 wymaga uwierzytelniania wieloskładnikowego przy każdym dostępie do środowiska danych posiadacza karty, a wymagania wersji 4.0 o odroczonym terminie stosowania stały się obowiązkowe 31 marca 2025 r.
Gdzie zabezpieczenia API do płatności przestają działać?#
Te zabezpieczenia zawężają drogi wejścia. Same w sobie nie czynią integracji bezpieczną. Nawet w przypadku nadawców webhooków arkusz OWASP dotyczący webhooków nazywa listę dozwolonych adresów IP „tylko dodatkową warstwą”, ponieważ „współdzielony adres wyjściowy IP nie jest dowodem tożsamości”.
Gdzie to nie pomaga
- Przejęty serwer znajdujący się na liście. Atakujący wysyła żądania z zaufanego adresu, używając prawdziwego klucza.
- Współdzielone adresy wyjściowe. Jeśli inni najemcy wychodzą do chmury z tego samego adresu NAT, lista nie odróżni ich od Ciebie.
- Skradzione hasło do panelu bez logowania dwuetapowego. Atakujący w ogóle pomija API.
- Dane osobowe w polach faktury. Publiczny endpoint faktur ItisPay zwraca pełne dane otwartych faktur bez klucza, dlatego trzymaj nazwiska klientów i adresy e-mail poza nazwą zamówienia.
Jak w jedno popołudnie uruchomić bezpieczną integrację?#
Część techniczną bezpiecznej integracji można ukończyć w jedno popołudnie, jeśli trzymasz się ustalonej kolejności. Poniższe kroki dotyczą ItisPay; ta sama kolejność sprawdzi się u dowolnego dostawcy.
- Utwórz projekt testowy i osobny projekt produkcyjny, każdy z własnym kluczem.
- Przechowuj oba klucze w menedżerze sekretów i wczytuj je wyłącznie na serwerze.
- Ustal publiczny adres wyjściowy każdego środowiska i wpisz go w polu API Allowed IPs.
- Utwórz fakturę z back-endu: wyślij POST na https://api.itispay.com/api/v1/invoices z nagłówkiem Api-key, unikalnym order_id, fiat_amount z fiat_currency EUR, kryptowalutą w polu currency oraz swoim callback_url.
- Zbuduj obsługę webhooka: wyłącznie HTTPS, idempotentną, ponownie odczytującą fakturę po ID przed każdym działaniem.
- Uruchom symulację webhooka dla każdego obsługiwanego statusu, a następnie endpoint ponownego wysłania, aby przetestować duplikaty.
- Włącz wypłaty na końcu, z zapisanymi odbiorcami i drugim zatwierdzającym.
Na szybki start asystent Ask AI w panelu na życzenie napisze przykładowy kod, na przykład wywołanie tworzenia faktury w Node.js z już ustawionym nagłówkiem Api-key. Traktuj go jako szkic: przed wdrożeniem sprawdź nazwy pól w dokumentacji API, ponieważ wiążąca jest dokumentacja, a nie wygenerowany przykład. ItisPay publikuje też oficjalnego klienta TypeScript w npm: @itispay/typescript-client.
Jeśli wdrażasz to w szerszej konfiguracji orkiestracji płatności, każdy dostawca powinien mieć własny klucz, listę dozwolonych adresów i obsługę webhooków. Ten sam rekord, ponownie odczytywany po ID, zasila także uzgadnianie płatności kryptowalutowych dla Twojego zespołu finansowego.
Jeśli chcesz przyjmować płatności stablecoinami i otrzymywać euro bez samodzielnego budowania całego stosu, ItisPay zapewnia API, fakturowanie, webhooki i uzgadnianie oraz pierwszą warstwę bezpieczeństwa API do płatności: klucze, które możesz ograniczyć do własnych adresów IP. Licencjonowanie, KYC i rozliczenia na Twój IBAN realizuje nasz partner, licencjonowany w UE dostawca usług w zakresie kryptoaktywów (CASP) oraz instytucja płatnicza. Większość zespołów przechodzi od KYB do pierwszej transakcji w mniej niż tydzień.
Ten artykuł ma wyłącznie charakter informacyjny i nie stanowi porady prawnej ani regulacyjnej.
