Sign in
المدفوعات والسحوبات/Payout API

واجهة Payout API

أرسل عمليات سحب من رصيد التاجر إلى أي عنوان بلوكتشين.

تتيح لك واجهة Payout API برمجيًا سحب الأموال من رصيد التاجر إلى أي عنوان بلوكتشين.

لجميع نقاط نهاية Payout، يجب استخدام Payout API key منفصل لإنشاء توقيع sign. هذا المفتاح يختلف عن API key العادي ويجب إنشاؤه من إعدادات المشروع.

إنشاء عملية سحب

ينشئ طلب سحب من رصيد التاجر.

POST/v1/payout

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

الحقلالنوعمطلوبالوصف
currencystringنعمعملة السحب (راجع References)
networkstringنعمرمز الشبكة (راجع References)
amountstringنعممبلغ السحب
to_addressstringنعمعنوان البلوكتشين للمستلم
order_idstringلامفتاح idempotency — فريد داخل المشروع. تكرار POST بنفس order_id لا يُنشئ عملية سحب جديدة — بدلًا من ذلك تُرجع الموجودة
url_callbackstringلاعنوان URL لـ webhooks السحب. اتركه فارغًا لتعطيل webhooks لهذه العملية
memostring | nullلاتاج / memo الوجهة. يُستخدم حاليًا فقط في شبكات TON وSOL؛ بحد أقصى 255 حرفًا
from_currencystringلاالرصيد المصدري الذي يُخصم منه ويُحوَّل تلقائيًا إلى currency لحظة السحب. يتيح لك السحب بأصول متقلّبة (BTC، ETH، …) مع الاحتفاظ برصيدك بعملة مستقرّة مثل USDT — لست مضطرًا لحيازة العملة المتقلّبة بنفسك. مرّر "USDT" لخصم رصيد USDT
fee_optionstringلاكيف يتم احتساب العمولات. deduct (الافتراضي) — رسوم الشبكة + رسوم المنصة تُخصم من amount، ويستلم المستلم amount - fees. add — تُضاف الرسوم فوقه، ويُخصم من التاجر amount + fees، ويستلم المستلم amount بالضبط

Idempotency. داخل مشروع، تكون عملية السحب فريدة بواسطة order_id. إعادة إرسال POST بنفس order_id آمن — تُرجع واجهة API عملية السحب الموجودة بدلًا من إنشاء نسخة مكررة. مرّر دائمًا order_id في عمليات السحب الإنتاجية.

أمثلة الطلبات

Shell
curl -X POST https://api.2328.io/api/v1/payout \
  -H "Content-Type: application/json" \
  -H "User-Agent: MyShop/1.0 (+https://myshop.example)" \
  -H "project: YOUR_PROJECT_UUID" \
  -H "sign: YOUR_HMAC_SIGNATURE" \
  -d '{"currency":"TRX","network":"TRX-TRC20","amount":"1.00","to_address":"TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t","order_id":"9ed25264-8be4-439f-acf5-2a8732538d27","url_callback":"https://your-site.com/webhook/payout","memo":null,"fee_option":"deduct"}'

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

JSON
{
  "state": 0,
  "result": {
    "uuid": "019dea62-1727-72aa-ac2c-eaf2ade193ef",
    "order_id": "9ed25264-8be4-439f-acf5-2a8732538d27",
    "status": "pending",
    "currency": "TRX",
    "network": "TRX-TRC20",
    "amount": "1.00",
    "merchant_amount": "1",
    "network_amount": "0.89",
    "amount_usd": "0.33",
    "to_address": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
    "memo": null,
    "txid": null,
    "block_number": null,
    "error_type": null,
    "created_at": "2026-05-02T23:29:50+03:00",
    "updated_at": "2026-05-02T23:29:50+03:00"
  }
}

العمولات. الافتراضي fee_option: deduct — رسوم الشبكة + رسوم المنصة تُخصم من amount (يستلم المستلم amount - fees). مرّر fee_option: add لإضافة الرسوم فوق المبلغ — سيستلم المستلم amount بالضبط، ويُخصم من التاجر amount + fees.

حساب عملية السحب

يحسب مبالغ ورسوم السحب دون إنشاء عملية سحب ودون خصم من رصيدك. استخدمه لعرض المبلغ الدقيق الذي سيستلمه المستخدم (أو يدفعه) قبل التأكيد.

POST/v1/payout/calc

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

مطابقة لـ إنشاء عملية سحب — نفس الحقول، نفس التوقيع. الحقول order_id و url_callback و to_address و memo مقبولة لكنها مُتجاهَلة: لا تُخزَّن أي عملية سحب ولا تُرسَل أي callbacks.

مثال الطلب

Shell
curl -X POST https://api.2328.io/api/v1/payout/calc \
  -H "Content-Type: application/json" \
  -H "User-Agent: MyShop/1.0 (+https://myshop.example)" \
  -H "project: YOUR_PROJECT_UUID" \
  -H "sign: YOUR_HMAC_SIGNATURE" \
  -d '{"currency":"USDT","network":"TRX-TRC20","amount":"100","fee_option":"add"}'

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

JSON
{
  "state": 0,
  "result": {
    "currency": "USDT",
    "network": "TRX-TRC20",
    "amount": "100",
    "fee_option": "add",
    "merchant_amount": "103.00000000",
    "network_amount": "100",
    "total_fee": "3.00000000",
    "total_fee_usd": "3.00000000"
  }
}

معاينة فقط. هذه النقطة الطرفية للقراءة فقط — لا يُخصم من الرصيد ولا تُنشَأ أي عملية سحب. اتصل بها بالقدر الذي تحتاجه لعرض تفصيل الرسوم في واجهتك.

حالة السحب

احصل على حالة طلب السحب.

