# واجهة Payment API

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

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

## إنشاء دفعة

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

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

| الحقل | النوع | مطلوب | الوصف | القيم |
|-------|------|----------|-------------|--------|
| `amount` | decimal | نعم | مبلغ الدفع بالعملة المحددة، مثلًا `100.00` |  |
| `currency` | string | نعم | عملة ورقية (USD، EUR، RUB، …) أو عملة مشفرة (USDT، TRX، BTC، …) | `USD`, `EUR`, `RUB`, `KZT`, `UAH`, `UZS`, `USDT`, `USDC`, `BTC`, `ETH`, `GRAM`, `SOL`, `TRX`, `BNB`, `POL`, `LTC`, `DASH`, `DOGE`, `ZEC`, `XRP`, `XMR` |
| `order_id` | string | نعم | معرّف الطلب الخاص بك، مثلًا `ORDER-12345` (حتى 128 حرفًا) |  |
| `to_currency` | string | لا | عملة مشفرة محددة مسبقًا | `USDT`, `USDC`, `BTC`, `ETH`, `GRAM`, `SOL`, `TRX`, `BNB`, `POL`, `LTC`, `DASH`, `DOGE`, `ZEC`, `XRP`, `XMR` |
| `network` | string | لا\* | رمز الشبكة (مطلوب عند تعيين `to_currency` أو عندما يكون `currency` عملة مشفرة) | `TRX-TRC20`, `ETH-ERC20`, `BASE`, `BSC-BEP20`, `AVAX-C`, `POL-MATIC`, `TON`, `SOL`, `BTC`, `LTC`, `DASH`, `DOGE`, `ZEC`, `XRP`, `XMR` |
| `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` إذا لم يكن التحويل قابلًا للتطبيق بعد (مثلًا، لم يتم تثبيت سعر العملة الورقية ↔ المشفرة بعد). يتم ملؤه بمجرد اختيار عملة الدفع.

> Use your project UUID and the endpoint-appropriate API key from the merchant dashboard.

#### Interactive request: `POST /v1/payment`
  - `amount` (decimal, required)
  - `currency` (enum, required): USD,EUR,RUB,KZT,UAH,UZS,USDT,USDC,BTC,ETH,GRAM,SOL,TRX,BNB,POL,LTC,DASH,DOGE,ZEC,XRP,XMR
  - `order_id` (string, required)
  - `to_currency` (enum): USDT,USDC,BTC,ETH,GRAM,SOL,TRX,BNB,POL,LTC,DASH,DOGE,ZEC,XRP,XMR
  - `network` (enum): TRX-TRC20,ETH-ERC20,BASE,BSC-BEP20,AVAX-C,POL-MATIC,TON,SOL,BTC,LTC,DASH,DOGE,ZEC,XRP,XMR
  - `url_return` (string)
  - `url_success` (string)
  - `url_callback` (string, required)
  - `invite_code` (string)
  - `fee_split` (decimal)
  - `price_markup` (decimal)
  - `description` (string)
  - `ttl_seconds` (integer)

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

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

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

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

```json
{
  "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 بإنشاء فاتورة البلوكشين أثناء استدعاء واجهة برمجة التطبيقات، لذلك يمكن عرض استجابة ناجحة داخل صفحة الدفع الخاصة بك دون إعادة توجيه العميل.

```json
{
  "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` — نسخة احتياطية مستضافة مفيدة عندما لا يمكن إكمال عملية الدفع المخصصة.

> **DANGER:** لا تقم أبدًا بتوليد عنوان أو استبداله، أو إعادة استخدام عنوان من فاتورة أخرى، أو حساب `payer_amount` من سعر سوق عام. استجابة واجهة برمجة التطبيقات هي المرجع.

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

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

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

> **WARNING:** إعادة المحاولة بنفس `order_id` لا يعني أن **not** تعني "تحديث هذه الفاتورة". قد يتم تجاهل تغييرات المبلغ أو العملة أو الاستدعاء الخلفي أو الهامش أو TTL أو حقول الاتجاه لأن الجلسة الموجودة يتم إرجاعها. احتفظ بالطلب الأول ورفض عمليات المحاولة المتعارضة في تطبيقك الخاص.

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

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

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

| الوضع | المعالجة الصحيحة |
|-----------|------------------|
| `address` / `qr` هو `null` | لم يتم تهيئة اتجاه الدافع. قم بإعادة التوجيه إلى `url`، أو أنشئ فاتورة H2H جديدة محددة بشكل صحيح مع `order_id` جديد. |
| خطأ في التحقق من HTTP `400` | اقرأ الحقل على مستوى `errors`؛ لا تحاول إعادة الإدخال غير المعدل. |
| HTTP `429` | أعد المحاولة باستخدام تراجع أسي متغير الاحتكاك واحتفظ بنفس `order_id`. |
| HTTP `503` / `direction_disabled` | قم بتحديث `/v1/directions`؛ أخفِ الاتجاه مؤقتًا أو أعد المحاولة لاحقًا. |
| انتهت مهلة طلب العميل | اعتبر النتيجة مجهولة. استعلم عن طريق `order_id` قبل إنشاء أي شيء آخر. |
| `underpaid_check` | خزن الحدث الجزئي وانتظر تعزيز الرصيد أو الحالة لاحقًا. لا تقم بالإئتمان مرتين عند وصول مزيد من معرفات المعاملات. |
| `underpaid` | حالة دفع ناقص نهائية. طبق سياسة التنفيذ/المراجعة اليدوية المُعدة على المبلغ الفعلي المُعتمد. |
| `overpaid` | دفع ناجح مع أموال فائضة. نفذ بشكل متسق واحتفظ بالمبالغ الفعلية لمراجعة التسوية/سياسة الاسترداد. |
| `aml_lock` | لا تقم بالتنفيذ أو تحرير الأموال تلقائيًا؛ وجهه إلى سير عمل الامتثال / الدعم. |
| `cancel` | الفاتورة انتهت صلاحيتها أو تم إلغاؤها. لا تستنتج أن التحويل على الشبكة المتأخر مستحيل؛ قم بتسوية أي حدث لاحق مع الدعم. |

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

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

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

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

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

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

#### Interactive request: `POST /v1/payment/info`
  - `uuid` (string)
  - `order_id` (string)

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

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

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

| الحقل | النوع | مطلوب | الوصف | القيم |
|-------|------|----------|-------------|--------|
| `status` | string | لا | تصفية حسب حالة الدفع (راجع [References](/docs/references)) | `pending`, `check`, `paid`, `underpaid_check`, `underpaid`, `overpaid`, `cancel` |
| `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` |  |

#### Interactive request: `POST /v1/payment/list`
  - `status` (enum): pending,check,paid,underpaid_check,underpaid,overpaid,cancel
  - `date_from` (string)
  - `date_to` (string)
  - `page` (integer)
  - `per_page` (integer)