Statische Wallets

Statische Wallets sind permanente Adressen für den Empfang von Kryptowährungs-Zahlungen. Sie sind mit einer bestimmten order_id verknüpft und eindeutig durch die Kombination aus project_id + order_id + currency + network.

Verwenden Sie statische Wallets für:

• Wiederkehrende Einzahlungen desselben Nutzers
• Langfristige Zahlungsadressen, die im Nutzerprofil angezeigt werden
• Einzahlungs-Workflows mit hohem Volumen, in denen Sie eine stabile Adresse pro Nutzer wünschen

Statische Wallet erstellen

Anfrageparameter

Anfragebeispiel

{
  "currency": "USDT",
  "network": "TRX-TRC20",
  "order_id": "USER-123",
  "label": "User deposit #123",
  "url_callback": "https://your-site.com/webhook/static"
}

Antwortbeispiel

{
  "state": 0,
  "result": {
    "uuid": "019b2265-34d8-7001-a230-8f97de90d481",
    "address": "TXYZabc123...",
    "currency": "USDT",
    "network": "TRX-TRC20",
    "label": "User deposit #123",
    "order_id": "USER-123",
    "status": "active",
    "url": "https://go.2328.io/static/019b2265-34d8-7001-a230-8f97de90d481",
    "created_at": "2026-01-20T12:00:00Z",
    "qr": "data:image/png;base64,iVBORw0..."
  }
}

Wallet-Informationen

Statische Wallet anhand von uuid oder address abrufen.

Anfrageparameter

Antwortbeispiel

{
  "state": 0,
  "result": {
    "uuid": "019b2265-34d8-7001-a230-8f97de90d481",
    "address": "TXYZabc123...",
    "currency": "USDT",
    "network": "TRX-TRC20",
    "status": "active",
    "total_received": "1250.50",
    "transactions_count": 3,
    "created_at": "2026-01-20T12:00:00Z",
    "qr": "data:image/png;base64,iVBORw0..."
  }
}

• total_received — Summe aller von dieser Wallet empfangenen Einzahlungen, in currency.
• transactions_count — Anzahl der bisher empfangenen Einzahlungen.
• qr — Base64-codierter QR-Data-URI der Einzahlungsadresse (für statische Wallets stets vorhanden, da die Adresse bei der Erstellung zugewiesen wird).

Wallet-Liste

Anfrageparameter

Antwortbeispiel

{
  "state": 0,
  "result": {
    "items": [
      {
        "uuid": "019b2265-...",
        "address": "TXYZabc123...",
        "currency": "USDT",
        "network": "TRX-TRC20",
        "status": "active",
        "total_received": "1250.50",
        "transactions_count": 3
      }
    ],
    "paginate": {
      "count": 1,
      "current_page": 1,
      "per_page": 20,
      "total": 1,
      "total_pages": 1,
      "has_more": false
    }
  }
}

Wallet aktivieren / deaktivieren

Schalten Sie um, ob eine statische Wallet neue Zahlungen entgegennimmt.

Anfrage

Beide Endpoints nehmen einen einzelnen Parameter entgegen:

{
  "uuid": "019b2265-34d8-7001-a230-8f97de90d481"
}

Antwortbeispiel

{
  "state": 0,
  "result": {
    "uuid": "019b2265-34d8-7001-a230-8f97de90d481",
    "status": "inactive",
    "message": "Static wallet disabled successfully"
  }
}

Bei enable lautet status "active" und message "Static wallet enabled successfully".

Wallet-Transaktionen

Liste aller von einer statischen Wallet empfangenen Einzahlungen abrufen.

Anfrageparameter

Antwortbeispiel

{
  "state": 0,
  "result": {
    "items": [
      {
        "uuid": "abc123-def456-...",
        "order_id": "USER-123",
        "amount": "100.00",
        "currency": "USDT",
        "payment_status": "paid",
        "txid": "0xabc123def456...",
        "fee_amount": "3.00",
        "net_amount": "97.00",
        "created_at": "2026-01-20T15:30:00Z"
      }
    ],
    "paginate": {
      "count": 1,
      "hasPages": true,
      "perPage": 15,
      "page": 1
    }
  }
}

