# واجهة Payment API

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

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

## إنشاء دفعة

<TwoCol>

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

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

| الحقل | النوع | مطلوب | الوصف | القيم |
|-------|------|----------|-------------|--------|
| `amount` | decimal | نعم | مبلغ الدفع بالعملة المحددة، مثلًا `100.00` | <InputValue name="amount" type="decimal" example="100.00" /> |
| `currency` | string | نعم | عملة ورقية (USD، EUR، RUB، …) أو عملة مشفرة (USDT، TRX، BTC، …) | <EnumValues name="currency" values="USD,EUR,RUB,KZT,UAH,UZS,USDT,USDC,BTC,ETH,TON,SOL,TRX,BNB,MATIC,XMR" /> |
| `order_id` | string | نعم | معرّف الطلب الخاص بك، مثلًا `ORDER-12345` (حتى 128 حرفًا) | <InputValue name="order_id" example="ORDER-12345" /> |
| `to_currency` | string | لا | عملة مشفرة محددة مسبقًا | <EnumValues name="to_currency" values="USDT,USDC,BTC,ETH,TON,SOL,TRX,BNB,MATIC,XMR" optional /> |
| `network` | string | لا\* | رمز الشبكة (مطلوب عند تعيين `to_currency` أو عندما يكون `currency` عملة مشفرة) | <EnumValues name="network" values="TRX-TRC20,ETH-ERC20,BSC-BEP20,TON,SOL,BTC,MATIC,XMR" optional /> |
| `url_return` | string | لا | عنوان URL لإعادة التوجيه بعد الدفع، مثلًا `https://your-site.com/return` | <InputValue name="url_return" placeholder="https://your-site.com/return" /> |
| `url_success` | string | لا | بديل لـ `url_return` | <InputValue name="url_success" placeholder="https://your-site.com/success" /> |
| `url_callback` | string | لا | عنوان URL لإشعارات webhook، مثلًا `https://your-site.com/webhook` | <InputValue name="url_callback" example="https://your-site.com/webhook" /> |
| `invite_code` | string | لا | رمز المُحيل | <InputValue name="invite_code" placeholder="ref_xyz" /> |
| `fee_split` | decimal | لا | حصة عمولة التاجر التي يتحملها الدافع، 0–100 (%). 0 = التاجر يدفع بالكامل، 100 = الدافع يدفع بالكامل. يتجاوز الإعداد على مستوى المشروع. **مثال: `30`** (الدافع يغطي 30% من العمولة). | <InputValue name="fee_split" type="decimal" placeholder="30" /> |
| `price_markup` | decimal | لا | زيادة أو خصم على مبلغ الفاتورة، من −99 إلى 100 (%). يتجاوز الإعداد على مستوى المشروع. **مثال: `5`** (+5%) أو `-10` (خصم 10%). | <InputValue name="price_markup" type="decimal" placeholder="5" /> |
| `description` | string | لا | وصف اختياري للفاتورة (بحد أقصى 200 حرف). يُعرض للدافع في صفحة الدفع. **مثال: `Premium plan — Order #12345`**. | <InputValue name="description" placeholder="Premium plan — Order #12345" /> |
| `ttl_seconds` | int | لا | مدة صلاحية الفاتورة بالثواني، من `300` (5 دقائق) إلى `86400` (24 ساعة). بعد انتهاء هذه المدة تنتهي صلاحية الفاتورة ولا يمكن دفعها. القيمة الافتراضية: `3600` (ساعة واحدة). **مثال: `3600`**. | <InputValue name="ttl_seconds" type="integer" placeholder="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` إذا لم يكن التحويل قابلًا للتطبيق بعد (مثلًا، لم يتم تثبيت سعر العملة الورقية ↔ المشفرة بعد). يتم ملؤه بمجرد اختيار عملة الدفع.

<TwoColAside>

<Credentials />

<TryIt endpoint="POST /v1/payment">
  <Param name="amount" type="decimal" required />
  <Param name="currency" type="enum" required values="USD,EUR,RUB,KZT,UAH,UZS,USDT,USDC,BTC,ETH,TON,SOL,TRX,BNB,MATIC,XMR" />
  <Param name="order_id" type="string" required />
  <Param name="to_currency" type="enum" values="USDT,USDC,BTC,ETH,TON,SOL,TRX,BNB,MATIC,XMR" />
  <Param name="network" type="enum" values="TRX-TRC20,ETH-ERC20,BSC-BEP20,TON,SOL,BTC,MATIC,XMR" />
  <Param name="url_return" type="string" />
  <Param name="url_success" type="string" />
  <Param name="url_callback" type="string" />
  <Param name="invite_code" type="string" />
  <Param name="fee_split" type="decimal" />
  <Param name="price_markup" type="decimal" />
  <Param name="description" type="string" />
  <Param name="ttl_seconds" type="integer" />
</TryIt>

</TwoColAside>

</TwoCol>

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

<TwoCol>

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

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

| الحقل | النوع | مطلوب | الوصف | القيم |
|-------|------|----------|-------------|--------|
| `uuid` | string | نعم\* | معرّف الدفعة UUID (من `result.uuid` عند الإنشاء) | <InputValue name="uuid" example="abc123-def456-..." /> |
| `order_id` | string | نعم\* | معرّف الطلب الخاص بك | <InputValue name="order_id" placeholder="ORDER-12345" /> |

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

<TwoColAside>

<TryIt endpoint="POST /v1/payment/info">
  <Param name="uuid" type="string" />
  <Param name="order_id" type="string" />
</TryIt>

</TwoColAside>

</TwoCol>

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

<TwoCol>

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

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

| الحقل | النوع | مطلوب | الوصف | القيم |
|-------|------|----------|-------------|--------|
| `status` | string | لا | تصفية حسب حالة الدفع (راجع [References](/docs/references)) | <EnumValues name="status" values="pending,check,paid,underpaid_check,underpaid,overpaid,cancel,aml_lock" optional /> |
| `date_from` | date | لا | تاريخ البداية (YYYY-MM-DD)، مثلًا `2026-01-01` | <InputValue name="date_from" example="2026-01-01" /> |
| `date_to` | date | لا | تاريخ النهاية (YYYY-MM-DD)، مثلًا `2026-01-31` | <InputValue name="date_to" example="2026-01-31" /> |
| `page` | int | لا | رقم الصفحة، الافتراضي `1` | <InputValue name="page" type="integer" example="1" /> |
| `per_page` | int | لا | عدد العناصر لكل صفحة، الافتراضي `15`، الحد الأقصى `5000` | <InputValue name="per_page" type="integer" example="15" /> |

<TwoColAside>

<TryIt endpoint="POST /v1/payment/list">
  <Param name="status" type="enum" values="pending,check,paid,underpaid_check,underpaid,overpaid,cancel,aml_lock" />
  <Param name="date_from" type="string" />
  <Param name="date_to" type="string" />
  <Param name="page" type="integer" />
  <Param name="per_page" type="integer" />
</TryIt>

</TwoColAside>

</TwoCol>