للمطورين

واجهة عمليات الحساب

اقرأ الرصيد، واطلب الاستردادات والسحوبات، وأجب عن النزاعات، وأدر عمليات تسليم webhook. وقّع كل طلب كما هو موضح في المصادقة.

عنوان URL الأساسيhttps://www.manuellsolutions.com/api/v3
إصدار الواجهة3.0.0

تصفّح العمليات

البيئة

Sandboxالإنتاج

اختبر دون تحريك أموال حقيقية.

مدفوعات حقيقية. يلزم مفتاح الإنتاج.

الرصيد

اقرأ رصيدك المتاح والقابل للسحب.

رصيد sandbox افتراضي. تنتقل مدفوعات sandbox فورًا إلى available_amount دون انتظار تاريخ القيمة، فيمكنك اختبار السحوبات مباشرة.

يتكوّن رصيد الإنتاج من مبالغ محصّلة فعلًا. تنتظر الدفعة في pending_settlement_amount حتى تاريخ القيمة ثم تنتقل إلى available_amount.

GET/api/v3/balance

جلب الرصيد

الاستجابة · 200

ملخص الرصيد.

`Balance`

الحقل	النوع	مطلوب	الوصف
`currency_code`	`string`	مطلوب	عملة المنصة الأساسية المهيأة. `USDEURAEDTRY`
`available_amount`	`string`	مطلوب	إجمالي الرصيد المتاح في محافظ روابط الدفع وAPI والمتجر. ويقرأ مفتاح sandbox بدلًا من ذلك محفظة API الافتراضية المعزولة.
`pending_settlement_amount`	`string`	مطلوب	مبلغ مُحصَّل لكنه لم يُسوَّ بعد (تاريخ القيمة لم يحن). تكون القيمة دائمًا 0.00 مع مفتاح sandbox لأن مدفوعات sandbox لا تنتظر تاريخ القيمة.
`environment`	`string`	مطلوب	البيئة التي تنتمي إليها الأرقام (بيئة مفتاح التوقيع). `livesandbox`

الاستجابة · مثال

{
  "currency_code": "USD",
  "available_amount": "48200.00",
  "pending_settlement_amount": "250.00",
  "environment": "live"
}

الأخطاء المحتملة

9000026503

GET/api/v3/balance/withdrawable

جلب الرصيد القابل للسحب

الاستجابة · 200

ملخص الرصيد القابل للسحب.

`WithdrawableBalance`

الحقل	النوع	مطلوب	الوصف
`currency_code`	`string`	مطلوب	عملة المنصة الأساسية المهيأة. `USDEURAEDTRY`
`withdrawable_amount`	`string`	مطلوب	إجمالي الرصيد المتاح لروابط الدفع وAPI والمتجر؛ ولا يستطيع POST /withdrawals الخصم إلا من محفظة API ويطبّق فحوصًا إضافية. ويقرأ مفتاح sandbox محفظة API الافتراضية المعزولة.
`can_withdraw`	`boolean`	مطلوب	تكون القيمة false إذا كان أي جزء من المحفظة سالبًا.
`environment`	`string`	مطلوب	البيئة التي تنتمي إليها الأرقام (بيئة مفتاح التوقيع). `livesandbox`

الاستجابة · مثال

{
  "currency_code": "USD",
  "withdrawable_amount": "48200.00",
  "can_withdraw": true,
  "environment": "live"
}

الأخطاء المحتملة

9000026503

المبالغ المستردة

اطلب استردادًا أو إلغاءً وتابعه.

في الإنتاج، يعني HTTP 202 أن الطلب استُلم، وليس أن الاسترداد اكتمل. تابع النتيجة عبر نقاط نهاية الحالة: requested ثم awaiting_provider_manual ثم completed؛ أو rejected / cancelled.

في sandbox يُحسم الطلب فورًا (completed افتراضيًا). أرسل X-CAV-Sandbox-Scenario: rejected لاختبار استرداد مرفوض.

تُراجع الطلبات في الإنتاج. تابع عملية العكس حتى completed أو rejected أو cancelled. يرسل refund المكتمل فقط payment.refunded؛ تابع void عبر GET.

POST/api/v3/refundsيتطلب Idempotency-Key

طلب استرداد أو إلغاء

المعاملات

الحقل	النوع	مطلوب	الوصف
`X-CAV-Sandbox-Scenario`	`string · header`	اختياري	لمفاتيح sandbox فقط. يحدد النتيجة المحاكاة: `completed` (الافتراضية) أو `rejected` (دون أي أثر في المحفظة الافتراضية). أما مفتاح الإنتاج الذي يرسل هذه الترويسة، أو أي مفتاح يرسل قيمة أخرى، فيحصل على 422 `1000001`. والترويسة ليست جزءًا من النص الموقَّع؛ لكنها جزء من بصمة Idempotency-Key، ولذلك تُرجع إعادة استخدام مفتاح مع سيناريو آخر 9000010. ويُعاد السيناريو المطبَّق في ترويسة الاستجابة التي تحمل الاسم نفسه. `completedrejected`

جسم الطلب

الحقل	النوع	مطلوب	الوصف
`payment_code`	`string`	مطلوب	رمز الدفعة الناجحة المراد استردادها أو إلغاؤها. `maxLength 16`
`operation_type`	`string`	مطلوب	يُستخدم `refund` لاسترداد دفعة نهائية، ويُستخدم `void` لإلغاء تحصيل بالبطاقة لم يصبح نهائيًا بعد. وكلاهما يفتح طلبًا جديدًا (الحالة `requested`). يراجع الطلب مشغّل؛ وبعد الموافقة يُحجز المبلغ من رصيدك وتكون الحالة `awaiting_provider_manual` إلى أن يُسجَّل مرجع استرداد مزوّد الدفع (`completed`)؛ وإلا ينتهي الطلب بالحالة `rejected` أو `cancelled` (ويُفرَج عن المبلغ المحجوز). لا تتصل نقطة النهاية هذه بمزوّد الدفع. `refundvoid`
`reason`	`string`	مطلوب	سبب طلب الاسترداد أو الإلغاء. `minLength 3maxLength 500`

