Payment API

Payment API umożliwia tworzenie sesji płatności, przekierowywanie klientów do hostowanego checkoutu oraz śledzenie statusu płatności.

Utwórz płatność

{
  "state": 0,
  "result": {
    "uuid": "abc123-def456-...",
    "order_id": "ORDER-12345",
    "amount": "100.00",
    "currency": "USD",
    "amount_usd": "100.00",
    "exchange_rate": null,
    "url": "https://2328.io/pay/abc123-def456-...",
    "tg_deeplink": "https://t.me/my2328bot?start=pay_abc123-def456-...",
    "expires_at": "2026-01-11T21:00:00Z",
    "created_at": "2026-01-11T20:00:00Z",
    "payer_currency": "USDT",
    "payer_amount": "100.50",
    "network": "TRX-TRC20",
    "address": "TXYZabc123...",
    "payment_status": "check",
    "txid": null,
    "payment_amount": null,
    "qr": "data:image/png;base64,iVBORw0..."
  }
}

curl -X POST https://api.2328.io/api/v1/payment \
  -H "Content-Type: application/json" \
  -H "User-Agent: MyShop/1.0 (+https://myshop.example)" \
  -H "project: YOUR_PROJECT_UUID" \
  -H "sign: YOUR_HMAC_SIGNATURE"

Zarządzany koszyk, H2H i dokładne kwoty kryptowalut

Ten sam punkt końcowy obsługuje trzy różne typy faktur. Wybierz jeden celowo; nie mieszaj ich semantyki kwot.

Zarządzany koszyk z wyborem płatnika

Wyślij amount, currency, order_id i url_callback, ale pomiń to_currency i network. Odpowiedź zawiera result.url; address, qr i czasami pola płatnika pozostają null do momentu, gdy płatnik wybierze kierunek na zarządzanej stronie.

{
  "amount": "125.00",
  "currency": "EUR",
  "order_id": "ORDER-2026-1042",
  "url_callback": "https://merchant.example/webhooks/2328",
  "url_return": "https://merchant.example/orders/ORDER-2026-1042"
}

Faktura H2H o bezpośrednim adresie

Wyślij zarówno to_currency, jak i network. 2328.io tworzy fakturę blockchain podczas wywołania API, więc poprawna odpowiedź może być wyświetlona w Twoim procesie realizacji zamówienia bez przekierowywania klienta.

{
  "amount": "100.00",
  "currency": "USD",
  "to_currency": "USDT",
  "network": "TRX-TRC20",
  "order_id": "ORDER-2026-1043",
  "url_callback": "https://merchant.example/webhooks/2328"
}

Wyświetl te wartości dokładnie tak, jak zostały zwrócone:

• payer_amount i payer_currency — instrukcja płatności;
• network i address — jedyne miejsce docelowe dla tej faktury;
• qr — URI danych dla tego samego adresu;
• expires_at — termin płatności faktury;
• url — przydatna hostowana alternatywa, gdy niestandardowy proces realizacji zamówienia nie może zostać zakończony.

Faktura za dokładną kwotę kryptowaluty

Umieść kryptowalutę w currency, gdy sama faktura jest denominowana w kryptowalucie:

{
  "amount": "25.000000",
  "currency": "USDT",
  "network": "TRX-TRC20",
  "order_id": "ORDER-2026-1044",
  "url_callback": "https://merchant.example/webhooks/2328"
}

Żądana wartość kryptowaluty jest zachowana w payer_currency / payer_amount. Usługa może również wewnętrznie utrzymywać wycenę w USD dla celów księgowych i pól kursów; nie zastępuj dokładnej instrukcji dotyczącej kryptowaluty tą wyceną. Zachowaj zwrócone ciągi dziesiętne, w tym końcową precyzję.

Dla kryptowaluty z tylko jedną obsługiwaną siecią, sieć może być wybierana automatycznie. Zaleca się jednak podanie network w sposób jawny dla deterministycznej integracji. Dla aktywów wielosieciowych, takich jak stablecoiny, zawsze należy go wysyłać.

Idempotencja i ponawianie prób

order_id jest przypisane do uwierzytelnionego projektu handlowca i działa jako klucz idempotencji tworzenia. Jeśli płatność już istnieje, API zwraca tę sesję z state: 0.

Zalecany algorytm tworzenia:

1. Wstaw lokalną próbę płatności i unikalny order_id w jednej transakcji bazy danych.
2. Wyślij podpisane żądanie API.
3. Zachowaj zwrócony uuid oraz pełną odpowiedź.
4. Jeśli wynik HTTP zostanie utracony, ponów identyczne żądanie lub zapytaj /v1/payment/info przez order_id.
5. Nigdy nie twórz drugiego lokalnego zamówienia tylko dlatego, że żądanie z górnego poziomu czasu oczekiwania wygasło.

Edge cases płatności

Adres URL zwrotny przeglądarki służy wyłącznie do nawigacji. Klient może go otworzyć bez płacenia, zamknąć po dokonaniu płatności lub odtworzyć go później. Tylko zweryfikowany stan API/webhook może rozliczyć zamówienie sprzedawcy.

Informacje o płatności

curl -X POST https://api.2328.io/api/v1/payment/info \
  -H "Content-Type: application/json" \
  -H "User-Agent: MyShop/1.0 (+https://myshop.example)" \
  -H "project: YOUR_PROJECT_UUID" \
  -H "sign: YOUR_HMAC_SIGNATURE"

Lista płatności

curl -X POST https://api.2328.io/api/v1/payment/list \
  -H "Content-Type: application/json" \
  -H "User-Agent: MyShop/1.0 (+https://myshop.example)" \
  -H "project: YOUR_PROJECT_UUID" \
  -H "sign: YOUR_HMAC_SIGNATURE"