Poznaj przebieg płatności i wymagania
Jeśli chcesz dowiedzieć się, jak przyjmować płatności kryptowalutami na stronie internetowej Next.js i jak dodać płatności kryptowalutowe do Next.js, zacznij od poznania przebiegu płatności, a nie od pisania kodu. Proces płatności kryptowalutą składa się zwykle z 4 etapów: utworzenia zamówienia, wyświetlenia prośby o płatność, monitorowania blockchaina i oznaczenia zamówienia jako opłaconego dopiero po weryfikacji.
Brzmi prosto. W praktyce rzadko takie jest.
„Przyjmowanie kryptowalut” na stronie Next.js nie oznacza, że sama aplikacja przechowuje monety. W większości przypadków strona tworzy prośbę o płatność dla klienta, klient wysyła środki ze swojego portfela, a operator płatności lub Twój backend potwierdza przelew. Dobry proces płatności powinien też uwzględniać limit czasu, bo kurs atrakcyjny o 10:00 może już nie być korzystny 20 minut później.
Musisz też zdecydować, jakie sieci i aktywa będziesz obsługiwać. Sklep przyjmujący USDT w sieciach Ethereum, Polygon i BNB Chain działa inaczej niż strona przyjmująca wyłącznie BTC w jednej sieci. Wybór sieci wpływa na opłaty, czas potwierdzenia i rodzaj portfela potrzebnego klientowi. Jeśli klient wybierze niewłaściwą sieć, płatność może trafić w miejsce, w którym nie uda Ci się przypisać jej do zamówienia.
Warto sprawdzić jedną praktyczną rzecz: czy nowy klient może sfinalizować płatność w mniej niż 2 minuty? Jeśli nie, proces wymaga usprawnień. Jeden portfel, jedna kwota, jeden czytelny adres i jedna jasna strona ze statusem płatności. Takiej przejrzystości oczekują klienci.
Wybierz operatora płatności kryptowalutowych lub integrację z portfelem
Płatności kryptowalutowe możesz wdrożyć na 3 sposoby. Pierwszy to strona płatności udostępniana przez operatora. Drugi — bezpośrednia integracja z portfelem, w której aplikacja korzysta z biblioteki portfela. Trzeci to bramka płatnicza pośrednicząca między użytkownikiem a blockchainem. Każde rozwiązanie wymaga innego nakładu pracy, a wybór zależy od tego, czy ważniejsza jest szybkość wdrożenia, kontrola, czy jedno i drugie.
Stronę płatności operatora zwykle najłatwiej szybko uruchomić. Tworzysz fakturę, przekierowujesz klienta na gotową stronę, a operator wykrywa płatność. Bezpośrednia integracja z portfelem może lepiej pasować do Twojego produktu, ale zwykle wymaga więcej kodu, obsługi dodatkowych przypadków i większej odpowiedzialności za potwierdzanie płatności. Bramka pośredniczy w transakcji i często jest praktycznym wyborem w handlu elektronicznym, bo może tworzyć faktury, śledzić potwierdzenia i wysyłać webhooki. Dla projektu Next.js bramka płatności kryptowalutowych dla Next.js może uprościć obsługę tych etapów, jeśli oferuje potrzebne aktywa i sieci.
Przed wyborem sprawdź 5 rzeczy: obsługiwane monety, obsługiwane sieci, obsługę webhooków, termin ważności faktur oraz to, ile kodu po stronie backendu musisz napisać. Jeśli porównujesz rozwiązania dla sklepu, poradnik o bramce płatności kryptowalutowych dla e-commerce będzie dobrym punktem wyjścia, bo przedstawia tę samą decyzję z perspektywy sprzedawcy. Freelancer wystawiający faktury klientom może bardziej potrzebować faktur i linków do płatności niż sklep internetowy — dlatego warto też spojrzeć na temat bramek płatności kryptowalutowych dla freelancerów.
Mała uwaga: jeśli operator deklaruje obsługę „wszystkich najważniejszych aktywów”, poproś o dokładną listę. „Wszystkie” to nieprecyzyjne określenie. „BTC, ETH i USDC w 3 sieciach” to konkret, na podstawie którego można podjąć decyzję.
Przygotuj projekt Next.js do obsługi płatności
Zacznij od przejrzystej struktury aplikacji. W projekcie Next.js korzystającym z App Routera umieść logikę płatności w trasach lub akcjach serwerowych, a klucze tajne trzymaj poza kodem klienta. Prosty układ może obejmować 1 stronę produktu, 1 formularz płatności, 1 trasę API do tworzenia faktur i 1 trasę webhooka do obsługi zdarzeń płatniczych.
W zmiennych środowiskowych umieść tajny klucz operatora płatności, klucz webhooka oraz publiczne wartości API, które można udostępnić w przeglądarce. Nie umieszczaj tajnego klucza w komponencie klienckim. Taki błąd może narazić całe konto na problemy, a jego szybkie naprawienie bywa kosztowne.
Jeśli operator udostępnia SDK, instaluj je wyłącznie w warstwie serwerowej. Możesz też korzystać ze zwykłych endpointów HTTP. Najważniejsza zasada pozostaje taka sama: przeglądarka prosi backend Next.js o utworzenie prośby o płatność, a backend komunikuje się z operatorem. Przeglądarka nigdy nie powinna samodzielnie decydować, że zamówienie zostało opłacone.
W przypadku zespołów przechodzących z płatności kartą struktura niewiele różni się od procesu opartego na Stripe — zmieniają się głównie etapy weryfikacji. Jeśli takie porównanie Ci pomoże, przeczytaj, jak przejść ze Stripe na bramkę płatności kryptowalutowych, zanim zaplanujesz trasy API. W prototypie wystarczy jedna trasa API; po dodaniu ponowień, zwrotów i historii statusów zamówienia lepiej sprawdzą się 3 lub 4 trasy.
Stwórz interfejs płatności w Next.js
Interfejs płatności może mieć formę karty produktu, strony koszyka albo prostego przycisku rozpoczynającego płatność. W klienckim komponencie Next.js przycisk zwykle wysyła szczegóły zamówienia do trasy serwerowej, czeka na odpowiedź, a następnie przekierowuje klienta lub wyświetla instrukcje dotyczące portfela.
Ogranicz liczbę pól w formularzu. Zwykle wystarczą nazwa produktu, kwota, adres e-mail i ewentualnie uwagi do zamówienia. Jeśli poprosisz o wypełnienie 9 pól, więcej osób zrezygnuje. Przy 3 polach klienci szybciej sfinalizują zakup. Proces płatności trwający 30 sekund wydaje się wygodniejszy niż taki, który zajmuje 3 minuty, nawet jeśli oba kończą się taką samą płatnością.
Opis przycisku płatności powinien jasno określać działanie: „Zapłać kryptowalutą”. Nie używaj „Dalej” ani „Kontynuuj” — takie etykiety nie wyjaśniają, co czeka użytkownika w kolejnym kroku. Po kliknięciu przycisku wywołaj backend, pobierz dane płatności, a następnie wyświetl w tym samym widoku adres portfela, kod QR i kwotę.
Warto podczas ładowania instrukcji płatności pozostawić widoczne podsumowanie zamówienia. Klient widzi wtedy konkretny produkt i dokładną kwotę w jednym miejscu. To zmniejsza ryzyko pomyłki, gdy cena jest ustalona w USD, ale płatność odbywa się w aktywie o zmiennym kursie.
Generuj adresy płatności, faktury lub linki do płatności
Każde zamówienie powinno być powiązane z 1 unikalną prośbą o płatność. Może to być adres portfela, link do płatności lub obiekt faktury utworzony przez operatora. Ponowne używanie tego samego adresu dla wszystkich klientów utrudnia rozliczanie i może generować niepotrzebne zgłoszenia do obsługi klienta.
W małym sklepie możesz generować nowy adres dla każdego zamówienia i zapisywać w bazie danych adres, oczekiwaną kwotę, aktywo oraz termin ważności. W przypadku integracji z operatorem możesz zamiast tego otrzymać identyfikator faktury i link do strony płatności. W obu przypadkach powiąż prośbę o płatność z identyfikatorem zamówienia, zanim ją wyświetlisz klientowi.
Wyświetl szczegóły w czytelnej formie: aktywo, sieć, kwotę i adres odbiorcy. Kod QR jest pomocny, ale nie powinien zastępować tekstu. Niektóre portfele słabo skanują kody QR, a część użytkowników woli kopiować i wklejać dane ręcznie. Czytelny adres to dodatkowe zabezpieczenie.
Jeśli potrzebujesz obsługi płatności na wskazany adres za usługi lub faktury, podobne rozwiązania opisano w artykule o bramkach płatności kryptowalutowych dla freelancerów. Link do płatności jest często wygodniejszy przy jednorazowych zamówieniach, a osobny rekord faktury lepiej się sprawdzi, gdy potrzebujesz historii płatności i przypomnień. Tak zaprojektowana integracja płatności kryptowalut w sklepie internetowym ułatwia powiązanie każdej wpłaty z właściwym zamówieniem.
Potwierdzaj płatności w blockchainie i aktualizuj status zamówienia
Przy potwierdzaniu płatności wiele zespołów popełnia błędy. Nie oznaczaj zamówienia jako opłaconego, gdy portfel pokazuje przelew oczekujący. Nie ufaj samej przeglądarce. Backend powinien weryfikować transakcję bezpośrednio w blockchainie lub otrzymać podpisany webhook od operatora płatności.
Typowy proces jest prosty. Operator wykrywa płatność i wysyła webhook do trasy Next.js, a serwer weryfikuje jego podpis, zanim zmieni status zamówienia. Jeśli samodzielnie wdrażasz ten etap, musisz sprawdzić hash transakcji, adres odbiorcy, aktywo, kwotę i liczbę potwierdzeń wymaganą przez Twoją politykę. Płatność może wyglądać na prawdziwą, zanim zostanie ostatecznie zatwierdzona.
Korzystaj z modelu zamówienia obejmującego 3 stany: oczekujące, potwierdzone i opłacone. „Oczekujące” oznacza, że prośba o płatność została utworzona. „Potwierdzone” — że płatność jest widoczna w blockchainie i uzyskała wymaganą liczbę potwierdzeń. „Opłacone” — że aplikacja zaktualizowała realizację zamówienia lub dostęp do usługi. Rozdziel te stany, żeby pracownik obsługi wiedział, czy klient czeka, czy płatność została zweryfikowana, czy zamówienie już zrealizowano.
Jeśli korzystasz z webhooków, zawsze weryfikuj ich podpisy. Artykuł o tym, jak weryfikować podpisane webhooki Payora, przyda się nawet wtedy, gdy nie korzystasz z PHP, bo podstawowa zasada jest taka sama: odrzucaj wiadomości, które nie potwierdzają, że pochodzą od operatora. Taka weryfikacja może skutecznie zablokować fałszywe powiadomienia o opłaceniu zamówienia.
Obsłuż sytuacje wyjątkowe, zadbaj o bezpieczeństwo i przeprowadź testy
Płatności kryptowalutowe mogą nie powieść się na więcej sposobów niż płatności kartą. Wycena może stracić ważność. Klient może wysłać środki w niewłaściwej sieci. W portfelu może zabraknąć niewielkiej części kwoty. Przeglądarka może odświeżyć się w połowie procesu. Każda z tych sytuacji wymaga odpowiedniej reakcji i wskazania użytkownikowi 1 kolejnego kroku.
Nie pozostawiaj wygasłych wycen bez wyjaśnienia. Jeśli link do płatności jest ważny przez 15 minut, wyświetlaj wyraźne odliczanie i po upływie tego czasu utwórz nową prośbę o płatność. W przypadku przelewów wysłanych w niewłaściwej sieci zapewnij możliwość kontaktu z obsługą, bo środki mogą być w blockchainie, ale nie tam, gdzie oczekuje ich aplikacja. Niedopłatę można zaakceptować, odrzucić albo skierować do ręcznej weryfikacji — zasady określ przed uruchomieniem usługi, a nie po pierwszej skardze.
Bezpieczeństwo jest obowiązkowe. Przechowuj tajne klucze w zmiennych środowiskowych dostępnych wyłącznie po stronie serwera. Weryfikuj podpisy webhooków. Zapisuj tylko niezbędne dane płatności. Jeśli logujesz identyfikatory transakcji, maskuj wszystkie poufne informacje, których nie potrzebujesz do debugowania. Przed obsługą prawdziwych płatności testuj rozwiązanie w sieci testowej lub za pomocą narzędzi sandbox operatora. Praktyczną listę kontrolną znajdziesz w artykule o tym, jak przetestować płatność kryptowalutową, zanim podłączysz prawdziwy portfel.
Pamiętaj też o zduplikowanych zdarzeniach. Niektórzy operatorzy ponawiają wysyłanie webhooków, a jeśli nie zachowasz ostrożności, blockchain może sprawić, że ta sama płatność zostanie zarejestrowana w systemie więcej niż raz. Kod aktualizujący zamówienie powinien być idempotentny, czyli to samo zdarzenie nie może dwukrotnie oznaczyć tego samego zamówienia jako opłaconego. To proste zabezpieczenie pozwala zaoszczędzić wiele godzin pracy.
Uruchom płatności, monitoruj je i ulepszaj proces zakupowy
Wdrożenie Next.js na Vercel lub podobnej platformie hostingowej zwykle przebiega bez problemów, ale elementy związane z płatnościami nadal wymagają uwagi. Upewnij się, że endpoint webhooka jest publicznie dostępny, zmienne środowiskowe są ustawione w środowisku produkcyjnym, a kompilacja nie zależy od wartości dostępnych wyłącznie lokalnie. Trasa płatności, która działa na Twoim komputerze, ale zawodzi na produkcji, to klasyczny błąd.
Logowanie zdarzeń ma tu duże znaczenie. Rejestruj tworzenie faktury, odbiór webhooka, wyniki weryfikacji i zmiany statusu. Zapisuj wystarczająco dużo szczegółów, by prześledzić całe zamówienie od początku do końca, ale nie umieszczaj w logach tajnych danych. Jeśli klient mówi, że zapłacił o 14:32, znalezienie odpowiadającego zdarzenia powinno zająć sekundy, a nie godziny.
Niewielkie zmiany w interfejsie mogą znacząco ułatwić płatność. Wyświetl kwotę dwa razy: w podsumowaniu zamówienia i w sekcji płatności. Po załadowaniu faktury nie ukrywaj przycisku płatności. Dodaj przycisk kopiowania obok adresu. Jasno pokaż etap potwierdzania, bo użytkownicy często odświeżają stronę podczas oczekiwania. Gdy strona milczy, aktualizacja statusu co 5 sekund może się dłużyć jak 5 minut.
Najwięcej pracy nie wymaga pierwsza płatność, lecz druga, trzecia i ta, która zawiedzie na styku portfela, blockchaina i backendu Next.js. Jeśli Twój system sprawnie obsłuży te 3 przypadki, klienci będą mogli zaufać procesowi płatności.
Comments