التوثيق
الدمج

نموذج الكائنات

إزاي موارد XPay بتتركّب مع بعض. اللي بتنشئه، اللي بتقراه، والمعرّفين اللي تحتفظ بيهم في سجل الطلب بتاعك.

الدفعة الناجحة على XPay هي رسم بياني صغير من كائنات مترابطة. أنت بتنشئ الكائن اللي فوق (جلسة الدفع) وبتقرا الباقي كحقول متضمَّنة. الصفحة دي هي النموذج الذهني اللي يتشاف في شاشة واحدة عن إزاي الكائنات دي بتتركّب مع بعض، وأنهي معرّفات هتشوفها، وإيه اللي تحتفظ بيه في سجل الطلب بتاعك.

الكائنات

Checkout Session                           cs_*
├── customer                               cus_*
└── paymentIntent                          pi_*
    ├── charges[]                          ch_*
    │   └── balanceTransaction             txn_*  (the receivable)
    └── refunds[]                          re_*
        └── balanceTransaction             txn_*  (the reversal)
الكائنبيمثّل إيه
Checkout SessionAPIعملية دفع مظبوطة. البنود، وحقول العميل، وسطح الدمج (الصفحة المستضافة، أو drop-in، أو elements). واحدة لكل محاولة عميل.
CustomerAPIسجل المتسوّق. بيانات التواصل والفوترة والشحن. بتتجمّع وقت الدفع، أو بتترتبط بـ customerId لو عندك واحد بالفعل.
Payment IntentAPIالمعاملة. الفلوس المفروض تتحرك، والطريقة المستخدمة، والحالة اللي هي فيها. النظير المالي لجلسة الدفع.
ChargeAPIمحاولة تحريك فلوس. محاولة واحدة لتفويض وتحصيل فلوس على وسيلة دفع العميل. الـ Payment Intent بيبقى ليه أكتر من واحدة لو العميل أعاد المحاولة.
RefundAPIرد فلوس. بيرجّع فلوس للعميل، كامل أو جزئي، مقابل Charge اتحصّل.
Balance TransactionAPIصف في السجل. كل Charge وكل Refund بينتج واحد. القيمة بإشارتها هي اللي بتأثّر على رصيدك.

اللي بتنشئه مقابل اللي بتقراه

أنت بتنشئ جلسات الدفع والمبالغ المستردة. أما Payment Intents وCharges وBalance Transactions فهي موارد للقراءة بس. بتقابلها كحقول متضمَّنة في الردود وكمعرّفات في حمولات الـ webhook، بس الـ API مش بيكشف إنشاء مباشر ليها. كل تدفق دفع بيبدأ عند جلسة دفع.

سطحا الإنشاء الاتنين:

  • POST /checkout/sessions بينتج Checkout SessionAPI. ورا الكواليس، دفعة العميل بتشتغل على Payment Intent، اللي بينتج Charges، اللي بينتجوا Balance Transactions. بتشوفهم كلهم كحقول متضمَّنة على الجلسة، بس ما بتعملش POST لأي واحد فيهم بنفسك.
  • POST /refunds بينتج RefundAPI مقابل pi_* (الـ Payment Intent بتاع الدفعة) أو ch_* (Charge معيّن). قدّم واحد بالظبط. والـ Refund بينتج الـ Balance Transaction الخاص بيه (رد الفلوس).

كل حاجة تانية للقراءة بس. بتجيب جلسة دفع، وبتقرا الـ paymentIntent بتاعها، وبتقرا الـ charges بتاعتها، وبتقرا الـ balance transactions بتاعتهم. عمرك ما بتنشئهم بنفسك.

روابط الدفع ميزة بلا كود بتتعمل في لوحة التحكم. لما عميل يفتح رابط /p/plink_...، XPay بيعمل جلسة الدفع للعميل ده تلقائيًا. وبتفضل تستقبل checkout.session.completed ونفس رسم الكائنات المتضمَّن زي أي عملية دمج تانية.

أنهي معرّفات تخزّن

معرّفين بيعملوا شغلانتين مختلفين. احتفظ بالاتنين في سجل الطلب بتاعك.

  • cs_* هو مرجع الدفع بتاعك. بيحدّد سياق دفع العميل: أنهي بنود اشتراها، وأنهي حقول ملاها، وأنهي سطح دمج استخدم. استخدمه للدعم، والتنقيح، وإعادة عرض طلب العميل في واجهتك أنت.
  • pi_* هو مقبض المعاملة بتاعك. بيحدّد الفلوس: اللي اتخصم، واللي اترد، واللي تسوّى في رصيدك. استخدمه علشان تعمل المبالغ المستردة وتسوّي مقابل التسويات. واحد لكل دفعة ناجحة.

