Statische wallets

Statische wallets zijn permanente adressen voor het ontvangen van crypto-betalingen. Ze zijn gekoppeld aan een specifieke order_id en zijn uniek op de combinatie project_id + order_id + currency + network.

Gebruik statische wallets voor:

• Terugkerende stortingen van dezelfde gebruiker
• Langetermijn-betalingsadressen die op een gebruikersprofiel worden weergegeven
• Hoge volumes aan stortingen waarbij je een stabiel adres per gebruiker wilt

Statische wallet aanmaken

Verzoekparameters

Voorbeeld van een verzoek

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

Voorbeeld van een response

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

Walletinformatie

Haal informatie over een statische wallet op met uuid of address.

Verzoekparameters

Voorbeeld van een response

{
  "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 — som van alle stortingen die deze wallet heeft ontvangen, in currency.
• transactions_count — aantal tot nu toe ontvangen stortingen.
• qr — base64-gecodeerde QR data URI van het stortingsadres (altijd aanwezig voor statische wallets, het adres wordt bij het aanmaken toegewezen).

Walletlijst

Verzoekparameters

Voorbeeld van een response

{
  "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 inschakelen / uitschakelen

Schakel in of uit of een statische wallet nieuwe betalingen accepteert.

Verzoek

Beide endpoints nemen één enkele parameter:

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

Voorbeeld van een response

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

Voor enable is status "active" en luidt message "Static wallet enabled successfully".

Wallet-transacties

Haal een lijst op van alle stortingen die een statische wallet heeft ontvangen.

Verzoekparameters

Voorbeeld van een response

{
  "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 — platformfee die van deze storting is afgetrokken, in currency.
• net_amount — bedrag dat na de fee aan het merchantsaldo is toegevoegd.

Webhooks voor statische wallets

Wanneer er een betaling wordt ontvangen op een statische wallet, stuurt het systeem een webhook naar 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"
}

Veldreferentie

Best practices

• Unieke order_id — Gebruik een unieke order_id voor elke gebruiker of order
• Idempotentie — Controleer txid voordat je verwerkt om dubbele bijboekingen te voorkomen
• Verifieer handtekeningen — Verifieer ALTIJD de sign-handtekening voordat je geld bijboekt
• Gebruik merchant_amount — Boek gebruikers bij op basis van merchant_amount, niet payment_amount

Levenscyclus en idempotentie

Een statische portemonnee is een herbruikbare stortingsidentiteit, geen factuur. Het heeft geen verwacht bedrag en geen vervaldatum. Eén adres kan gedurende zijn levensduur een willekeurig aantal stortingstransacties genereren.

Aanmaak is idempotent voor hetzelfde handelaarproject, order_id, currency, en network: de bestaande portemonnee wordt geretourneerd. Houd die tuple stabiel en bewaar de geretourneerde portemonnee uuid; gebruik niet elke keer een nieuwe order_id wanneer dezelfde klant het stortingsscherm opent.

Idempotentie van stortingen verschilt van idempotentie van portemonnees:

• order_id identificeert de herbruikbare portemonnee/klantkoppeling;
• portemonnee uuid identificeert het permanente portemonneerecord;
• webhook uuid identificeert één gedetecteerde stortingstransactie;
• txid identificeert de on-chain overboeking en is de primaire deduplicatiesleutel voor het crediteren.

Gebruik een uniekheidsbeperking in de database voor de verwerkte chain/network/txid-identiteit en claim deze in dezelfde transactie die het interne saldo van de klant crediteert.

In- en uitschakelsemantiek inschakelen

Het uitschakelen van een wallet voorkomt dat de applicatie deze verwerkt als een actief stortingsdoel; het wist het adres of de geschiedenis ervan niet en kan een blockchain-overboeking die al door een gebruiker is verzonden, niet stoppen.

Het opnieuw inschakelen behoudt dezelfde wallet-identiteit en hetzelfde adres. Maak geen vervanging alleen om het label te wijzigen; labels zijn geen afwikkelingsidentificatoren.

Statische wallet-randgevallen

Reconciliatiemodel

Voer een periodieke taak uit die door /v1/static-wallet/transactions bladert, stortingen bijwerkt op txid, en hun merchant_amount, status en optioneel conversieresultaat vergelijkt met uw interne grootboek. Webhook-levering moet het reconciliëren snel maken, maar reconciliatie moet het volledig maken.