واجهة Payment API

تتيح لك واجهة Payment API إنشاء جلسات الدفع، وإعادة توجيه العملاء إلى صفحة دفع مستضافة، وتتبع حالة الدفع.

إنشاء دفعة

{
  "state": 0,
  "result": {
    "uuid": "abc123-def456-...",
    "order_id": "ORDER-12345",
    "amount": "100.00",
    "currency": "USD",
    "amount_usd": "100.00",
    "exchange_rate": null,
    "url": "https://2328.io/pay/abc123-def456-...",
    "tg_deeplink": "https://t.me/my2328bot?start=pay_abc123-def456-...",
    "expires_at": "2026-01-11T21:00:00Z",
    "created_at": "2026-01-11T20:00:00Z",
    "payer_currency": "USDT",
    "payer_amount": "100.50",
    "network": "TRX-TRC20",
    "address": "TXYZabc123...",
    "payment_status": "check",
    "txid": null,
    "payment_amount": null,
    "qr": "data:image/png;base64,iVBORw0..."
  }
}

curl -X POST https://api.2328.io/api/v1/payment \
  -H "Content-Type: application/json" \
  -H "User-Agent: MyShop/1.0 (+https://myshop.example)" \
  -H "project: YOUR_PROJECT_UUID" \
  -H "sign: YOUR_HMAC_SIGNATURE"

تسجيل المغادرة المستضاف، H2H، والمبالغ الدقيقة بالعملات المشفرة

نفس نقطة النهاية تدعم ثلاث أشكال فواتير مميزة. اختر واحدًا بعناية؛ لا تخلط بين دلالات المبلغ الخاصة بهم.

تسجيل المغادرة المستضاف مع اختيار الدافع

أرسل amount، currency، order_id، وurl_callback، ولكن احذف to_currency وnetwork. تحتوي الاستجابة على result.url؛ تبقى address، qr، وأحيانًا حقول الدافع null حتى يختار الدافع اتجاهًا على الصفحة المستضافة.

{
  "amount": "125.00",
  "currency": "EUR",
  "order_id": "ORDER-2026-1042",
  "url_callback": "https://merchant.example/webhooks/2328",
  "url_return": "https://merchant.example/orders/ORDER-2026-1042"
}

فاتورة H2H بعنوان مباشر

أرسل كلا من to_currency و network. يقوم 2328.io بإنشاء فاتورة البلوكشين أثناء استدعاء واجهة برمجة التطبيقات، لذلك يمكن عرض استجابة ناجحة داخل صفحة الدفع الخاصة بك دون إعادة توجيه العميل.

{
  "amount": "100.00",
  "currency": "USD",
  "to_currency": "USDT",
  "network": "TRX-TRC20",
  "order_id": "ORDER-2026-1043",
  "url_callback": "https://merchant.example/webhooks/2328"
}

قم بعرض هذه القيم بالضبط كما تم إرجاعها:

• payer_amount و payer_currency — تعليمات الدفع;
• network و address — الوجهة الوحيدة لهذه الفاتورة;
• qr — URI بيانات لنفس العنوان;
• expires_at — الموعد النهائي للفاتورة;
• url — نسخة احتياطية مستضافة مفيدة عندما لا يمكن إكمال عملية الدفع المخصصة.

فاتورة لمبلغ محدد من العملات الرقمية

ضع العملة الرقمية في currency عندما تكون الفاتورة نفسها مقومة بالعملات الرقمية:

{
  "amount": "25.000000",
  "currency": "USDT",
  "network": "TRX-TRC20",
  "order_id": "ORDER-2026-1044",
  "url_callback": "https://merchant.example/webhooks/2328"
}

يتم الاحتفاظ بالقيمة المطلوبة من العملات الرقمية في payer_currency / payer_amount. يمكن للخدمة أيضًا الاحتفاظ بقيمة بالعملة الأمريكية داخليًا لأغراض المحاسبة وحقول السعر؛ لا تقم باستبدال التعليمات الدقيقة للعملات الرقمية بتلك القيمة. حافظ على سلاسل الأرقام العشرية المسترجعة، بما في ذلك الدقة النهائية.

بالنسبة للعملة المشفرة التي تدعم شبكة واحدة فقط، قد يتم اختيار الشبكة تلقائيًا. ومع ذلك، يُوصى بتقديم network صراحةً لتحقيق تكامل حتمي. بالنسبة للأصول متعددة الشبكات مثل العملات المستقرة، يجب إرسالها دائمًا.

التكرار وإعادة المحاولة

order_id يقتصر على مشروع التاجر المصادق عليه ويعمل كمفتاح تكرار الإنشاء. إذا كان الدفع موجودًا بالفعل، تقوم واجهة برمجة التطبيقات بإرجاع تلك الجلسة مع state: 0.

الخوارزمية الموصى بها للإنشاء:

1. أدخل محاولة الدفع المحلية الخاصة بك و order_id الفريد في معاملة قاعدة بيانات واحدة.
2. أرسل طلب API الموقع.
3. احتفظ بـ uuid المسترجع والاستجابة الكاملة.
4. إذا ضاع نتيجة HTTP، قم بإعادة الطلب نفسه أو استعلم عن /v1/payment/info بواسطة order_id.
5. لا تنشئ طلبًا محليًا ثانٍ لمجرد أن طلب المصدر أعلاه انتهت مهلةه.

حالات الحافة للدفع

عنوان URL الذي يعيده المتصفح هو للتنقل فقط. يمكن للعميل فتحه دون دفع، أو إغلاقه بعد الدفع، أو تشغيله مرة أخرى لاحقًا. فقط حالة API/ويب هوك مؤكدة يمكن أن تسوي طلب التاجر.

معلومات الدفعة

curl -X POST https://api.2328.io/api/v1/payment/info \
  -H "Content-Type: application/json" \
  -H "User-Agent: MyShop/1.0 (+https://myshop.example)" \
  -H "project: YOUR_PROJECT_UUID" \
  -H "sign: YOUR_HMAC_SIGNATURE"

قائمة المدفوعات

curl -X POST https://api.2328.io/api/v1/payment/list \
  -H "Content-Type: application/json" \
  -H "User-Agent: MyShop/1.0 (+https://myshop.example)" \
  -H "project: YOUR_PROJECT_UUID" \
  -H "sign: YOUR_HMAC_SIGNATURE"