Wprowadzenie/Informacje ogólne

Informacje ogólne

Specyfikacja techniczna integracji przetwarzania płatności kryptowalutowych i wypłat z 2328.io.

Witamy w dokumentacji API 2328.io. Niniejsza dokumentacja referencyjna opisuje, jak zintegrować przetwarzanie płatności kryptowalutowych oraz wypłat z Państwa aplikacją.

Pierwsze kroki

Aby rozpocząć integrację:

Załóż konto sprzedawcy oraz projekt na 2328.io
Pobierz project UUID oraz API key z ustawień projektu
Wygeneruj osobny Payout API key, jeśli planujesz korzystać z wypłat
Zapoznaj się z sekcją Authentication, aby dowiedzieć się, jak podpisywać żądania
Wykonaj swoje pierwsze wywołanie Create Payment

Bazowy URL

Wszystkie produkcyjne żądania API korzystają z następującego bazowego URL:

Text

https://api.2328.io/api

Wszystkie żądania muszą być wykonywane przez HTTPS. Żądania bez HTTPS są blokowane.

Co możesz robić

Za pomocą API 2328.io możesz:

Akceptować płatności kryptowalutowe — twórz sesje płatności i przekierowuj klientów do hostowanego checkoutu lub Telegram MiniApp
Wypłacać środki — programowo wysyłaj wypłaty z salda sprzedawcy na dowolny adres blockchain
Sprawdzanie sald — zobacz salda kont merchanta dla każdej waluty, ekwiwalenty w USD i kwoty zablokowane przez AML
Korzystać ze statycznych portfeli — generuj trwałe adresy depozytowe powiązane z użytkownikiem lub zamówieniem
Pobierać kursy walutowe — uzyskuj kursy w czasie rzeczywistym dla par fiat i kryptowalut
Otrzymywać webhooki — natychmiast otrzymuj powiadomienia o zmianie statusu płatności

Limity zapytań

API pozwala na maksymalnie 10 żądań na sekundę na projekt. Żądania przekraczające limit otrzymują odpowiedź HTTP 429 Too Many Requests — zastosuj wycofanie i spróbuj ponownie.

Wybierz odpowiedni wzorzec integracji

Wymaganie	Zalecany wzorzec	Dlaczego
Pozwól klientowi wybrać, jak zapłacić	Hostowana kasa	Utwórz płatność i przekieruj do `result.url`; 2328.io prezentuje obecnie dostępne kierunki.
Pozwól klientowi pozostać w Twojej własnej kasie	Faktura z bezpośrednim adresem H2H	Wyślij `to_currency` i `network` podczas tworzenia płatności; wyświetl otrzymane `address`, `payer_amount` i `qr`.
Pobierz dokładnie `25 USDT` lub `0.001 BTC`	Faktura denominowana w kryptowalutach	Umieść kryptowalutę w `currency` i dokładną kwotę dziesiętną w `amount`.
Nadaj każdemu użytkownikowi wielokrotnego użytku adres depozytowy	Statyczny portfel	Adres jest stały i może odbierać wiele niezależnych depozytów.
Normalizuj przychodzące aktywa do jednej waluty bilansowej	Automatyczne przekonwertowanie	Skonfiguruj zasady projektu w panelu sterowania i wykorzystaj wynik `convert` po zakończeniu konwersji.
Wymień istniejący bilans sprzedawcy	Konwersja ręczna	Podgląd z `/v1/convert/price`, następnie wykonaj z `/v1/convert`
Wyślij środki na adres blockchain	Wypłata	Użyj osobnego klucza API do wypłat, najpierw dokonaj obliczeń, a następnie uzgodnij status wypłaty.

Hosted checkout i H2H to dwie formy prezentacji tego samego API płatności. H2H nie tworzy słabszej ani niepodpisanej płatności: backend nadal tworzy fakturę, 2328.io nadal posiada adres i status, a podpisane webhooki pozostają wiążące dla rozliczenia.

Nienaruszalne właściwości integracji

Te zasady dotyczą każdej integracji produkcyjnej:

Backend only — trzymaj klucze API z dala od przeglądarek, aplikacji mobilnych, logów, analiz i zrzutów ekranu wsparcia.
Decimal strings — wysyłaj i przechowuj pieniądze jako ciągi znaków. Nigdy nie zaokrąglaj kryptowalut ani kursów wymiany przy użyciu binarnej arytmetyki zmiennoprzecinkowej.
Immutable idempotency keys — wygeneruj order_id przed pierwszym żądaniem i zachowaj pełne żądanie z nim. Ponowna próba z tym samym order_id może zwrócić oryginalny obiekt zamiast stosować zmienione pola.
Webhook-first settlement — przekierowania, odpytywanie przez klienta, hashe transakcji dostarczone przez użytkowników i limity czasu HTTP nie są dowodem płatności.
Verify, deduplicate, then mutate — zweryfikuj HMAC, atomowo zgłoś rekord idempotencji, zaktualizuj zamówienie/saldo raz i szybko zwróć HTTP 200.
Reconciliation — okresowo sprawdzaj status płatności, portfela statycznego i wypłat, aby utracony webhook nie powodował trwałych niezgodności.
Dynamic availability — waliduj pary waluta/sieć za pomocą /v1/directions; obsługiwany aktyw nadal może mieć tymczasowo wyłączony jeden kierunek wpłaty lub wypłaty.
Explicit status policy — zdecyduj, jak Twój produkt obsługuje częściową płatność, nadpłatę, wygaśnięcie, blokadę AML, awaryjną konwersję i niejednoznaczne przekroczenia czasu w górnym strumieniu przed uruchomieniem.

Zalecane dane do przechowywania

Dla płatności przechowuj co najmniej uuid, order_id, oryginalną treść żądania, amount, currency, payer_currency, payer_amount, network, address, expires_at, najnowsze payment_status, txid, payment_amount, merchant_amount, opcjonalny blok convert oraz surowy zweryfikowany ładunek webhooka.

Dla portfeli statycznych, przechowuj portfel uuid, adres, walutę, sieć, referencję klienta/konta, status i adres URL wywołania zwrotnego oddzielnie od zapisów wpłat. Każda wpłata wymaga własnej transakcji uuid, txid, statusu, otrzymanej kwoty, kwoty dla sprzedawcy i wyniku konwersji.