# स्टैटिक वॉलेट

> किसी विशिष्ट order या user से जुड़े स्थायी deposit address, recurring और लंबी अवधि के भुगतानों के लिए perfect।

स्टैटिक वॉलेट क्रिप्टोकरेंसी भुगतान प्राप्त करने के लिए स्थायी address हैं। ये एक विशिष्ट `order_id` से linked होते हैं और `project_id + order_id + currency + network` के संयोजन से unique होते हैं।

स्टैटिक वॉलेट का उपयोग करें इन कामों के लिए:

- एक ही user से recurring deposit
- User profile पर दिखाए गए लंबी अवधि के payment address
- High-volume deposit flows जहाँ आप प्रति user एक स्थिर address चाहते हैं

## स्टैटिक वॉलेट बनाएँ

`POST /v1/static-wallet`

### Request parameters

| Field | Type | आवश्यक | Description |
|-------|------|----------|-------------|
| `currency` | string | हाँ | क्रिप्टोकरेंसी (USDT, BTC, ETH, इत्यादि) |
| `network` | string | हाँ | Network code |
| `order_id` | string | हाँ | आपका order/user ID (अधिकतम 255 chars) |
| `label` | string | नहीं | वॉलेट label (अधिकतम 255 chars) |
| `url_callback` | string | हाँ | webhook notifications के लिए URL |
| `invite_code` | string | नहीं | Referrer code |

### Request example

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

### Response example

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

## वॉलेट जानकारी

`uuid` या `address` से स्टैटिक वॉलेट जानकारी प्राप्त करें।

`POST /v1/static-wallet/info`

### Request parameters

| Field | Type | आवश्यक | Description |
|-------|------|----------|-------------|
| `uuid` | string | हाँ* | स्टैटिक वॉलेट UUID |
| `address` | string | हाँ* | Blockchain वॉलेट address |

> **INFO:** `uuid` या `address` में से कम से कम एक आवश्यक है।

### Response example

```json
{
  "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` — `currency` में, इस वॉलेट द्वारा प्राप्त सभी deposits का योग।
- `transactions_count` — अब तक प्राप्त deposits की संख्या।
- `qr` — deposit address का Base64-encoded QR data URI (स्टैटिक वॉलेट के लिए हमेशा उपस्थित, address creation पर assigned होता है)।

## वॉलेट सूची

`POST /v1/static-wallet/list`

### Request parameters

| Field | Type | आवश्यक | Description |
|-------|------|----------|-------------|
| `status` | string | नहीं | status के अनुसार filter (`active`, `inactive`) |
| `currency` | string | नहीं | currency के अनुसार filter |
| `network` | string | नहीं | network के अनुसार filter |
| `order_id` | string | नहीं | order_id के अनुसार filter |
| `page` | int | नहीं | Page संख्या (default: 1) |
| `per_page` | int | नहीं | प्रति page items (default: 20, अधिकतम: 100) |

### Response example

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

## वॉलेट enable / disable करें

टॉगल करें कि स्टैटिक वॉलेट नए भुगतान स्वीकार करता है या नहीं।

`POST /v1/static-wallet/disable`

`POST /v1/static-wallet/enable`

### Request

दोनों endpoints एक single parameter लेते हैं:

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

### Response example

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

`enable` के लिए, `status` `"active"` होता है और `message` `"Static wallet enabled successfully"` पढ़ता है।

## वॉलेट transactions

स्टैटिक वॉलेट द्वारा प्राप्त सभी deposits की सूची प्राप्त करें।

`POST /v1/static-wallet/transactions`

### Request parameters

| Field | Type | आवश्यक | Description |
|-------|------|----------|-------------|
| `uuid` | string | हाँ | स्टैटिक वॉलेट UUID |
| `date_from` | date | नहीं | प्रारंभ तिथि (YYYY-MM-DD) |
| `date_to` | date | नहीं | अंतिम तिथि (YYYY-MM-DD) |
| `page` | int | नहीं | Page संख्या (default: 1) |
| `per_page` | int | नहीं | प्रति page items (default: 15, अधिकतम: 5000) |

### Response example

```json
{
  "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` — इस deposit से कटी हुई platform fee, `currency` में।
- `net_amount` — fee के बाद merchant बैलेंस में जमा की गई राशि।

## स्टैटिक वॉलेट webhooks

