المحافظ الثابتة

المحافظ الثابتة هي عناوين دائمة لاستلام مدفوعات العملات المشفرة. ترتبط بـ order_id معيّن وتكون فريدة بمجموع project_id + order_id + currency + network.

استخدم المحافظ الثابتة من أجل:

• الإيداعات المتكررة من نفس المستخدم
• عناوين دفع طويلة الأمد تُعرض على الملف الشخصي للمستخدم
• تدفقات إيداع كبيرة الحجم حيث تريد عنوانًا ثابتًا لكل مستخدم

إنشاء محفظة ثابتة

معاملات الطلب

مثال على الطلب

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

مثال على الاستجابة

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

معاملات الطلب

مثال على الاستجابة

{
  "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.
• transactions_count — عدد الإيداعات المستلمة حتى الآن.
• qr — رمز QR مُرمَّز بـ Base64 (data URI) لعنوان الإيداع (موجود دائمًا للمحافظ الثابتة، حيث يتم تعيين العنوان عند الإنشاء).

قائمة المحافظ

معاملات الطلب

مثال على الاستجابة

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

تفعيل / تعطيل المحفظة

تبديل ما إذا كانت المحفظة الثابتة تقبل مدفوعات جديدة.

الطلب

تأخذ كلتا نقطتي النهاية معاملًا واحدًا:

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

مثال على الاستجابة

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

بالنسبة لـ enable، تكون status هي "active" وتكون message هي "Static wallet enabled successfully".

معاملات المحفظة

احصل على قائمة بجميع الإيداعات المستلمة بمحفظة ثابتة.

معاملات الطلب

مثال على الاستجابة

{
  "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 — رسوم المنصة المخصومة من هذا الإيداع، بـ currency.
• net_amount — المبلغ المُضاف إلى رصيد التاجر بعد الرسوم.

webhooks المحافظ الثابتة

عند استلام دفعة على محفظة ثابتة، يرسل النظام webhook إلى url_callback.

محتوى webhook

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

مرجع الحقول

أفضل الممارسات

• order_id فريد — استخدم order_id فريدًا لكل مستخدم أو طلب
• Idempotency — تحقق من txid قبل المعالجة لتجنب الإيداعات المكررة
• التحقق من التوقيعات — تحقق دائمًا من توقيع sign قبل إيداع الأموال
• استخدم merchant_amount — أضف للمستخدمين على أساس merchant_amount، وليس payment_amount

دورة الحياة وعدم التغيير عند التكرار

المحفظة الثابتة هي هوية إيداع قابلة لإعادة الاستخدام، وليست فاتورة. ليس لديها مبلغ متوقع ولا تاريخ انتهاء. يمكن أن تنتج عنوان واحد أي عدد من المعاملات الإيداعية خلال فترة حياته.

الإنشاء لا يتغير عند التكرار لنفس مشروع التاجر، order_id، currency، وnetwork: يتم إرجاع المحفظة الموجودة. احرص على ثبات هذا الزوج واستمر في المحفظة المعادة uuid؛ لا تستخدم order_id جديدًا في كل مرة يفتح فيها نفس العميل شاشة الإيداع.

عدم التغيير عند التكرار للإيداع يختلف عن عدم التغيير عند التكرار للمحفظة:

• order_id يحدد التوافق بين المحفظة القابلة لإعادة الاستخدام والعميل؛
• uuid للمحفظة يحدد سجل المحفظة الدائم؛
• الويب هوك uuid يحدد عملية إيداع مكتشفة واحدة;
• txid يحدد التحويل على السلسلة ويعتبر مفتاح التكرار الأساسي لمنح الرصيد.

استخدم قيد فريد في قاعدة البيانات لهوية السلسلة/الشبكة/معرف المعاملة المعالجة وادعِ ذلك في نفس المعاملة التي تخص رصيد العميل الداخلي.

تمكين وتعطيل الدلالات

إيقاف المحفظة يمنع التطبيق من معالجتها كهدف إيداع نشط؛ لا يمحو العنوان أو تاريخه ولا يمكنه إيقاف تحويل على البلوكشين تم إرساله بالفعل من قبل المستخدم.

إعادة التمكين تحافظ على نفس هوية المحفظة والعنوان. لا تنشئ بديلاً لمجرد تغيير التسمية؛ التسمية ليست معرفًا للتسوية.

حالات حافة المحفظة الثابتة

نموذج المطابقة

قم بتشغيل وظيفة دورية تتصفح /v1/static-wallet/transactions، وتقوم بإجراء تحديث أو إدراج للودائع حسب txid، وتقارن بين merchant_amount، والحالة، ونتيجة التحويل الاختيارية مع دفتر الحسابات الداخلي الخاص بك. يجب أن تجعل تسليم الويب هوك عملية المطابقة سريعة، ولكن يجب أن تجعل عملية المطابقة مكتملة.