API bramki płatności kryptowalutowych: faktury, webhooki, wypłaty i white label

Co robi API bramki płatności kryptowalutowych?

API ukrywa blockchain przed Twoim kodem. Zamiast prowadzić węzły, wyprowadzać adresy i liczyć potwierdzenia, wywołujesz endpoint tworzący fakturę, zapisujesz identyfikator bramki i czekasz na powiadomienia. Bramka podaje kurs wymiany, obserwuje sieci, stosuje screening AML i rozlicza środki na Twoje saldo.

Większość bramek udostępnia te same elementy pod różnymi nazwami: faktury lub zamówienia dla płatności przychodzących, IPN lub callbacki dla powiadomień, endpointy przewalutowania i salda oraz wypłaty lub wypłaty środków dla przelewów wychodzących. Sandboxy są u większości dostawców, na przykład osobny host sandbox w CoinGate i konto sandbox w NOWPayments, i należy z nich korzystać przed każdym testem w sieci głównej.

• API faktur: tworzenie, odczyt i anulowanie żądań płatności z ceną w walucie fiat, akceptowanymi monetami, numerem zamówienia i adresem callbacku
• Powiadomienia: webhooki lub IPN przy każdej zmianie statusu, zwykle podpisane
• API wypłat: wysyłanie krypto lub waluty fiat do klientów, partnerów albo na własny portfel
• Kursy i waluty: lista obsługiwanych monet, sieci, kwot minimalnych i bieżące wyceny
• Wtyczki i SDK: gotowe moduły dla platform e-commerce oparte na tym samym API

Jak wygląda cykl życia faktury?

Każda bramka ma własny model statusów, więc zmapuj je na niewielki zestaw wewnętrzny, zanim napiszesz logikę biznesową. Tylko końcowy status opłacenia powinien wydawać towar; statusy pośrednie istnieją, ponieważ transakcja bywa widoczna w blockchainie na długo przed tym, zanim można ją bezpiecznie przyjąć.

Tabela mapuje dwa opublikowane modele statusów na stany, których potrzebuje większość platform. CoinGate na przykład wygasza nieopłaconą fakturę po 20 minutach od wyboru monety przez klienta, a płatności oznaczone przez kontrole AML uznaje za nieważne.

Jak weryfikować webhooki i IPN kryptowalutowe?

Traktuj każde powiadomienie jako niezaufane, dopóki go nie zweryfikujesz. Bramki stosują różne schematy: NOWPayments podpisuje posortowane ciało JSON algorytmem HMAC-SHA512 i wysyła podpis w nagłówku x-nowpayments-sig, CoinGate wysyła token ustawiony przy zamówieniu, a BitPay zaleca pobranie faktury z API po każdym powiadomieniu zamiast ufać jego treści.

Najbezpieczniejszy wzorzec łączy oba podejścia: zweryfikuj podpis, a potem odczytaj fakturę z API i działaj na podstawie tej odpowiedzi. Kosztuje to jedno żądanie na zmianę statusu i chroni przed sfałszowanymi lub powtórzonymi callbackami.

• Weryfikuj podpisy porównaniem w stałym czasie i odrzucaj żądania bez podpisu
• Pobierz fakturę po identyfikatorze bramki, zanim zmienisz stan zamówienia
• Szybko zwracaj HTTP 200 i przetwarzaj asynchronicznie; bramki ponawiają przy błędach
• Zapisuj każde powiadomienie ze zdarzeniem lub statusem, aby ignorować duplikaty
• Nigdy nie ufaj kwotom ani walutom przesłanym w przekierowaniu przeglądarki

Jak obsłużyć niedopłaty, nadpłaty i płatności po terminie?

Portfele i giełdy potrącają opłaty za wypłatę, a klienci niedokładnie kopiują kwoty, więc nie można zakładać płatności co do grosza. Zdefiniuj tolerancję i regułę dla każdego przypadku przed startem i udostępnij wynik obsłudze klienta.

