Statiska plånböcker

Statiska plånböcker är permanenta adresser för att ta emot kryptobetalningar. De är kopplade till ett specifikt order_id och är unika utifrån kombinationen project_id + order_id + currency + network.

Använd statiska plånböcker för:

• Återkommande insättningar från samma användare
• Långsiktiga betalningsadresser som visas i en användarprofil
• Inbetalningsflöden med hög volym där du vill ha en stabil adress per användare

Skapa statisk plånbok

Parametrar i förfrågan

Exempel på förfrågan

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

Exempel på svar

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

Plånboksinformation

Hämta information om en statisk plånbok via uuid eller address.

Parametrar i förfrågan

Exempel på svar

{
  "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 — summan av alla insättningar som tagits emot av denna plånbok, i currency.
• transactions_count — antal insättningar som mottagits hittills.
• qr — Base64-kodad QR data URI för inbetalningsadressen (alltid närvarande för statiska plånböcker, eftersom adressen tilldelas vid skapandet).

Plånbokslista

Parametrar i förfrågan

Exempel på svar

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

Aktivera / inaktivera plånbok

Växla om en statisk plånbok ska acceptera nya betalningar.

Förfrågan

Båda endpoints tar en enda parameter:

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

Exempel på svar

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

För enable är status "active" och message lyder "Static wallet enabled successfully".

Plånbokstransaktioner

Hämta en lista över alla insättningar som mottagits av en statisk plånbok.

Parametrar i förfrågan

Exempel på svar

{
  "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 — plattformsavgift som dragits från denna insättning, i currency.
• net_amount — belopp som krediterats handlarsaldot efter avgift.

Webhooks för statiska plånböcker

När en betalning tas emot på en statisk plånbok skickar systemet en webhook till 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"
}

Fältreferens

Bästa praxis

• Unikt order_id — Använd ett unikt order_id för varje användare eller order
• Idempotens — Kontrollera txid innan bearbetning för att undvika dubbla krediteringar
• Verifiera signaturer — Verifiera ALLTID sign-signaturen innan du krediterar medel
• Använd merchant_amount — Kreditera användare baserat på merchant_amount, inte payment_amount

Livscykel och idempotens

En statisk plånbok är en återanvändbar insättningsidentitet, inte en faktura. Den har inget förväntat belopp och ingen utgångstid. En adress kan generera ett obegränsat antal insättningstransaktioner under sin livstid.

Skapande är idempotent för samma handlareprojekt, order_id, currency och network: den befintliga plånboken returneras. Håll den tupeln stabil och spara den returnerade plånboken uuid; använd inte en ny order_id varje gång samma kund öppnar insättningsskärmen.

Idempotens för insättningar skiljer sig från idempotens för plånbok:

• order_id identifierar den återanvändbara plånbok/kund-mappningen;
• plånbok uuid identifierar den permanenta plånboksregistreringen;
• webhook uuid identifierar en upptäckt insättningstransaktion;
• txid identifierar on-chain-överföringen och är nyckeln för primär duplikathantering vid kreditering.

Använd en unikhetsbegränsning i databasen för den behandlade chain/network/txid-identiteten och kräva den i samma transaktion som krediterar kundens interna saldo.

Aktivera och inaktivera semantik

Att inaktivera en plånbok förhindrar att applikationen behandlar den som ett aktivt insättningsmål; det raderar inte adressen eller dess historik och kan inte stoppa en blockchain-överföring som redan skickats av en användare.

Återaktivering bevarar samma plånboksidentitet och adress. Skapa inte en ersättning enbart för att ändra etiketten; etiketter är inte uppgörelseidentifierare.

Statisk plånboks specialfall

Avstämningsmodell

Kör ett periodiskt jobb som bläddrar igenom /v1/static-wallet/transactions, uppdaterar insättningar efter txid och jämför deras merchant_amount, status och eventuellt konverteringsresultat med din interna huvudbok. Webhook-leverans bör göra avstämningen snabb, men avstämningen måste göra den fullständig.