# نموذج الكائنات (/ar/integrate/object-model)

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

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

## الكائنات [#الكائنات]

```
Checkout Session                           cs_*
├── customer                               cus_*
└── paymentIntent                          pi_*
    ├── charges[]                          ch_*
    │   └── balanceTransaction             txn_*  (the receivable)
    └── refunds[]                          re_*
        └── balanceTransaction             txn_*  (the reversal)
```

| الكائن                                                                                   | بيمثّل إيه                                                                                                                                       |
| ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| <ApiLink href="/api-reference/objects/checkout-session">Checkout Session</ApiLink>       | **عملية دفع مظبوطة.** البنود، وحقول العميل، وسطح الدمج (الصفحة المستضافة، أو drop-in، أو elements). واحدة لكل محاولة عميل.                       |
| <ApiLink href="/api-reference/objects/customer">Customer</ApiLink>                       | **سجل المتسوّق.** بيانات التواصل والفوترة والشحن. بتتجمّع وقت الدفع، أو بتترتبط بـ `customerId` لو عندك واحد بالفعل.                             |
| <ApiLink href="/api-reference/objects/payment-intent">Payment Intent</ApiLink>           | **المعاملة.** الفلوس المفروض تتحرك، والطريقة المستخدمة، والحالة اللي هي فيها. النظير المالي لجلسة الدفع.                                         |
| <ApiLink href="/api-reference/objects/charge">Charge</ApiLink>                           | **محاولة تحريك فلوس.** محاولة واحدة لتفويض وتحصيل فلوس على وسيلة دفع العميل. الـ Payment Intent بيبقى ليه أكتر من واحدة لو العميل أعاد المحاولة. |
| <ApiLink href="/api-reference/objects/refund">Refund</ApiLink>                           | **رد فلوس.** بيرجّع فلوس للعميل، كامل أو جزئي، مقابل Charge اتحصّل.                                                                              |
| <ApiLink href="/api-reference/objects/balance-transaction">Balance Transaction</ApiLink> | **صف في السجل.** كل Charge وكل Refund بينتج واحد. القيمة بإشارتها هي اللي بتأثّر على رصيدك.                                                      |

## اللي بتنشئه مقابل اللي بتقراه [#اللي-بتنشئه-مقابل-اللي-بتقراه]

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

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

* `POST /checkout/sessions` بينتج <ApiLink href="/api-reference/objects/checkout-session">Checkout Session</ApiLink>. ورا الكواليس، دفعة العميل بتشتغل على Payment Intent، اللي بينتج Charges، اللي بينتجوا Balance Transactions. بتشوفهم كلهم كحقول متضمَّنة على الجلسة، بس ما بتعملش `POST` لأي واحد فيهم بنفسك.
* `POST /refunds` بينتج <ApiLink href="/api-reference/objects/refund">Refund</ApiLink> مقابل `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` ونادرًا ما بتحتاج تعيش في سجل الطلب بتاعك.

## إزاي الكائنات بترتبط [#إزاي-الكائنات-بترتبط]

<Cards>
  <Card icon="<ShoppingCart />" title="جلسة الدفع هي الأب">
    الجلسة ليها Payment Intent واحد على الأكتر (بيتعمل لما العميل يسلّم النموذج) وعميل
    واحد على الأكتر (موجود أو اتعمل وقت الدفع). اقرا الجلسة، يبقى عندك الباقي.
  </Card>

  <Card icon="<Layers />" title="Payment Intent بيمسك دورة الحياة">
    كل محاولة دفع على الجلسة بتعدّي عبر Payment Intent واحد. الإعادة بتعيد استخدامه؛ مش
    بتطلّع واحد جديد.
  </Card>

  <Card icon="<ArrowDownToLine />" title="Charges وRefunds هي أحداث الفلوس">
    الـ Charge هو "فلوس دخلت". والـ Refund هو "فلوس رجعت". كل واحد بينتج Balance Transaction،
    اللي هو الصف اللي بيتسوّى في رصيدك وفي تسوياتك.
  </Card>

  <Card icon="<Anchor />" title="Balance Transactions هي السجل">
    القيمة بإشارتها بتاعت الـ Balance Transaction (موجبة للـ charges، سالبة للـ refunds) هي
    الحقيقة بخصوص فلوسك. الـ Charges والـ Refunds هي الطريقة اللي بتوصف بيها الحدث؛ والـ Balance
    Transactions هي الطريقة اللي بيها الحسابات بتتوازن.
  </Card>
</Cards>

## إمتى بتدخل على الكائنات الأعمق [#إمتى-بتدخل-على-الكائنات-الأعمق]

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

| محتاج تـ...                            | تعمل إيه                                                                                                                 |
| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| تنفّذ طلب بعد الدفع                    | اقرا `cs_*` على `checkout.session.completed`. دي الشغلانة كلها لمعظم عمليات الدمج.                                       |
| تعمل استرداد من الكود                  | `POST /refunds` بالـ `pi_*`. شوف صفحة دمج [المبالغ المستردة](/integrate/refunds).                                        |
| تبصّ على الـ charge اللي اتنفّذ بالظبط | اقرا `paymentIntent.charges[]` على رد الجلسة.                                                                            |
| تسوّي مقابل رصيدك وتسوياتك             | اقرا `paymentIntent.charges[].balanceTransaction`. كل واحد بيحمل المبلغ المسوّى، والرسوم، وأنهي تسوية (لو فيه) وقع فيها. |
| تدوّر على عميل راجع                    | اقرا `cs.customer` (أو اجلب <ApiLink href="/api-reference/objects/customer">Customer</ApiLink> بالـ `cus_*`).            |

## الأحداث اللي بتستقبلها [#الأحداث-اللي-بتستقبلها]

الحدث الوحيد اللي كل عملية دمج بتستمع له هو `checkout.session.completed`. الـ `data.object` بيبقى <ApiLink href="/api-reference/objects/checkout-session">Checkout Session</ApiLink> كاملة، مطابقة لـ `GET /checkout/sessions/:id`، مع رسم الكائنات المتضمَّن كله مرفق. الحدث الواحد ده بيكفي علشان تنفّذ الطلب وتمسك كل معرّف ممكن تعوز تخزّنه.

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

## رايح فين بعد كده [#رايح-فين-بعد-كده]

<Cards>
  <Card icon="<Boxes />" title="مرجع جلسة الدفع" href="/integrate/checkout-session/overview">
    الحقول على الجلسة اللي بتنشئها، ودورة الحياة اللي بتعدّي بيها، وإيه اللي تقدر
    تظبطه.
  </Card>

  <Card icon="<RotateCcw />" title="المبالغ المستردة" href="/integrate/refunds">
    إزاي تعمل استرداد مقابل `pi_*` (أو `ch_*` معيّن). استدعاء API واحد.
  </Card>

  <Card icon="<Webhook />" title="إعداد webhook" href="/integrate/webhooks/setting-up-an-endpoint">
    استقبل `checkout.session.completed` وتحقق من التوقيع.
  </Card>

  <Card icon="<User />" title="اختار طريقة الدمج" href="/get-started/choose-your-integration">
    اختار السطح اللي بيبني جلسة الدفع: روابط الدفع، أو المستضاف، أو Drop-in، أو Elements.
  </Card>
</Cards>