3 نقاط نهاية
الاستردادات
استرداد كامل أو جزئي لأداء ناجح، بسبب ومرجع من عندكم — يُخصم من رصيد المحفظة ويُقيَّد حركةً مستقلة مرتبطة بالمعاملة الأصلية.
عناوين النقاط وأوصافها تأتي من عقد OpenAPI، بالإنجليزية — فلا يمكن أن تحيد عن الواجهة.
بكلمات بسيطة
إرجاع مال بيعٍ ما، كليًا أو جزئيًا، بشكل نظيف.
متى تستعملونها
فور إلغاء طلب أو إرجاعه أو التنازع عليه. الاسترداد الجزئي ممكن، ويمكن تتابع عدة استردادات ما دام المجموع في حدود الدفعة الأصلية.
كيف تدمجونها
- 1أنشئوا الاسترداد ذاكرين العملية الأصلية ومرجع الاسترداد لديكم.
- 2يعمل المرجع كمفتاح Idempotency: إعادة الاستدعاء نفسه لا تسترد مرتين.
- 3تابعوا الاكتمال عبر الويب هوك — فالاسترداد ليس فوريًا لدى البنك.
- GET
/v1/refundsعرض عمليات الاسترداد - POST
/v1/refundsإنشاء استرداد - GET
/v1/refunds/{reference}استرجاع عملية استرداد
عرض عمليات الاسترداد
يُرجع عمليات الاسترداد الخاصة بكم لبيئة المفتاح، من الأحدث إلى الأقدم، على شكل Page مقسّمة إلى صفحات. يمكن اختيارياً التصفية حسب الحالة (PENDING, SUCCESS, FAILED).
| الحقل | النوع | الموضع | مطلوب | الوصف |
|---|---|---|---|---|
status | enum | query | اختياري | الاستردادات في هذه الحالة فقط.القيم PENDINGSUCCESSFAILED |
pageable | Pageable | query | مطلوب |
إنشاء استرداد
يسترد عملية دفع، كلياً أو جزئياً (refundAmount). حدّدوا عملية الدفع عبر operationId أو externalId. العملية Idempotent (عدم التكرار) على refundReference: إعادة إرسال مرجع سبق تنفيذه تُرجع الاسترداد الموجود (200) دون خصم جديد؛ أما المرجع الجديد فيُرجع 202 Accepted ريثما تتم التسوية.
المخطط · RefundPaymentRequest
| الحقل | النوع | الموضع | مطلوب | الوصف |
|---|---|---|---|---|
operationId | integer (int64) | body | اختياري | |
externalId | string | body | اختياري | |
refundReference | string | body | مطلوب | |
refundAmount | number | body | اختياري | |
reason | string | body | مطلوب | |
note | string | body | اختياري | |
metadata | object | body | اختياري |
استرجاع عملية استرداد
يجلب عملية استرداد عبر refundReference الخاص بكم أو عبر refundId الخاص بالمنصة.
| الحقل | النوع | الموضع | مطلوب | الوصف |
|---|---|---|---|---|
reference | string | path | مطلوب | refundReference الخاص بكم أو refundId الخاص بالمنصة. |
سؤال حول الدمج؟
يجيب فريقنا التقني فرق الإدماج، من أول استدعاء في السندبوكس حتى الانتقال إلى الإنتاج.