الاتنين بيوصلوا في حمولة checkout.session.completed، فامسكهم في نفس الوقت واحفظ الاتنين. كل واحد هو الأداة الصح لشغلته، ومفيش واحد بيستبدل التاني.

الـ cus_* (لو موجود) هو ثالث معرّف يستاهل الاحتفاظ بيه لما تعوز تلاقي عميل راجع عبر طلبات. وكل حاجة تانية (ch_*، txn_*) ممكن توصلها عند الطلب من GET /checkout/sessions/:id أو GET /refunds/:id ونادرًا ما بتحتاج تعيش في سجل الطلب بتاعك.

إزاي الكائنات بترتبط

جلسة الدفع هي الأب

الجلسة ليها Payment Intent واحد على الأكتر (بيتعمل لما العميل يسلّم النموذج) وعميل واحد على الأكتر (موجود أو اتعمل وقت الدفع). اقرا الجلسة، يبقى عندك الباقي.

Payment Intent بيمسك دورة الحياة

كل محاولة دفع على الجلسة بتعدّي عبر Payment Intent واحد. الإعادة بتعيد استخدامه؛ مش بتطلّع واحد جديد.

Charges وRefunds هي أحداث الفلوس

الـ Charge هو "فلوس دخلت". والـ Refund هو "فلوس رجعت". كل واحد بينتج Balance Transaction، اللي هو الصف اللي بيتسوّى في رصيدك وفي تسوياتك.

Balance Transactions هي السجل

القيمة بإشارتها بتاعت الـ Balance Transaction (موجبة للـ charges، سالبة للـ refunds) هي الحقيقة بخصوص فلوسك. الـ Charges والـ Refunds هي الطريقة اللي بتوصف بيها الحدث؛ والـ Balance Transactions هي الطريقة اللي بيها الحسابات بتتوازن.

إمتى بتدخل على الكائنات الأعمق

لمعظم عمليات الدمج الإجابة هي "نادرًا". الكائنات الأعمق موجودة علشان البيانات تبقى متّسقة وقابلة للتتبّع، مش علشان محتاج تتعامل معاها مباشرة.

محتاج تـ...تعمل إيه
تنفّذ طلب بعد الدفعاقرا cs_* على checkout.session.completed. دي الشغلانة كلها لمعظم عمليات الدمج.
تعمل استرداد من الكودPOST /refunds بالـ pi_*. شوف صفحة دمج المبالغ المستردة.
تبصّ على الـ charge اللي اتنفّذ بالظبطاقرا paymentIntent.charges[] على رد الجلسة.
تسوّي مقابل رصيدك وتسوياتكاقرا paymentIntent.charges[].balanceTransaction. كل واحد بيحمل المبلغ المسوّى، والرسوم، وأنهي تسوية (لو فيه) وقع فيها.
تدوّر على عميل راجعاقرا cs.customer (أو اجلب CustomerAPI بالـ cus_*).

الأحداث اللي بتستقبلها

الحدث الوحيد اللي كل عملية دمج بتستمع له هو checkout.session.completed. الـ data.object بيبقى Checkout SessionAPI كاملة، مطابقة لـ GET /checkout/sessions/:id، مع رسم الكائنات المتضمَّن كله مرفق. الحدث الواحد ده بيكفي علشان تنفّذ الطلب وتمسك كل معرّف ممكن تعوز تخزّنه.

الأحداث التانية (checkout.session.expired، refund.created، charge.refunded) بتبقى مفيدة لما تعوز تتفاعل مع تغييرات دورة حياة معيّنة خارج مسار النجاح. القائمة الكاملة في مرجع الأحداث.

رايح فين بعد كده

مرجع جلسة الدفع

الحقول على الجلسة اللي بتنشئها، ودورة الحياة اللي بتعدّي بيها، وإيه اللي تقدر تظبطه.

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

إزاي تعمل استرداد مقابل pi_* (أو ch_* معيّن). استدعاء API واحد.

إعداد webhook

استقبل checkout.session.completed وتحقق من التوقيع.

اختار طريقة الدمج

اختار السطح اللي بيبني جلسة الدفع: روابط الدفع، أو المستضاف، أو Drop-in، أو Elements.

الإشعارات

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

نظرة عامة

جلسة الدفع هي الكائن المركزي اللي بينشئه أي دمج. نفس الشكل بيرجعلك من POST، وGET، وعميل الـ SDK، ومن كل webhook خاص بـ checkout.session.

في الصفحة دي

الكائناتاللي بتنشئه مقابل اللي بتقراهأنهي معرّفات تخزّنإزاي الكائنات بترتبطإمتى بتدخل على الكائنات الأعمقالأحداث اللي بتستقبلهارايح فين بعد كده