GET/v1/payout/status/{uuid}

معاملات المسار

الحقلالنوعمطلوبالوصف
uuidstringنعممعرّف السحب UUID (من result.uuid عند الإنشاء)

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

JSON
{
  "state": 0,
  "result": {
    "uuid": "019dff1f-0dbd-7277-8d45-271e7775388f",
    "order_id": "4dfdcc84402b1185b71cbe399321533e",
    "status": "completed",
    "currency": "TRX",
    "network": "TRX-TRC20",
    "amount": "3.00",
    "merchant_amount": "3.00",
    "network_amount": "3.00",
    "amount_usd": "1.04",
    "to_address": "THauRv5tcucQRohXg8NiyGTk16DX1XQG5x",
    "memo": null,
    "txid": "9242e533703704ef3eaba840f70b4a26333e72c943377ee375fea17badb53def",
    "block_number": null,
    "error_type": null,
    "created_at": "2026-05-07T00:08:38+03:00",
    "updated_at": "2026-05-07T00:08:54+03:00",
    "from_currency": "USDT",
    "debited_amount": "1.050735",
    "debited_currency": "USDT"
  }
}

لطلب GET هذا، يُحسب التوقيع من محتوى فارغ: hash_hmac('sha256', base64_encode(''), $apiKey)

حقول الاستجابة

الحقول المرجعة في result من POST /v1/payout وGET /v1/payout/status/{uuid}:

الحقلالنوعالوصف
uuidstringمعرّف السحب UUID المعيّن من النظام
order_idstringمعرّف السحب الداخلي الخاص بك (فريد داخل المشروع)
statusstringحالة السحب الحالية (انظر أدناه)
currencystringعملة السحب
networkstringرمز الشبكة
amountstringمبلغ السحب كما طُلب
merchant_amountstringالمبلغ المخصوم من رصيد التاجر
network_amountstringالمبلغ المُرسل فعليًا على البلوكتشين (بعد رسوم الشبكة + المنصة)
amount_usdstringالمكافئ بالدولار الأمريكي لمبلغ السحب
to_addressstringعنوان البلوكتشين للمستلم
memostring | nullتاج / memo الوجهة (TON، SOL). null خلاف ذلك
txidstring | nullهاش معاملة البلوكتشين. null حتى يتم إرسال المعاملة
block_numberint | nullرقم البلوك الذي تم تضمين المعاملة فيه. null حتى يتم التضمين
error_typestring | nullسبب الفشل عند status = failed (راجع أنواع الأخطاء أدناه). null خلاف ذلك
created_atstring (ISO 8601)وقت إنشاء السحب
updated_atstring (ISO 8601)وقت آخر تغيير حالة
from_currencystring | nullالرصيد المصدري الذي خُصم منه السحب عند استخدام التحويل التلقائي (مثلًا USDT لسحب بـ BTC). يكون null إذا لم يحدث تحويل
debited_amountstring | nullالمبلغ المخصوم فعليًا من الرصيد المصدري بعد التحويل. يكون موجودًا فقط عند استخدام التحويل التلقائي
debited_currencystring | nullعملة debited_amount — الرصيد الذي خُصمت منه الأموال

حالات السحب

يمكن أن يأخذ حقل status القيم التالية:

الحالةالوصف
pendingتم إنشاؤها، بانتظار المعالجة
completedتمت بنجاح — تم تعيين txid
failedخطأ في الإرسال — راجع error_type
cancelledملغاة

أنواع الأخطاء

عندما يكون status = failed، يصف حقل error_type السبب:

الرمزالوصف
aml_riskتم حظر السحب بواسطة فحوصات مخاطر AML (تم تصنيف عنوان المستلم على أنه عالي المخاطر)

إشعارات webhook

عندما تتغير حالة عملية سحب، يرسل النظام webhook بطريقة POST إلى عنوان url_callback الذي تم تمريره عند إنشاء السحب. إذا لم يتم توفير url_callback، فلن يتم إرسال أي webhooks لتلك العملية.

  • الطريقة: POST
  • Content-Type: application/json
  • التوقيع: حقل sign في محتوى الطلب، محسوب باستخدام Payout API key (نفس المفتاح المستخدم لتوقيع طلبات السحب).

يعكس المحتوى كائن result من GET /v1/payout/status/{uuid} بالإضافة إلى حقل sign للتحقق.

المحتوى

JSON
{
  "uuid": "019dff1f-0dbd-7277-8d45-271e7775388f",
  "order_id": "4dfdcc84402b1185b71cbe399321533e",
  "status": "completed",
  "currency": "TRX",
  "network": "TRX-TRC20",
  "amount": "3.00",
  "merchant_amount": "3.00",
  "network_amount": "3.00",
  "amount_usd": "1.04",
  "to_address": "THauRv5tcucQRohXg8NiyGTk16DX1XQG5x",
  "memo": null,
  "txid": "9242e533703704ef3eaba840f70b4a26333e72c943377ee375fea17badb53def",
  "block_number": null,
  "error_type": null,
  "created_at": "2026-05-07T00:08:38+03:00",
  "updated_at": "2026-05-07T00:08:54+03:00",
  "from_currency": "USDT",
  "debited_amount": "1.050735",
  "debited_currency": "USDT",
  "sign": "925ad7bf3d6841864101f7cc2c7e30652e70a06cdb04dbe07a0129480000ce4a"
}

التحقق من التوقيع. استخدم نفس الخوارزمية المستخدمة في webhooks المدفوعات، لكن وقّع باستخدام Payout API key بدلًا من API key العادي. أزل حقل sign، رمّز المحتوى المتبقي بـ JSON، رمّزه بـ Base64، ثم احسب hash_hmac('sha256', $base64, $payoutApiKey) وقارنه بـ sign المستلم.