الاسترداد

يعمل الاسترداد بطريقة مختلفة في الوضعين التجريبي والفعلي.

عالج الاسترداد من إشعار Webhook لا من طلبك أنت، فيعمل الكود نفسه في الوضعين.

الاسترداد في الوضع التجريبي

بالمفتاح التجريبي يُحاكى الاسترداد فوراً. أرسل المبلغ المراد استرداده بالدينار مع سبب. يمكنك استرداد جزء من الدفعة ثم المزيد، حتى يُعاد المبلغ كاملاً.

curl -s -X POST "$BRIDGE_URL/api/v1/payments/01a13c8c-8592-70f4-9ef9-d3767e74d54c/refunds" \
  -H "Authorization: Bearer $BRIDGE_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"amount": 10000, "reason": "One item out of stock"}'

يأتي الرد 201 Created بالدفعة كاملة: تكون status بقيمة partially_refunded ما دام جزء من المبلغ متبقياً، وrefunded عندما لا يتبقى شيء، ويزداد refunded_amount، ويظهر الاسترداد الجديد في refunds:

{
  "id": "01a13c8c-8592-70f4-9ef9-d3767e74d54c",
  "status": "partially_refunded",
  "amount": 25000,
  "refunded_amount": 10000,
  "refunds": [
    {"id": 1, "amount": 10000, "source": "api", "provider_reference": "01a13c8c-8595-723d-90e3-978995c21827", "note": "One item out of stock", "created_at": "2026-10-14T22:40:11+00:00"}
  ]
}

(هذا الرد مختصر، والشكل الكامل للدفعة في صفحة الدفعات.) ويُرسل كذلك إشعار Webhook المطابق، payment.partially_refunded أو payment.refunded.

الاسترداد الفعلي

لا يتيح المزوّد الذي تمر به الدفعات الفعلية (APS) واجهة برمجية للاسترداد، لذلك لا تسترد هذه النقطة الدفعات الفعلية. بالمفتاح الفعلي يرد الطلب نفسه بـ 422 أياً كان جسمه، ويشير docs_url إلى صفحة الاسترداد:

{
  "error": {
    "code": "refunds_processed_manually",
    "message": "Live refunds are not made through the API. Request the refund from the application dashboard; it is processed by the payment provider.",
    "docs_url": "https://<your-bridge-domain>/docs/en/refunds"
  }
}

يُطلب الاسترداد الفعلي من لوحة التحكم، من صفحة الدفعة نفسها، ويُسجَّل يدوياً. ومن يحق له الطلب يعتمد على حساب المزوّد الذي يستخدمه تطبيقك:

ما يحدث بعد ذلك:

1. يُنشأ الطلب بمبلغ (كامل أو جزئي) وسبب، وتكون حالته «مطلوب». ولا يمكن أن يتجاوز المبلغ قيمة الدفعة مطروحاً منها الاستردادات المؤكدة والطلبات التي ما زالت مفتوحة.
2. يرسل الجسر الطلب بالبريد الإلكتروني إلى مكتب الاسترداد لدى المزوّد، وهو من يجري الاسترداد.
3. يؤكد المزوّد أو يرفض. عند تأكيد الاسترداد تسجّل ألفابت (أو مالك التطبيق إن كان الحساب خاصاً بك) المرجع الذي أعطاه المزوّد، أو يرى الجسر بنفسه أن المزوّد أبلغ عن الاسترداد. وإن رفض المزوّد، يُغلق الطلب بحالة «مرفوض» مع ملاحظة.
4. الاسترداد المؤكَّد وحده يُحتسب. عندها تصبح الدفعة partially_refunded أو refunded، ويزداد refunded_amount، ويظهر في refunds استرداد بقيمة source: manual، ويُرسل إشعار Webhook.

تعرض لوحة تحكم تطبيقك كل طلب استرداد على صفحة الدفعة، مع مبلغه وسببه وحالته ومن طلبه ومتى.

وإن أبلغ المزوّد عن استرداد لم يطلبه أحد عبر الجسر، تُعلَّم الدفعة refunded، ويصلك payment.refunded ومعه استرداد في refunds بقيمة source: provider_detected، وتراجعه ألفابت.

القواعد

• لا يمكن استرداد إلا الدفعات بحالة paid أو partially_refunded، وإلا ترد الواجهة بـ 409 payment_not_refundable مع الحالة الحالية status.
• استرداد مبلغ أكبر من المتبقي يرد بـ 422 refund_amount_exceeds_refundable مع refundable_amount.
• يعود المبلغ إلى البطاقة التي دفعت، وقد يستغرق ظهوره في كشف حساب العميل بضعة أيام.
• الرسوم لا تُعاد عند الاسترداد.