जब किसी स्टैटिक वॉलेट पर भुगतान प्राप्त होता है, तो सिस्टम `url_callback` पर एक webhook भेजता है।

> **WARNING:** स्टैटिक वॉलेट के लिए webhook format सामान्य payment webhooks से भिन्न है। विशेष रूप से, स्टैटिक वॉलेट webhooks में एक `merchant_amount` field होता है जिसका उपयोग आपको crediting के लिए करना चाहिए।

### Webhook payload

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

> **INFO:** स्टैटिक वॉलेट webhooks में `url` या `expires_at` **शामिल नहीं** होते (क्योंकि address स्थायी है, session नहीं)। इनमें `exchange_rate` और `created_at` **शामिल** होते हैं।

### Field reference

| Field | Type | Description |
|-------|------|-------------|
| `uuid` | string | इस deposit के लिए Transaction (invoice) UUID |
| `order_id` | string | आपका स्टैटिक वॉलेट `order_id` |
| `amount` | decimal (8 dp) | प्राप्त crypto राशि |
| `currency` | string | प्राप्त crypto (वॉलेट के `currency` से मेल खाता है) |
| `amount_usd` | decimal (8 dp) | प्राप्ति के समय USD value |
| `exchange_rate` | decimal | उपयोग की गई Crypto / USD दर |
| `payer_currency` | string | स्टैटिक वॉलेट के लिए `currency` के समान |
| `payer_amount` | decimal (8 dp) | स्टैटिक वॉलेट के लिए `amount` के समान |
| `network` | string | Blockchain network |
| `address` | string | स्टैटिक वॉलेट address |
| `payment_status` | string | ??????? deposit status; ????????? `paid`, ????? AML ?? `aml_lock` ?? ???? ?? ???? automatic credit ???? ???? ????? |
| `txid` | string | Blockchain transaction hash |
| `tx_explorer_url` | string \| null | ब्लॉकचेन एक्सप्लोरर में ट्रांज़ैक्शन का URL। `txid` न होने या ट्रांसफ़र के आंतरिक P2P होने पर `null`। |
| `payment_amount` | decimal (8 dp) | `amount` के समान |
| `merchant_amount` | decimal (18 dp) | **Fee deduction के बाद की राशि** — crediting के लिए इसका उपयोग करें |
| `created_at` | string (ISO 8601) | Deposit कब प्राप्त हुआ |
| `sign` | string (hex) | Payload का HMAC-SHA256 सिग्नेचर |

## Best practices

- **Unique `order_id`** — प्रत्येक user या order के लिए एक unique `order_id` का उपयोग करें
- **Idempotency** — डुप्लीकेट credit से बचने के लिए processing से पहले `txid` जाँचें
- **सिग्नेचर verify करें** — फंड credit करने से पहले हमेशा `sign` सिग्नेचर verify करें
- **`merchant_amount` का उपयोग करें** — `payment_amount` के बजाय `merchant_amount` के आधार पर users को credit करें

## लाइफसायकल और आइडेम्पोटेंसी

एक स्थिर वॉलेट एक पुन: प्रयोज्य जमा पहचान है, कोई चालान नहीं। इसका कोई अपेक्षित राशि नहीं है और न ही कोई समाप्ति तिथि। एक पता अपने जीवनकाल में किसी भी संख्या में जमा लेनदेन उत्पन्न कर सकता है।

सृजन एक ही व्यापारी परियोजना के लिए आइडेम्पोटेंट है, `order_id`, `currency`, और `network`: मौजूदा वॉलेट लौटाया जाता है। उस ट्युपल को स्थिर रखें और लौटाए गए वॉलेट को सहेजें `uuid`; हर बार जब वही ग्राहक जमा स्क्रीन खोलता है तो नया `order_id` उपयोग न करें।

जमा की आइडेम्पोटेंसी वॉलेट की आइडेम्पोटेंसी से अलग है:

- `order_id` पुन: प्रयोज्य वॉलेट/ग्राहक मैपिंग की पहचान करता है;
- वॉलेट `uuid` स्थायी वॉलेट रिकॉर्ड की पहचान करता है;
- वेबहुक `uuid` एक पहचानी गई जमा लेनदेन की पहचान करता है;
- `txid` ऑन-चेन ट्रांसफर की पहचान करता है और क्रेडिट करने के लिए प्राथमिक डुप्लीकेशन कुंजी है।

