Statik Cüzdanlar

Statik cüzdanlar, kripto para ödemeleri almak için kalıcı adreslerdir. Belirli bir order_id'ye bağlıdırlar ve project_id + order_id + currency + network kombinasyonuyla benzersizdirler.

Statik cüzdanları şunlar için kullanın:

• Aynı kullanıcıdan tekrarlayan yatırımlar
• Bir kullanıcı profilinde gösterilen uzun vadeli ödeme adresleri
• Kullanıcı başına stabil bir adres istediğiniz yüksek hacimli yatırım akışları

Statik cüzdan oluştur

İstek parametreleri

İstek örneği

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

Yanıt örneği

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

Cüzdan bilgisi

Statik cüzdan bilgisini uuid veya address ile alın.

İstek parametreleri

Yanıt örneği

{
  "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 — bu cüzdan tarafından alınan tüm yatırımların toplamı, currency cinsinden.
• transactions_count — şu ana kadar alınan yatırım sayısı.
• qr — yatırma adresinin Base64 ile encode edilmiş QR data URI'si (statik cüzdanlar için her zaman mevcuttur, adres oluşturma sırasında atanır).

Cüzdan listesi

İstek parametreleri

Yanıt örneği

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

Cüzdanı etkinleştir / devre dışı bırak

Bir statik cüzdanın yeni ödemeleri kabul edip etmeyeceğini değiştirin.

İstek

Her iki endpoint de tek bir parametre alır:

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

Yanıt örneği

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

enable için status "active"'tir ve message "Static wallet enabled successfully" olarak okunur.

Cüzdan işlemleri

Bir statik cüzdan tarafından alınan tüm yatırımların listesini alın.

İstek parametreleri

Yanıt örneği

{
  "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 — bu yatırımdan düşülen platform ücreti, currency cinsinden.
• net_amount — ücret düşüldükten sonra merchant bakiyesine yansıtılan tutar.

Statik cüzdan webhook'ları

Bir statik cüzdana ödeme alındığında, sistem url_callback adresine bir webhook gönderir.

Webhook payload'u

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

Alan referansı

En iyi uygulamalar

• Benzersiz order_id — Her kullanıcı veya sipariş için benzersiz bir order_id kullanın
• Idempotency — Yinelenen alacaklandırmaları önlemek için işlemden önce txid'yi kontrol edin
• İmzaları doğrulayın — Fonları alacaklandırmadan önce HER ZAMAN sign imzasını doğrulayın
• merchant_amount kullanın — Kullanıcıları payment_amount'a değil, merchant_amount'a göre alacaklandırın

Yaşam döngüsü ve idempotency

Bir static wallet yeniden kullanılabilir bir depozit kimliğidir, invoice değil. Beklenen bir miktarı ve son kullanma tarihi yok. Bir adres, ömrü boyunca herhangi sayıda mevduat işlemi gerçekleştirebilir.

Aynı merchant projesi için oluşturulma idempotent olarak kullanılır: order_id, currency ve network: mevcut cüzdan geri döner. O tuple'ı sabit tutun ve geri dönen cüzdanı uuid'da tutun; Aynı müşteri depozito ekranını her açtığında yeni bir order_id kullanmayın.

Yatırma idempotency cüzdandan idempotency]'dan farklıdır:

• order_id yeniden kullanılabilir cüzdan/müşteri eşlemesini belirler;
• cüzdan uuid kalıcı cüzdan kaydını tanımlar;
• webhook uuid tespit edilen bir depozito işlemini tespit eder;
• txid zincir içi transferi tanımlar ve kredi için birincil deduplication anahtarıdır.

İşlenen zincir/ağ/txid kimliği için veritabanı benzersizliği kısıtlaması kullanın ve müşterinin iç bakiyesini krediye alan aynı işlemde talep edin.

Semantik etkinleştir ve devre dışı bırak

Bir cüzdanı devre dışı bırakmak, uygulamanın onu aktif bir depozito hedefi olarak işlemesini engeller; Adresi veya geçmişini silmez ve bir kullanıcı tarafından zaten gönderilen blok zinciri transferini durduramaz.

Yeniden etkinleştirmek aynı cüzdan kimliğini ve adresini korur. Sadece etiketi değiştirmek için bir yedek oluşturma; Etiketler settlement tanımlayıcı değildir.

Static wallet Uç durumlar

Reconciliation modeli

/v1/static-wallet/transactions üzerinden sayfa sayfa geçen, txid ile yatırmaları güncelleyen ve bunların merchant_amount, durumu ve isteğe bağlı dönüşüm sonucunu iç defterinle karşılaştıran periyodik bir iş çalıştır. Webhook teslimi reconciliation'yi hızlı yapmalı, ama reconciliation tamamlayıcı olmalı.