المدفوعات والسحوبات/Payment API

واجهة Payment API

إنشاء وإدارة جلسات الدفع بالعملات المشفرة باستخدام واجهة 2328.io Payment API.

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

إنشاء دفعة

تنشئ جلسة دفع وتُرجع عنوان URL يستخدمه العميل للدفع.

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

الحقل	النوع	مطلوب	الوصف
`amount`	decimal	نعم	مبلغ الدفع بالعملة المحددة، مثلًا `100.00`
`currency`	string	نعم	عملة ورقية (USD، EUR، RUB، …) أو عملة مشفرة (USDT، TRX، BTC، …)
`order_id`	string	نعم	معرّف الطلب الخاص بك، مثلًا `ORDER-12345` (حتى 128 حرفًا)
`to_currency`	string	لا	عملة مشفرة محددة مسبقًا
`network`	string	لا*	رمز الشبكة (مطلوب عند تعيين `to_currency` أو عندما يكون `currency` عملة مشفرة)
`url_return`	string	لا	عنوان URL لإعادة التوجيه بعد الدفع، مثلًا `https://your-site.com/return`
`url_success`	string	لا	بديل لـ `url_return`
`url_callback`	string	لا	عنوان URL لإشعارات webhook، مثلًا `https://your-site.com/webhook`
`invite_code`	string	لا	رمز المُحيل
`fee_split`	decimal	لا	حصة عمولة التاجر التي يتحملها الدافع، 0–100 (%). 0 = التاجر يدفع بالكامل، 100 = الدافع يدفع بالكامل. يتجاوز الإعداد على مستوى المشروع. مثال: `30` (الدافع يغطي 30% من العمولة).
`price_markup`	decimal	لا	زيادة أو خصم على مبلغ الفاتورة، من −99 إلى 100 (%). يتجاوز الإعداد على مستوى المشروع. مثال: `5` (+5%) أو `-10` (خصم 10%).
`description`	string	لا	وصف اختياري للفاتورة (بحد أقصى 200 حرف). يُعرض للدافع في صفحة الدفع. مثال: `Premium plan — Order #12345`.
`ttl_seconds`	int	لا	مدة صلاحية الفاتورة بالثواني، من `300` (5 دقائق) إلى `86400` (24 ساعة). بعد انتهاء هذه المدة تنتهي صلاحية الفاتورة ولا يمكن دفعها. القيمة الافتراضية: `3600` (ساعة واحدة). مثال: `3600`.

الاستجابة

JSON

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

أعد توجيه العميل إلى result.url لإكمال الدفع.
tg_deeplink — رابط عميق لروبوت Telegram للدفع عبر Telegram MiniApp.
qr — رمز QR مُرمَّز بـ Base64 (data URI) لعنوان الإيداع. يكون موجودًا عندما يتم تعيين عنوان مسبقًا (عند تعيين network مع to_currency، أو عندما يكون currency عملة مشفرة)؛ وإلا فهو null.
txid، payment_amount — تكون null إلى أن يدفع العميل. يتم ملؤها بمجرد اكتشاف المعاملة على البلوكتشين. استمع لـ webhook بحالة payment_status: paid لتعرف الوقت.
exchange_rate — يكون null إذا لم يكن التحويل قابلًا للتطبيق بعد (مثلًا، لم يتم تثبيت سعر العملة الورقية ↔ المشفرة بعد). يتم ملؤه بمجرد اختيار عملة الدفع.

Credentials

Project UUIDAPI key

RequestPOST/v1/payment

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"

Response

Click Try it to see the response here.

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

احصل على حالة الدفع الحالية بواسطة uuid أو order_id.

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

الحقل	النوع	مطلوب	الوصف	القيم
`uuid`	string	نعم*	معرّف الدفعة UUID (من `result.uuid` عند الإنشاء)
`order_id`	string	نعم*	معرّف الطلب الخاص بك

يجب توفير واحد على الأقل من uuid أو order_id.

RequestPOST/v1/payment/info

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"

Response

Click Try it to see the response here.

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

احصل على قائمة بجميع المدفوعات مع التصفية والترقيم.

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

الحقل	النوع	مطلوب	الوصف
`status`	string	لا	تصفية حسب حالة الدفع (راجع References)
`date_from`	date	لا	تاريخ البداية (YYYY-MM-DD)، مثلًا `2026-01-01`
`date_to`	date	لا	تاريخ النهاية (YYYY-MM-DD)، مثلًا `2026-01-31`
`page`	int	لا	رقم الصفحة، الافتراضي `1`
`per_page`	int	لا	عدد العناصر لكل صفحة، الافتراضي `15`، الحد الأقصى `5000`

RequestPOST/v1/payment/list

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"

Response

Click Try it to see the response here.