جسم الطلب · مثال

{
  "payment_code": "ab34cdef",
  "operation_type": "refund",
  "reason": "Customer cancelled the order."
}

الاستجابة · 202

تم طلب الاسترداد أو الإلغاء. تتم مراجعته وإرساله إلى مزوّد الدفع يدويًا. ومع مفتاح sandbox تُعاد النتيجة المحاكاة (environment بالقيمة sandbox)؛ وتُرجع إعادة الطلب بالمفتاح نفسه أيضًا 202.

`Reversal`

الحقل	النوع	مطلوب	الوصف
`id`	`string`	مطلوب	معرّف طلب الاسترداد أو الإلغاء (UUID).
`operation`	`string`	مطلوب	نوع العملية. `refundvoid`
`status`	`string`	مطلوب	دورة حياة طلب الاسترداد أو الإلغاء: تبدأ بالحالة `requested` (بانتظار مشغّل) ثم `awaiting_provider_manual` (تمت الموافقة؛ ويُحجز المبلغ إلى أن يُسجَّل مرجع استرداد مزوّد الدفع) ثم `completed`، أو تنتهي بالحالة `rejected` / `cancelled` (ويُفرَج عن المبلغ المحجوز). أما `processing` و`failed` فقيمتان محجوزتان لا تُستخدمان حاليًا في استردادات المدفوعات. ومع مفتاح sandbox تكون الحالة نهائية فورًا: `completed` (الافتراضية) أو `rejected`. `requestedprocessingcompletedrejectedfailedawaiting_provider_manualcancelled`
`amount`	`string`	مطلوب	المبلغ الكامل للدفعة المستردة بعملة الدفعة نفسها (المبلغ والعملة نفسهما الخاصان بالدفعة وبإشعار `payment.refunded` الخاص بها)، على هيئة سلسلة عشرية بخانتين عشريتين. والحالة requested لا تعني أن الأموال قد تحركت.
`currency`	`string`	مطلوب	عملة `amount`: وهي `currency_code` للدفعة المستردة.
`reason`	`string`	مطلوب	السبب الذي قدّمته.
`provider_reference`	`string \| null`	مطلوب	مرجع استرداد مزوّد الدفع، ويُملأ عند اكتمال الاسترداد عبر POS الحقيقي. وفي sandbox يُعاد مرجع اصطناعي يبدأ بـ `SBX-` عند اكتمال الاسترداد أو الإلغاء المحاكى؛ وهو ليس سجلًا لدى مزوّد الدفع.
`provider_refunded_at`	`string · date-time \| null`	مطلوب	وقت تسجيل استرداد مزوّد الدفع (UTC). وتكون null إلى أن يكتمل يدويًا.
`created_at`	`string · date-time`	مطلوب	وقت الطلب (UTC).
`updated_at`	`string · date-time \| null`	مطلوب	آخر تغيير للحالة (UTC).
`payment_code`	`string \| null`	مطلوب	رمز الدفعة التي ينتمي إليها طلب الاسترداد أو الإلغاء هذا (قيمة `code` المُعادة عند إنشاء الدفعة).
`environment`	`string`	مطلوب	بيئة طلب الاسترداد أو الإلغاء (بيئة مفتاح التوقيع). `livesandbox`

الاستجابة · مثال

{
  "id": "9B2E6F3A-0C1D-4E5F-8A7B-000000000001",
  "operation": "refund",
  "status": "requested",
  "amount": "250.00",
  "currency": "USD",
  "reason": "Customer cancelled the order.",
  "provider_reference": "string",
  "provider_refunded_at": "2026-09-26T09:00:00.000Z",
  "created_at": "2026-09-26T09:00:00.000Z",
  "updated_at": "2026-09-26T09:00:00.000Z",
  "payment_code": "ab34cdef",
  "environment": "live"
}

الأخطاء المحتملة

GET/api/v3/refunds

عرض قائمة الاستردادات

المعاملات

الحقل	النوع	مطلوب	الوصف
`page`	`integer · query`	اختياري	رقم الصفحة. `minimum 1`
`per_page`	`integer · query`	اختياري	عدد العناصر في الصفحة. `minimum 1maximum 100`
`status`	`string · query`	اختياري	تصفية حسب الحالة. `requestedprocessingawaiting_provider_manualcompletedrejectedfailedcancelled`
`operation_type`	`string · query`	اختياري	تصفية حسب العملية. `refundvoid`

الاستجابة · 200

الاستردادات مقسّمة إلى صفحات.

الحقل	النوع	الوصف
`data`	`Reversal[]`
`meta`	`PaginationMeta`

الاستجابة · مثال

