Payment API

Mit der Payment API können Sie Zahlungssitzungen erstellen, Kunden auf eine gehostete Checkout-Seite weiterleiten und den Zahlungsstatus verfolgen.

Zahlung erstellen

{
  "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"

Hosted checkout, H2H und genaue Krypto-Beträge

Dasselbe Endpunkt unterstützt drei verschiedene invoice-Formen. Wählen Sie eine bewusst; mischen Sie nicht deren Mengenbedeutungen.

Hosted checkout mit Zahlerwahl

Senden Sie amount, currency, order_id und url_callback, aber lassen Sie to_currency und network weg. Die Antwort enthält result.url; address, qr und manchmal Zahlerfelder bleiben null, bis der Zahler auf der gehosteten Seite eine Richtung auswählt.

{
  "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"
}

Direktadresse H2H invoice

Senden Sie sowohl to_currency als auch network. 2328.io erstellt die Blockchain invoice während API call, sodass eine erfolgreiche Antwort innerhalb Ihres Checkouts gerendert werden kann, ohne den Kunden umzuleiten.

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

Geben Sie diese Werte genau so wieder, wie sie zurückgegeben werden:

• payer_amount und payer_currency — die Zahlungsanweisung;
• network und address — das einzige Ziel für dieses invoice;
• qr — eine Daten-URI für dieselbe Adresse;
• expires_at — die invoice-Frist;
• url — ein nützliches gehostetes fallback, wenn der benutzerdefinierte Checkout nicht abgeschlossen werden kann.

Invoice für einen genauen Krypto-Betrag

Setzen Sie die Kryptowährung in currency, wenn das invoice selbst in Krypto denominiert ist:

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

Der angeforderte Krypto-Wert wird in payer_currency / payer_amount beibehalten. Der Service kann auch eine USD-Bewertung intern für Buchhaltungs- und Kursfelder verwalten; ersetzen Sie die genaue Krypto-Anweisung nicht durch diese Bewertung. Bewahren Sie zurückgegebene Dezimalzeichenfolgen einschließlich nachgestellter Genauigkeit.

Bei einer Kryptowährung mit nur einem unterstützten Netzwerk kann das Netzwerk automatisch ausgewählt werden. Es wird trotzdem empfohlen, network explizit anzugeben, um eine deterministische Integration zu gewährleisten. Für Multi-Netzwerk-Assets wie Stablecoins senden Sie sie immer.

Idempotency und retries

order_id ist auf das authentifizierte merchant-Projekt beschränkt und fungiert als Erstellungs-idempotency-Schlüssel. Wenn eine Zahlung bereits existiert, gibt die API diese Sitzung mit state: 0 zurück.

Empfohlener Erstellungsalgorithmus:

1. Fügen Sie Ihren lokalen Zahlungsversuch und eindeutiges order_id in einer Datenbanktransaktion ein.
2. Senden Sie die unterzeichnete API-Anfrage.
3. Speichern Sie die zurückgegebene uuid und die vollständige Antwort.
4. Wenn das HTTP-Ergebnis verloren geht, retry die identische Anfrage oder fragen Sie /v1/payment/info über order_id ab.
5. Erstellen Sie niemals eine zweite lokale Bestellung nur weil die Upstream-Anfrage abgelaufen ist.

Zahlungs-Sonderfälle

Die Rückkehr-URL des Browsers dient nur der Navigation. Ein Kunde kann sie ohne Zahlung öffnen, nach der Zahlung schließen oder später erneut aufrufen. Nur ein verifizierter API-/webhook-Status kann die merchant-Bestellung abschließen.

Zahlungsinformationen

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"

Zahlungsliste

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"