प्रक्रियाधीन चेन/नेटवर्क/txid पहचान के लिए एक डेटाबेस अद्वितीयता प्रतिबंध का उपयोग करें और इसे उसी लेनदेन में दावा करें जो ग्राहक के आंतरिक बैलेंस को क्रेडिट करता है।

## सक्षम और अक्षम अर्थवत्ता

वॉलेट को अक्षम करना आवेदन को इसे सक्रिय जमा लक्ष्य के रूप में संसाधित करने से रोकता है; यह पता या उसके इतिहास को मिटाता नहीं है और उपयोगकर्ता द्वारा पहले से भेजे गए ब्लॉकचेन ट्रांसफर को रोक नहीं सकता।

> **DANGER:** कभी भी उपयोगकर्ताओं से न कहें कि निष्क्रिय पते पर भेजे गए फंड अपने आप लौट जाते हैं। ब्लॉकचेन ट्रांसफ़र अपरिवर्तनीय हैं। केवल तभी अक्षम करें जब आप अपने UI से पता हटा चुके हों, और देर से जमा के लिए एक कार्यशील पुनर्प्राप्ति प्रक्रिया बनाए रखें।

फिर से सक्षम करने पर वही वॉलेट पहचान और पता बनाए रखा जाता है। केवल लेबल बदलने के लिए प्रतिस्थापन न बनाएं; लेबल निपटान पहचानकर्ता नहीं हैं।

## स्थिर वॉलेट के किनारे मामलों

| स्थिति | सही प्रबंधन |
|-----------|------------------|
| डुप्लिकेट निर्माण अनुरोध | वापस लौटे मौजूदा वॉलेट को स्वीकार करें और नए पते की अपेक्षा करने की बजाय इसके स्थायी ट्यूपल को सत्यापित करें। |
| एक पते पर कई जमा | प्रत्येक लेन-देन के लिए एक अलग स्थानीय जमा पंक्ति बनाएं `uuid`/`txid`; कभी भी वॉलेट को स्वयं ‘चुकाया गया’ के रूप में चिह्नित न करें। |
| डुप्लिकेट वेबहुक | पहले ही प्रतिबद्ध txid मिलने के बाद HTTP 200 लौटाएं; फिर कभी क्रेडिट न दें। |
| पुष्टिकरण में देरी या श्रृंखला का पुनः निरीक्षण | प्रसंस्करण को इडेम्पोटेंट रखें और `/v1/static-wallet/transactions` से मिलान करें। |
| ऑटो-कन्वर्ट न्यूनतम से कम जमा | पूर्ण हुए `convert` ब्लॉक के बिना स्रोत-मुद्रा का क्रेडिट अपेक्षित है। |
| ऑटो-कन्वर्ट सफल | स्रोत भुगतान मान और लक्ष्य `convert` परिणाम को अलग-अलग संग्रहित करें। |
| गलत टोकन या गलत नेटवर्क | एक क्रेडिट न बनाएं। सबूत दर्ज करें और समर्थन/पुनर्प्राप्ति टीम को बढ़ाएं क्योंकि पुनर्प्राप्ति श्रृंखला-विशिष्ट होती है। |
| मेमो/टैग-आधारित श्रृंखला | प्लेटफ़ॉर्म द्वारा लौटाए गए हर गंतव्य फ़ील्ड को दिखाएँ और प्रमाणित करें; केवल एक पता पर्याप्त नहीं हो सकता जब मेमो आवश्यक हो। |
| एएमएल लॉक | अधिकारप्राप्त स्थिति अनुपालन प्रक्रिया के माध्यम से जारी नहीं होने तक एंड यूज़र को क्रेडिट न दें। |
| पता दिखाने के बाद वॉलेट अक्षम | इसे UI से तुरंत हटा दें, लेकिन देर से होने वाले ट्रांसफर के लिए परिचालन अलर्ट की निगरानी जारी रखें। |

## सुलह मॉडल

एक आवधिक कार्य चलाएँ जो `/v1/static-wallet/transactions` के माध्यम से पृष्ठ करेगा, txid द्वारा जमा को अपडेट या सम्मिलित करेगा, और उनके `merchant_amount`, स्थिति, और वैकल्पिक रूपांतरण परिणाम की तुलना आपके आंतरिक लेजर के साथ करेगा। वेबहुक डिलीवरी मिलान को तेज़ बनाना चाहिए, लेकिन मिलान को पूर्ण बनाना आवश्यक है।