{
  "data": [
    {
      "id": "9B2E6F3A-0C1D-4E5F-8A7B-000000000001",
      "operation": "refund",
      "status": "requested",
      "amount": "250.00",
      "currency": "USD",
      "reason": "Customer cancelled the order.",
      "provider_reference": "string",
      "provider_refunded_at": "2026-09-26T09:00:00.000Z",
      "created_at": "2026-09-26T09:00:00.000Z",
      "updated_at": "2026-09-26T09:00:00.000Z",
      "payment_code": "ab34cdef",
      "environment": "live"
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 20,
    "total": 1,
    "total_pages": 1
  }
}

الأخطاء المحتملة

GET/api/v3/refunds/{id}

جلب حالة الاسترداد

المعاملات

الحقل	النوع	مطلوب	الوصف
`id`	`string · uuid · path`	مطلوب	معرّف طلب الاسترداد أو الإلغاء.

الاستجابة · 200

طلب الاسترداد أو الإلغاء.

الكائن: Reversal (الحقول مدرجة في طلب استرداد أو إلغاء).

الاستجابة · مثال

{
  "id": "9B2E6F3A-0C1D-4E5F-8A7B-000000000001",
  "operation": "refund",
  "status": "requested",
  "amount": "250.00",
  "currency": "USD",
  "reason": "Customer cancelled the order.",
  "provider_reference": "string",
  "provider_refunded_at": "2026-09-26T09:00:00.000Z",
  "created_at": "2026-09-26T09:00:00.000Z",
  "updated_at": "2026-09-26T09:00:00.000Z",
  "payment_code": "ab34cdef",
  "environment": "live"
}

الأخطاء المحتملة

الإشعار

عند اكتمال استرداد يُرسل إشعار payment.refunded موقّع إلى عنوان webhook الخاص بالدفعة. الترويسات والتوقيع وإعادة المحاولات هي نفسها في Webhooks. ولا يُرسل void أي إشعار.

POSTpayment.refunded

إشعار payment.refunded موقّع إلى عنوان التاجر

جسم الطلب

الحقل	النوع	مطلوب	الوصف
`event_id`	`string · uuid`	مطلوب
`event_type`	`string`	مطلوب	`payment.refunded`
`environment`	`string`	مطلوب	`sandboxlive`
`occurred_at`	`string · date-time`	مطلوب
`refund`	`object`	مطلوب
`refund.public_id`	`string · uuid`	مطلوب
`refund.status`	`string`	مطلوب	`completed`
`refund.amount`	`string`	مطلوب	مبلغ موجب على هيئة سلسلة عشرية ثابتة المقياس بخانتين عشريتين. القيمة "0.00" غير مقبولة.
`refund.currency_code`	`string`	مطلوب	رمز العملة الورقية، ويقتصر على العملات الأربع المدعومة. `USDEURAEDTRY`
`refund.completed_at`	`string · date-time`	مطلوب	اللحظة نفسها الخاصة بـ `occurred_at`.
`payment`	`object`	مطلوب
`payment.public_id`	`string · uuid`	مطلوب
`payment.code`	`string`	مطلوب	`minLength 1maxLength 16`
`payment.merchant_reference`	`string \| null`	مطلوب	`maxLength 64`
`order`	`object`	مطلوب
`order.public_id`	`string · uuid`	مطلوب

جسم الطلب · مثال

{
  "event_id": "B5D4E456-EFC1-4EC2-A613-D64A16E45BD5",
  "event_type": "payment.refunded",
  "environment": "sandbox",
  "occurred_at": "2026-09-28T12:00:00.000Z",
  "refund": {
    "public_id": "A1B2C3D4-E5F6-4789-8ABC-DEF012345678",
    "status": "completed",
    "amount": "100.00",
    "currency_code": "USD",
    "completed_at": "2026-09-28T12:00:00.000Z"
  },
  "payment": {
    "public_id": "11111111-2222-4333-8444-555555555555",
    "code": "ab34cdef",
    "merchant_reference": "SIP-2026-0001"
  },
  "order": {
    "public_id": "66666666-7777-4888-8999-AAAAAAAAAAAA"
  }
}

السحوبات

اطلب سحب USDT (TRC20) وتابعه.

في الإنتاج، يعني HTTP 201 أن الطلب قُبل وأن المبلغ محجوز، وليس أن USDT قد أُرسلت. تحقق من status وtx_hash وراجع العنوان مرتين: فالتحويل على السلسلة لا يمكن التراجع عنه.

يخصم سحب sandbox من الرصيد الافتراضي ولا يرسل أي شيء على السلسلة إطلاقًا. ويخضع للقواعد نفسها المطبّقة في الإنتاج، بما فيها الحد الأدنى والحد اليومي وسعر التحويل. أرسل X-CAV-Sandbox-Scenario: rejected لاختبار الرفض. تقبل بيئة sandbox عنوان TRON الصفري وجهةً؛ أما الإنتاج فيرفض عناوين الحرق بالرمز 1000030.

يُحدَّد الحد الأدنى والحد اليومي لكل حساب من جهة Manuell؛ وأقل من الحد الأدنى تُرجع الواجهة 9000019، وأكثر من الحد اليومي 9000021. في الإنتاج يرسل أحد مشغّلي Manuell مبلغ USDT ويسجّل tx_hash (sent)، أو يرفض الطلب مع ذكر السبب (rejected) فيعود المبلغ إلى رصيدك.

POST/api/v3/withdrawalsيتطلب Idempotency-Key

طلب سحب USDT

المعاملات

الحقل	النوع	مطلوب	الوصف
`X-CAV-Sandbox-Scenario`	`string · header`	اختياري	لمفاتيح sandbox فقط. يحدد النتيجة المحاكاة: `sent` (الافتراضية) أو `rejected` (دون أي أثر في المحفظة الافتراضية). أما مفتاح الإنتاج الذي يرسل هذه الترويسة، أو أي مفتاح يرسل قيمة أخرى، فيحصل على 422 `1000001`. والترويسة ليست جزءًا من النص الموقَّع؛ لكنها جزء من بصمة Idempotency-Key، ولذلك تُرجع إعادة استخدام مفتاح مع سيناريو آخر 9000010. ويُعاد السيناريو المطبَّق في ترويسة الاستجابة التي تحمل الاسم نفسه. `sentrejected`

جسم الطلب

الحقل	النوع	مطلوب	الوصف
`amount`	`string`	مطلوب	المبلغ المطلوب حجزه من محفظة API بعملة المنصة الأساسية المهيأة، على هيئة سلسلة عشرية بخانتين عشريتين. يحدد مشغّل المنصة الحد الأدنى والحد اليومي لكل حساب: فالمبلغ الأقل من الحد الأدنى يُرجع 9000019 والمبلغ الأكبر من الحد اليومي يُرجع 9000021. اسأل مدير حسابك عن حدودك.
`address`	`string`	مطلوب	عنوان TRON الخاص بك الذي تحققت منه لسحب USDT على شبكة TRC20. المثال عنصر نائب وسيُرفض إذا أُرسل دون تعديل. `maxLength 64`
`address_acknowledged`	`boolean`	مطلوب	يجب أن تكون القيمة true — وبذلك تؤكد أن عنوان الوجهة صحيح وأن التحويل لا يمكن التراجع عنه.

جسم الطلب · مثال

{
  "amount": "250.00",
  "address": "REPLACE_WITH_YOUR_TRON_ADDRESS",
  "address_acknowledged": true
}

الاستجابة · 201

تم طلب السحب. يُحجز الرصيد، ويُنفَّذ الإرسال على السلسلة يدويًا. ومع مفتاح sandbox تُعاد النتيجة المحاكاة (environment بالقيمة sandbox)؛ وتُرجع إعادة الطلب بالمفتاح نفسه أيضًا 201.

`Withdrawal`

الحقل	النوع	مطلوب	الوصف
`id`	`string`	مطلوب	معرّف طلب السحب (UUID).
`status`	`string`	مطلوب	حالة دورة حياة السحب: من `requested` إلى `sent` أو `rejected`. ويُنفّذ مشغّل المنصة الإرسال على السلسلة يدويًا. ومع مفتاح sandbox تكون الحالة نهائية فورًا: `sent` (الافتراضية) أو `rejected`. `requestedsentrejected`
`amount`	`string`	مطلوب	المبلغ المطلوب والمحجوز من محفظة API بعملة المنصة الأساسية، على هيئة سلسلة عشرية بخانتين عشريتين؛ وهو ليس مبلغًا بعملة USDT.
`currency`	`string`	مطلوب	العملة الأساسية التي يُعبَّر بها عن المبلغ.
`asset`	`string`	مطلوب	أصل السحب (USDT).
`network`	`string`	مطلوب	شبكة السحب (TRC20).
`address`	`string`	مطلوب	عنوان الوجهة الذي قدّمته.
`usdt_amount`	`string`	مطلوب	مبلغ USDT المحسوب عند قبول الطلب، على هيئة سلسلة عشرية ثابتة المقياس بست خانات عشرية. ولا يؤكد هذا الحقل وحده حدوث تحويل على السلسلة.
`tx_hash`	`string \| null`	مطلوب	تجزئة (hash) المعاملة على السلسلة، وتُملأ بعد الإرسال. وفي sandbox تُعاد تجزئة اصطناعية من 64 حرفًا لعملية سحب بحالة `sent`؛ ولا يحدث أي تحويل على السلسلة.
`rejection_reason`	`string \| null`	مطلوب	السبب، ويُملأ عند الرفض. وفي sandbox يحمل السحب المرفوض القيمة `Sandbox scenario: rejected`.
`requested_at`	`string · date-time`	مطلوب	وقت الطلب (UTC).
`processed_at`	`string · date-time \| null`	مطلوب	وقت الإرسال أو الرفض (UTC).
`created_at`	`string · date-time`	مطلوب	وقت إنشاء السجل (UTC).
`environment`	`string`	مطلوب	بيئة السحب (بيئة مفتاح التوقيع). `livesandbox`

الاستجابة · مثال

{
  "id": "7F0C2A94-3B1E-4D58-9A6F-1C2D3E4F5A6B",
  "status": "requested",
  "amount": "250.00",
  "currency": "USD",
  "asset": "USDT",
  "network": "TRC20",
  "address": "REPLACE_WITH_YOUR_TRON_ADDRESS",
  "usdt_amount": "249.000000",
  "tx_hash": null,
  "rejection_reason": null,
  "requested_at": "2026-09-26T09:30:00.000Z",
  "processed_at": null,
  "created_at": "2026-09-26T09:30:00.000Z",
  "environment": "live"
}

الأخطاء المحتملة

GET/api/v3/withdrawals

عرض قائمة السحوبات

المعاملات

الحقل	النوع	مطلوب	الوصف
`page`	`integer · query`	اختياري	رقم الصفحة. `minimum 1`
`per_page`	`integer · query`	اختياري	عدد العناصر في الصفحة. `minimum 1maximum 100`
`status`	`string · query`	اختياري	تصفية حسب الحالة. `requestedsentrejected`

الاستجابة · 200

السحوبات مقسّمة إلى صفحات.

الحقل	النوع	الوصف
`data`	`Withdrawal[]`
`meta`	`PaginationMeta`

الاستجابة · مثال

{
  "data": [
    {
      "id": "7F0C2A94-3B1E-4D58-9A6F-1C2D3E4F5A6B",
      "status": "requested",
      "amount": "250.00",
      "currency": "USD",
      "asset": "USDT",
      "network": "TRC20",
      "address": "REPLACE_WITH_YOUR_TRON_ADDRESS",
      "usdt_amount": "249.000000",
      "tx_hash": null,
      "rejection_reason": null,
      "requested_at": "2026-09-26T09:30:00.000Z",
      "processed_at": null,
      "created_at": "2026-09-26T09:30:00.000Z",
      "environment": "live"
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 20,
    "total": 1,
    "total_pages": 1
  }
}

الأخطاء المحتملة

GET/api/v3/withdrawals/{id}

جلب حالة السحب

المعاملات

الحقل	النوع	مطلوب	الوصف
`id`	`string · uuid · path`	مطلوب	معرّف السحب.

الاستجابة · 200

السحب.

الكائن: Withdrawal (الحقول مدرجة في طلب سحب USDT).

الاستجابة · مثال

{
  "id": "7F0C2A94-3B1E-4D58-9A6F-1C2D3E4F5A6B",
  "status": "requested",
  "amount": "250.00",
  "currency": "USD",
  "asset": "USDT",
  "network": "TRC20",
  "address": "REPLACE_WITH_YOUR_TRON_ADDRESS",
  "usdt_amount": "249.000000",
  "tx_hash": null,
  "rejection_reason": null,
  "requested_at": "2026-09-26T09:30:00.000Z",
  "processed_at": null,
  "created_at": "2026-09-26T09:30:00.000Z",
  "environment": "live"
}

الأخطاء المحتملة

النزاعات

اعرض النزاعات وقدّم أدلتك.

تأتي النزاعات من شبكات البطاقات، لذلك تُنشئ نزاعًا تجريبيًا بنفسك في sandbox عبر POST /api/v3/sandbox/disputes. انظر اختبار عمليات الحساب.

يُسجَّل النزاع في Manuell عندما يبلّغ به البنك. يُخصم المبلغ المتنازع عليه من رصيدك (قد يصبح الرصيد سالبًا وتصبح قيمة can_withdraw false) ويُعاد إليك إذا ربحت النزاع. أرسل أدلتك قبل evidence_due_at؛ ويستبدل Idempotency-Key جديد ملاحظتك السابقة ما دام النزاع مفتوحًا.

GET/api/v3/disputes

عرض قائمة النزاعات

المعاملات

الحقل	النوع	مطلوب	الوصف
`page`	`integer · query`	اختياري	رقم الصفحة. `minimum 1`
`per_page`	`integer · query`	اختياري	عدد العناصر في الصفحة. `minimum 1maximum 100`
`status`	`string · query`	اختياري	تصفية حسب الحالة. `openunder_reviewwonlost`

الاستجابة · 200

النزاعات مقسّمة إلى صفحات.

الحقل	النوع	الوصف
`data`	`Dispute[]`
`meta`	`PaginationMeta`

`Dispute`

الحقل	النوع	مطلوب	الوصف
`id`	`string`	مطلوب	معرّف النزاع (UUID).
`service`	`string`	مطلوب	الخدمة التي تنتمي إليها الدفعة المتنازع عليها: `api` لدفعة أُنشئت عبر هذه الواجهة، و`link` لرابط دفع.
`amount`	`string`	مطلوب	المبلغ المتنازع عليه (سلسلة عشرية).
`currency`	`string`	مطلوب	عملة النزاع.
`status`	`string`	مطلوب	حالة النزاع. `openunder_reviewwonlost`
`reason`	`string`	مطلوب	فئة سبب النزاع. `fraudunauthorizedproduct_not_deliveredduplicateamount_mismatchother`
`reason_note`	`string \| null`	مطلوب	ملاحظة سبب البنك كما وردت حرفيًا.
`occurred_on`	`string · date`	مطلوب	تاريخ فتح النزاع (YYYY-MM-DD).
`evidence_due_at`	`string · date-time \| null`	مطلوب	الموعد النهائي لتقديم الأدلة (UTC). يبقى نزاع sandbox مفتوحًا لتقديم الأدلة لمدة 7 أيام بعد إنشائه.
`evidence_submitted_at`	`string · date-time \| null`	مطلوب	وقت تقديم المنصة الدفاع إلى البنك.
`merchant_evidence_note`	`string \| null`	مطلوب	الملاحظة التي أرسلتها.
`merchant_evidence_submitted_at`	`string · date-time \| null`	مطلوب	وقت إرسالك ملاحظتك.
`resolved_at`	`string · date-time \| null`	مطلوب	وقت إغلاق النزاع.
`created_at`	`string · date-time`	مطلوب	وقت إنشاء السجل (UTC).
`payment_code`	`string \| null`	مطلوب	رمز دفعة API التي ينتمي إليها النزاع (قيمة `code` المُعادة عند إنشاء الدفعة)؛ وتكون null إذا لم يكن النزاع مرتبطًا بدفعة API.
`environment`	`string`	مطلوب	بيئة النزاع (بيئة مفتاح التوقيع). `livesandbox`

الاستجابة · مثال

{
  "data": [
    {
      "id": "9B2E6F3A-0C1D-4E5F-8A7B-000000000001",
      "service": "api",
      "amount": "250.00",
      "currency": "USD",
      "status": "open",
      "reason": "fraud",
      "reason_note": "string",
      "occurred_on": "2026-09-26",
      "evidence_due_at": "2026-09-26T09:00:00.000Z",
      "evidence_submitted_at": "2026-09-26T09:00:00.000Z",
      "merchant_evidence_note": "string",
      "merchant_evidence_submitted_at": "2026-09-26T09:00:00.000Z",
      "resolved_at": "2026-09-26T09:00:00.000Z",
      "created_at": "2026-09-26T09:00:00.000Z",
      "payment_code": "ab34cdef",
      "environment": "live"
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 20,
    "total": 1,
    "total_pages": 1
  }
}

الأخطاء المحتملة

GET/api/v3/disputes/{id}

جلب نزاع

المعاملات

الحقل	النوع	مطلوب	الوصف
`id`	`string · uuid · path`	مطلوب	معرّف النزاع.

الاستجابة · 200

النزاع.

الكائن: Dispute (الحقول مدرجة في عرض قائمة النزاعات).

الاستجابة · مثال

{
  "id": "9B2E6F3A-0C1D-4E5F-8A7B-000000000001",
  "service": "api",
  "amount": "250.00",
  "currency": "USD",
  "status": "open",
  "reason": "fraud",
  "reason_note": "string",
  "occurred_on": "2026-09-26",
  "evidence_due_at": "2026-09-26T09:00:00.000Z",
  "evidence_submitted_at": "2026-09-26T09:00:00.000Z",
  "merchant_evidence_note": "string",
  "merchant_evidence_submitted_at": "2026-09-26T09:00:00.000Z",
  "resolved_at": "2026-09-26T09:00:00.000Z",
  "created_at": "2026-09-26T09:00:00.000Z",
  "payment_code": "ab34cdef",
  "environment": "live"
}

الأخطاء المحتملة

POST/api/v3/disputes/{id}/evidenceيتطلب Idempotency-Key

إرسال دليل النزاع

المعاملات

الحقل	النوع	مطلوب	الوصف
`id`	`string · uuid · path`	مطلوب	معرّف النزاع.

جسم الطلب

الحقل	النوع	مطلوب	الوصف
`note`	`string`	مطلوب	نص الدليل الذي تقدّمه للنزاع. `minLength 3maxLength 4000`

جسم الطلب · مثال

{
  "note": "Order 4821 was delivered on 2026-09-25. Carrier reference ABC123."
}

الاستجابة · 200

سُجّل الدليل؛ ولا تتغير حالة النزاع. وتُرجع إعادة الطلب المتطابقة بالمفتاح نفسه جسم الاستجابة الأصلي.

الكائن: Dispute (الحقول مدرجة في عرض قائمة النزاعات).

الاستجابة · مثال

{
  "id": "9B2E6F3A-0C1D-4E5F-8A7B-000000000001",
  "service": "api",
  "amount": "250.00",
  "currency": "USD",
  "status": "open",
  "reason": "fraud",
  "reason_note": "string",
  "occurred_on": "2026-09-26",
  "evidence_due_at": "2026-09-26T09:00:00.000Z",
  "evidence_submitted_at": "2026-09-26T09:00:00.000Z",
  "merchant_evidence_note": "string",
  "merchant_evidence_submitted_at": "2026-09-26T09:00:00.000Z",
  "resolved_at": "2026-09-26T09:00:00.000Z",
  "created_at": "2026-09-26T09:00:00.000Z",
  "payment_code": "ab34cdef",
  "environment": "live"
}

الأخطاء المحتملة

إدارة عمليات التسليم

افحص تسليمات الـ webhook وأعد إرسال الفاشلة.

يُحدَّد عنوان استقبال الإشعارات لكل بيئة في “API Key والتكامل”. تسرد نقاط النهاية أدناه عمليات التسليم وتعيد جدولة الفاشلة منها.

GET/api/v3/webhooks/deliveries

عرض قائمة عمليات تسليم webhook

المعاملات

الحقل	النوع	مطلوب	الوصف
`page`	`integer · query`	اختياري	رقم الصفحة. `minimum 1`
`per_page`	`integer · query`	اختياري	عدد العناصر في الصفحة. `minimum 1maximum 100`
`status`	`string · query`	اختياري	تصفية حسب الحالة. `pendingdeliveredfailed`

الاستجابة · 200

عمليات التسليم مقسّمة إلى صفحات.

الحقل	النوع	الوصف
`data`	`WebhookDelivery[]`
`meta`	`PaginationMeta`

`WebhookDelivery`

الحقل	النوع	الوصف
`id`	`string`	معرّف التسليم (UUID).
`event`	`string`	نوع حدث التسليم: `payment.paid` أو `payment.refunded` أو `payment.failed`. المحاولة الفاشلة ليست نهائية؛ تبقى الدفعة created وقد تُدفع لاحقًا.
`status`	`string`	حالة التسليم. `pendingdeliveredfailed`
`payment_code`	`string \| null`	رمز الدفعة المرتبطة، إن وُجد.
`attempt_count`	`integer`	عدد محاولات التسليم حتى الآن.
`last_status_code`	`integer \| null`	حالة HTTP لآخر محاولة.
`last_error`	`string \| null`	خطأ تسليم خام قديم؛ استخدم last_error_code وlast_error_message.
`last_error_code`	`string \| null`	رمز خطأ تسليم ثابت قابل للقراءة آليًا. `invalid_webhook_targetwebhook_target_private_networkwebhook_environment_invalidwebhook_signing_unavailablewebhook_response_unsuccessfulwebhook_egress_proxy_unreachablewebhook_unreachablewebhook_delivery_failed`
`last_error_message`	`string \| null`	رسالة خطأ تسليم قصيرة مقروءة تُختار عبر Accept-Language.
`next_attempt_at`	`string · date-time \| null`	موعد إعادة المحاولة التالية المجدولة (UTC).
`delivered_at`	`string · date-time \| null`	وقت التسليم (UTC).
`created_at`	`string · date-time`	وقت إنشاء السجل (UTC).

الاستجابة · مثال

{
  "data": [
    {
      "id": "9B2E6F3A-0C1D-4E5F-8A7B-000000000001",
      "event": "payment.paid",
      "status": "pending",
      "payment_code": null,
      "attempt_count": 1,
      "last_status_code": null,
      "last_error": null,
      "last_error_code": null,
      "last_error_message": null,
      "next_attempt_at": null,
      "delivered_at": null,
      "created_at": "2026-09-26T09:00:00.000Z"
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 20,
    "total": 1,
    "total_pages": 1
  }
}

الأخطاء المحتملة

1000001422

GET/api/v3/webhooks/deliveries/{id}

جلب تسليم webhook

المعاملات

الحقل	النوع	مطلوب	الوصف
`id`	`string · uuid · path`	مطلوب	معرّف التسليم.

الاستجابة · 200

التسليم، بما في ذلك url والحمولة (payload).

`WebhookDeliveryDetail`

الحقل	النوع	الوصف
`id`	`string`	معرّف التسليم (UUID).
`event`	`string`	نوع حدث التسليم: `payment.paid` أو `payment.refunded` أو `payment.failed`. المحاولة الفاشلة ليست نهائية؛ تبقى الدفعة created وقد تُدفع لاحقًا.
`status`	`string`	حالة التسليم. `pendingdeliveredfailed`
`payment_code`	`string \| null`	رمز الدفعة المرتبطة، إن وُجد.
`attempt_count`	`integer`	عدد محاولات التسليم حتى الآن.
`last_status_code`	`integer \| null`	حالة HTTP لآخر محاولة.
`last_error`	`string \| null`	خطأ تسليم خام قديم؛ استخدم last_error_code وlast_error_message.
`last_error_code`	`string \| null`	رمز خطأ تسليم ثابت قابل للقراءة آليًا. `invalid_webhook_targetwebhook_target_private_networkwebhook_environment_invalidwebhook_signing_unavailablewebhook_response_unsuccessfulwebhook_egress_proxy_unreachablewebhook_unreachablewebhook_delivery_failed`
`last_error_message`	`string \| null`	رسالة خطأ تسليم قصيرة مقروءة تُختار عبر Accept-Language.
`next_attempt_at`	`string · date-time \| null`	موعد إعادة المحاولة التالية المجدولة (UTC).
`delivered_at`	`string · date-time \| null`	وقت التسليم (UTC).
`created_at`	`string · date-time`	وقت إنشاء السجل (UTC).
`url`	`string`	عنوان webhook الخاص بك لهذا التسليم.
`payload`	`object \| null`	جسم JSON الذي أُرسل.

الاستجابة · مثال

{
  "id": "9B2E6F3A-0C1D-4E5F-8A7B-000000000001",
  "event": "payment.paid",
  "status": "pending",
  "payment_code": null,
  "attempt_count": 1,
  "last_status_code": null,
  "last_error": null,
  "last_error_code": null,
  "last_error_message": null,
  "next_attempt_at": null,
  "delivered_at": null,
  "created_at": "2026-09-26T09:00:00.000Z",
  "url": "string",
  "payload": null
}

الأخطاء المحتملة

9000024404

POST/api/v3/webhooks/deliveries/{id}/retryيتطلب Idempotency-Key

إعادة محاولة تسليم فاشل

المعاملات

الحقل	النوع	مطلوب	الوصف
`id`	`string · uuid · path`	مطلوب	معرّف التسليم.

الاستجابة · 200

أُعيد وضع التسليم الفاشل في قائمة الانتظار. وتُرجع إعادة الطلب المتطابقة بالمفتاح نفسه استجابة وضعه الأصلية في قائمة الانتظار دون محاولة أخرى.

الكائن: WebhookDeliveryDetail (الحقول مدرجة في جلب تسليم webhook).

الاستجابة · مثال

{
  "id": "9B2E6F3A-0C1D-4E5F-8A7B-000000000001",
  "event": "payment.paid",
  "status": "pending",
  "payment_code": null,
  "attempt_count": 1,
  "last_status_code": null,
  "last_error": null,
  "last_error_code": null,
  "last_error_message": null,
  "next_attempt_at": null,
  "delivered_at": null,
  "created_at": "2026-09-26T09:00:00.000Z",
  "url": "string",
  "payload": null
}

الأخطاء المحتملة

أخطاء التسليم

last_error حقل قديم؛ استخدم last_error_code في عمليات التكامل الجديدة.

الحقل	الوصف
`invalid_webhook_target`	هدف webhook غير صالح.
`webhook_target_private_network`	يُحل هدف webhook إلى شبكة خاصة.
`webhook_environment_invalid`	بيئة webhook غير صالحة.
`webhook_signing_unavailable`	تعذّر توقيع webhook.
`webhook_response_unsuccessful`	أعاد الهدف استجابة ليست 2xx.
`webhook_egress_proxy_unreachable`	لا يمكن الوصول إلى وكيل الخروج للتسليم.
`webhook_unreachable`	لا يمكن الوصول إلى هدف webhook.
`webhook_delivery_failed`	فشل تسليم webhook.

حالة الخدمة والصيانة

يمكن وضع بعض الخدمات قيد الصيانة مؤقتًا. ويقتصر التأثير على العمليات الجديدة فقط؛ ويوضح هذا القسم ما يتوقف وما يستمر في العمل وكيفية الاستعلام عن الحالة.

GET/api/v3/service-statusعام

جلب حالة الخدمة

الاستجابة · 200

الخدمات قيد الصيانة (قد تكون القائمة فارغة).

الحقل	النوع	مطلوب	الوصف
`data`	`ServiceStatusItem[]`	مطلوب	الخدمات الموجودة قيد الصيانة حاليًا؛ وتعني القائمة الفارغة عدم وجود أي خدمة منها.

`ServiceStatusItem`

الحقل	النوع	مطلوب	الوصف
`service`	`string`	مطلوب	رمز الخدمة: `api_collection` (المدفوعات المُنشأة عبر الواجهة وصفحات الدفع الخاصة بها)، أو `withdrawals` (طلبات السحب)، أو إحدى القيم `link_collection` و`storefront` و`usdt_sales` و`balance_load` (خدمات أخرى في المنصة). `api_collectionlink_collectionwithdrawalsstorefrontusdt_salesbalance_load`
`until`	`string · date-time \| null`	مطلوب	الوقت المتوقع للعودة (UTC، ISO-8601) أو null. وهو مجرد تقدير: فالصيانة لا تنتهي من تلقاء نفسها، وبعد مرور هذا الوقت تصبح قيمة الحقل null.
`note`	`string \| null`	مطلوب	رسالة نصية قصيرة بسيطة من مشغّل المنصة، أو null. `maxLength 240`

الاستجابة · مثال

{
  "data": [
    {
      "service": "api_collection",
      "until": "2026-10-01T12:00:00Z",
      "note": "Planned maintenance."
    }
  ]
}

استجابات أخرى

429تم تجاوز حد الطلبات.

الأخطاء المحتملة

1000005429

ترقيم الصفحات

تقبل نقاط القوائم page (الافتراضي 1) وper_page (الافتراضي 20 والحد الأقصى 100) وتُرجع data وmeta.

`PaginationMeta`

الحقل	النوع	مطلوب	الوصف
`page`	`integer`	مطلوب	رقم الصفحة (يبدأ من 1).
`per_page`	`integer`	مطلوب	عدد العناصر في الصفحة (1–100).
`total`	`integer`	مطلوب	إجمالي السجلات المطابقة.
`total_pages`	`integer`	مطلوب	ceil(total / per_page).

اختبار عمليات الحساب

يعمل الرصيد والاستردادات والسحوبات والنزاعات في sandbox بنقاط النهاية وأجسام الطلب ورموز الأخطاء نفسها كما في الإنتاج.

تنتقل مدفوعات sandbox فورًا إلى available_amount دون انتظار تاريخ القيمة.
تُحسم طلبات الاسترداد والسحب فورًا. وتحدّد ترويسة X-CAV-Sandbox-Scenario النتيجة.
تأتي النزاعات من البنك، لذلك تُنشئ نزاعًا في sandbox عبر POST /api/v3/sandbox/disputes.

راجع اختبارات الاستردادات والسحوبات والنزاعات في “عمليات البيئة التجريبية”.

اختيار النتيجة

تستخدم طلبات الاسترداد والسحب نقاط النهاية والأجسام نفسها المستخدمة في الإنتاج. لاختيار النتيجة أضف الترويسة الاختيارية X-CAV-Sandbox-Scenario. وهي ليست جزءًا من التوقيع. وعند استخدام مفتاح إنتاج تُرفض الترويسة بالرمز 422 (1000001) حتى لا يتحول اختبار إلى طلب حقيقي أبدًا.

X-CAV-Sandbox-Scenario

X-CAV-Sandbox-Scenario: rejected

نقطة النهاية	قيم الترويسة	الافتراضي	التأثير
`POST /api/v3/refunds`	`completed` `rejected`	`completed`	`completed` يُنهي الاسترداد ويخصم من الرصيد الافتراضي؛ و`rejected` يسجّل الرفض ولا يغيّر شيئًا.
`POST /api/v3/withdrawals`	`sent` `rejected`	`sent`	`sent` يخصم من الرصيد الافتراضي ويملأ `tx_hash` بقيمة نائبة؛ و`rejected` يُفرج عن المبلغ.
`POST /api/v3/sandbox/disputes`	`open` `won` `lost`	`open`	يُحدَّد في جسم الطلب وليس في ترويسة. `open` أو `won` أو `lost`.

نزاع تجريبي

تأتي النزاعات من شبكات البطاقات ولا يمكن بدؤها من جانبك في الإنتاج. هذه هي نقطة النهاية الوحيدة الخاصة بـ sandbox: تنشئ نزاعًا تجريبيًا لدفعة مدفوعة في sandbox وتُرجع كائن Dispute نفسه المستخدم في الإنتاج.

POST/api/v3/sandbox/disputesيتطلب Idempotency-Key

إنشاء نزاع في sandbox لدفعة sandbox مدفوعة

جسم الطلب

الحقل	النوع	مطلوب	الوصف
`payment_code`	`string`	مطلوب	استبدله برمز دفعة مدفوعة أنشأتها بمفتاح sandbox الخاص بك. `maxLength 16`
`scenario`	`string`	اختياري	النتيجة المراد تسجيلها: تبقى `open` (الافتراضية) مفتوحة لتقديم الأدلة؛ أما `won` و`lost` فهما محسومتان بالفعل. `openwonlost`
`reason`	`string`	مطلوب	فئة سبب النزاع؛ وهي القيم نفسها الخاصة بـ `Dispute.reason`. `fraudunauthorizedproduct_not_deliveredduplicateamount_mismatchother`

جسم الطلب · مثال

{
  "payment_code": "ab34cdef",
  "scenario": "open",
  "reason": "fraud"
}

الاستجابة · 201

سُجّل النزاع؛ وتُرجع إعادة الطلب بالمفتاح نفسه النزاع ذاته.

الكائن: Dispute (الحقول مدرجة في عرض قائمة النزاعات).

الاستجابة · مثال

{
  "id": "B5D4E456-EFC1-4EC2-A613-D64A16E45BD5",
  "service": "api",
  "amount": "250.00",
  "currency": "USD",
  "status": "open",
  "reason": "fraud",
  "reason_note": null,
  "occurred_on": "2026-09-30",
  "evidence_due_at": "2026-10-07T09:00:00.000Z",
  "evidence_submitted_at": null,
  "merchant_evidence_note": null,
  "merchant_evidence_submitted_at": null,
  "resolved_at": null,
  "created_at": "2026-09-30T09:00:00.000Z",
  "payment_code": "ab34cdef",
  "environment": "sandbox"
}