• fee_amount — Plattformgebühr, die von dieser Einzahlung abgezogen wird, in currency.
• net_amount — Betrag, der nach Abzug der Gebühr dem Händlerguthaben gutgeschrieben wird.

Webhooks für statische Wallets

Wenn eine Zahlung auf einer statischen Wallet eingeht, sendet das System einen Webhook an url_callback.

Webhook-payload

{
  "uuid": "a28b293f-5c76-4053-8062-ae9ca4ab784b",
  "order_id": "USER-7666308594",
  "amount": "10.00000000",
  "currency": "USDT",
  "amount_usd": "10.00000000",
  "exchange_rate": "1.00000000",
  "payer_currency": "USDT",
  "payer_amount": "10.00000000",
  "network": "TRX-TRC20",
  "address": "TMU9Tgpchvgbywkbj5SdC8KJS73t5m3M7G",
  "payment_status": "paid",
  "txid": "8369ede26a0da05b1bae154b4bb4072eb2453db30ba86b21831902670929454f",
  "tx_explorer_url": "https://tronscan.org/#/transaction/8369ede26a0da05b1bae154b4bb4072eb2453db30ba86b21831902670929454f",
  "payment_amount": "10.00000000",
  "merchant_amount": "9.920000000000000000",
  "created_at": "2026-05-09T16:13:04+03:00",
  "sign": "dd958d1405febce670a9a196e9141784b9f2a5f39cd6d1832d6f3f68d0de1e10"
}

Feldreferenz

Best Practices

• Eindeutige order_id — Verwenden Sie für jeden Nutzer oder jede Bestellung eine eindeutige order_id
• Idempotenz — Prüfen Sie txid vor der Verarbeitung, um doppelte Gutschriften zu vermeiden
• Signaturen verifizieren — Verifizieren Sie IMMER die sign-Signatur, bevor Sie Mittel gutschreiben
• merchant_amount verwenden — Schreiben Sie Nutzern auf Basis von merchant_amount gut, nicht auf Basis von payment_amount

Lebenszyklus und idempotency

Ein static wallet ist eine wiederverwendbare Einzahlungsidentität, kein invoice. Er hat keinen erwarteten Betrag und kein Ablaufdatum. Eine Adresse kann im Laufe ihrer Existenz beliebig viele Einzahlungstransaktionen erzeugen.

Die Erstellung ist idempotent für dasselbe merchant Projekt, order_id, currency und network: das vorhandene Wallet wird zurückgegeben. Halten Sie dieses Tupel stabil und bewahren Sie das zurückgegebene Wallet uuid; verwenden Sie nicht jedes Mal ein neues order_id, wenn derselbe Kunde den Einzahlungsbildschirm öffnet.

Einzahlungs-idempotency ist anders als Wallet-idempotency:

• order_id identifiziert die wiederverwendbare Wallet/Kunden-Zuordnung;
• Wallet-uuid identifiziert den permanenten Wallet-Eintrag;
• webhook uuid identifiziert eine erkannte Einzahlungstransaktion;
• txid identifiziert die On-Chain-Übertragung und ist der primäre Deduplication-Schlüssel für die Gutschrift.

Verwenden Sie eine Datenbank-Eindeutigkeitsbeschränkung für die verarbeitete Kette/Netzwerk/txid-Identität und beanspruchen Sie diese in derselben Transaktion, die das interne Kontoguthaben des Kunden gutschreibt.

Semantik von Aktivieren und Deaktivieren

Das Deaktivieren eines Wallets verhindert, dass die Anwendung es als aktives Einzahlungziel verarbeitet; es löscht jedoch die Adresse oder deren Historie nicht und kann eine vom Benutzer bereits gesendete Blockchain-Übertragung nicht stoppen.

Das erneute Aktivieren bewahrt dieselbe Wallet-Identität und Adresse. Erstellen Sie keinen Ersatz lediglich, um das Label zu ändern; Labels sind keine settlement-Identifikatoren.

Edge-Cases von Static wallet

Reconciliation Modell

Führen Sie regelmäßig einen Job aus, der durch /v1/static-wallet/transactions blättert, Einzahlungen nach txid upsertet und deren merchant_amount, Status und optionales Konversionsergebnis mit Ihrem internen Hauptbuch vergleicht. Die Webhook Lieferung sollte reconciliation schnell machen, aber reconciliation muss sie vollständig machen.