Jak działają idempotentność i uzgadnianie?

Twórz faktury z własnym numerem zamówienia i zadbaj, aby wywołanie można było bezpiecznie ponowić: jeśli żądanie przekroczy limit czasu, wyszukaj fakturę po numerze, zanim utworzysz kolejną, albo użyj klucza idempotentności, jeśli bramka go obsługuje. Ta sama zasada dotyczy wypłat, gdzie zduplikowane żądanie wysyła prawdziwe pieniądze dwa razy.

Do uzgadniania zapisuj identyfikator faktury w bramce, hash transakcji, kwotę fiat, kwotę krypto, kurs i prowizję. Raporty rozliczeniowe pokazują wypłaty jako partie, więc dopasowanie biegnie od zamówienia przez fakturę do wypłaty, a nie od zamówienia do pozycji na wyciągu bankowym.

Czego wymaga API wypłat w świetle Travel Rule?

Endpointy wypłat wysyłają krypto z salda w bramce na adres, często partiami dla prowizji afiliacyjnych, sprzedawców marketplace lub wypłat klientów. Większość wymaga białej listy adresów, zatwierdzenia dwuskładnikowego albo klucza API z osobnymi uprawnieniami do wypłat.

W UE rozporządzenie (UE) 2023/1113 wymaga, aby bramka przekazywała dane nadawcy i odbiorcy z każdym przelewem oraz weryfikowała własność portfeli prywatnych powyżej 1000 EUR. Spodziewaj się, że żądania wypłat będą zawierały nazwę odbiorcy i typ adresu, i zaplanuj przelewy, które czekają na te dane.

Jakie są opcje white label dla bramki płatności kryptowalutowych?

Platformy odsprzedające płatności własnym sprzedawcom często chcą mieć stronę płatności pod własną marką. Są trzy poziomy, a cena rośnie wraz z kontrolą. Plisio na przykład podaje 0,5% dla API i 1,5% dla white label, a NOWPayments sprzedaje osobny produkt white label.

Pełny white label przenosi nie tylko markę, ale i odpowiedzialność. Jeśli onboardujesz sprzedawców i przechowujesz ich salda, możesz potrzebować własnego zezwolenia MiCA; model sub-merchant u bramki z zezwoleniem pozostawia ten obowiązek po stronie bramki.

Jak połączyć API bramek kryptowalutowych przez OrsunPay?

OrsunPay ujednolica statusy, webhooki i zwroty bramek kryptowalutowych w jednym API obok Twoich dostawców kartowych i bankowych, na Twoich własnych kontach w bramkach. Nie przechowuje krypto i nie realizuje wypłat ze swojego salda; kieruje żądania do wybranej bramki i zwraca podpisane, pozbawione duplikatów zdarzenia.

Jak zintegrować API bramki płatności kryptowalutowych

1. Otwórz konta sandbox Utwórz konta sandbox i produkcyjne w bramce, wygeneruj osobne klucze API do faktur i wypłat oraz ustaw sekret IPN.
2. Zmapuj statusy Przełóż statusy bramki na własne stany wewnętrzne i zdecyduj, który z nich wydaje towar.
3. Twórz faktury idempotentnie Wyślij kwotę fiat, walutę, numer zamówienia i adres callbacku; przed ponowieniem wywołania po przekroczeniu czasu wyszukaj fakturę po numerze.
4. Weryfikuj powiadomienia Sprawdź podpis, pobierz fakturę z API i przetwórz zdarzenie dokładnie raz.
5. Obsłuż przypadki brzegowe Wdróż tolerancję, dopłatę, zwrot i wygaśnięcie oraz przetestuj każdy przypadek w sandboxie.
6. Uzgadniaj rozliczenia Zapisuj hash transakcji, kurs i prowizję dla każdej faktury i codziennie dopasowuj partie wypłat do zamówień.