# الإعدادات المتقدّمة (/ar/integrate/checkout-session/advanced-configuration)

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

الصفحات الفرعية التانية لجلسة الدفع بتغطّي الحقول الأساسية: بنود الفاتورة، والعميل، واللي بيحصل بعد الدفع. الصفحة دي هي الجامعة للباقي: إزاي الصفحة بتظهر (`submitType`، `locale`، `brandingSettings`)، وأنهي طرق دفع بتبان (`paymentMethodTypes`، `paymentMethodConfigurationId`)، وإيه اللي بيتضاف للفاتورة (`feeConfig`، `discounts`)، وقد إيه الجلسة بتفضل مفتوحة (`expiresAfterMinutes`)، ومخزن المفتاح-قيمة الحر اللي تقدر تربطه (`metadata`).

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

## نص زر الإرسال [#نص-زر-الإرسال]

`submitType` بيتحكم في التسمية على زر الدفع في أسفل الفورم المستضاف. الافتراضي `pay`.

| القيمة      | تسمية الزر |
| ----------- | ---------- |
| `pay`       | ادفع       |
| `subscribe` | اشترِك     |
| `book`      | احجز       |
| `donate`    | تبرّع      |

استخدم `donate` لصفحات جمع التبرّعات، و`book` للحجوزات أو المواعيد، و`subscribe` لأي إطار بيع متكرّر. والافتراضي `pay` بيغطّي كل حاجة تانية.

`submitType` بيتم رفضه لما `uiMode: "custom"` (Elements). في الوضع ده إنت بتبني زرّك بنفسك. وهو مقفول كمان عند إنشاء الجلسة: `PATCH` ما بيقبلوش.

## اللغة [#اللغة]

`locale` بيتحكم في لغة الدفع المستضاف وiframe فورم البطاقة. قيمتين النهارده.

| القيمة | اللغة      |
| ------ | ---------- |
| `en`   | الإنجليزية |
| `ar`   | العربية    |

الاستقرار وقت العرض: القيمة على الجلسة بتكسب، بعدها لغتك التجارية الافتراضية (المظبوطة في إعدادات لوحة التحكم)، بعدها الإنجليزية. معامل `locale` بتاع وقت تشغيل الـ SDK (Drop-in / Elements) بيتجاوز كل حاجة لما الصفحة تتعرض جوّه iframe بتاع الـ SDK.

```jsonc
{ "locale": "ar" }
```

## العلامة التجارية [#العلامة-التجارية]

`brandingSettings` بيتجاوز افتراضيات العلامة التجارية على مستوى لوحة التحكم لجلسة واحدة. أي حاجة تظبطها هنا بتكسب؛ وأي حاجة تسيبها بترجع للافتراضي التجاري. الألوان بتندمج مفتاح بمفتاح، فالجلسة تقدر تتجاوز `primary` من غير ما تمسح `background` بتاع التاجر.

```jsonc
{
  "brandingSettings": {
    "colorMode": "light",
    "borderStyle": "rounded",
    "spacing": "normal",
    "inputSize": "medium",
    "inputStyle": "outlined",
    "formLayout": "spacious",
    "fontFamily": "Inter, sans-serif",
    "colors": {
      "primary": "#635bff",
      "background": "#ffffff",
      "foreground": "#0a0a0a",
    },
  },
}
```

الشكل:

| الحقل         | القيم                                         | الغرض                                           |
| ------------- | --------------------------------------------- | ----------------------------------------------- |
| `colorMode`   | `light`، `dark`، `system` (الافتراضي)         | فاتح أو غامق أو يتبع تفضيل نظام تشغيل العميل.   |
| `borderStyle` | `rounded` (الافتراضي)، `sharp`، `pill`        | انحناء الزوايا على الحقول، والأزرار، والبطاقات. |
| `spacing`     | `condensed`، `normal` (الافتراضي)، `spacious` | الكثافة الرأسية للصفحة.                         |
| `inputSize`   | `small`، `medium` (الافتراضي)، `large`        | ارتفاع حقل الفورم.                              |
| `inputStyle`  | `flat`، `outlined` (الافتراضي)، `filled`      | المعالجة البصرية للحقول.                        |
| `formLayout`  | `compact`، `spacious` (الافتراضي)             | كثافة التخطيط لعمود الفورم.                     |
| `fontFamily`  | قيمة CSS font-family                          | تجاوز خط الصفحة. لحد 512 حرف.                   |
| `colors`      | كائن من ألوان hex (شوف تحت)                   | ألوان العلامة التجارية. hex بس.                 |

`colors` بيقبل المفاتيح دي، كل واحد نص hex (`#RGB`، `#RGBA`، `#RRGGBB`، أو `#RRGGBBAA`؛ `#0000` للشفافية):

`primary`، `primaryForeground`، `background`، `foreground`، `border`، `input`، `ring`، `muted`، `mutedForeground`، `accent`، `accentForeground`، `destructive`.

قيم الألوان اللي مش hex بيتم رفضها عند إنشاء الجلسة. `rgb(...)`، والألوان المسمّاة، ومتغيرات CSS مش مقبولين.

لإعداد العلامة التجارية على ناحية التاجر (الشعار، واسم النشاط، والأيقونة المفضّلة)، شوف **الإعدادات ← العلامة التجارية** في لوحة التحكم. الحقول دي مينفعش تتجاوز لكل جلسة.

## طرق الدفع [#طرق-الدفع]

كل طريقة مفعّلة على حسابك بتتعرض للعميل أصلًا. أغلب عمليات الدمج ما بتبعتش أي حقل من الحقلين اللي تحت.

علشان تغيّر الطرق اللي العميل بيشوفها، عدّل التهيئة الافتراضية من **الإعدادات ← طرق الدفع**. بتسري على كل جلسة جديدة، من غير نشر. شوف [طرق الدفع](/features/checkout-customization/payment-methods).

فيه حقلين بيتجاوزوا ده لجلسة واحدة.

| الحقل                          | استخدمه لما                                             |
| ------------------------------ | ------------------------------------------------------- |
| `paymentMethodConfigurationId` | يكون عندك أكتر من تهيئة محفوظة. مرّر الـ `pmc_` بتاعها. |
| `paymentMethodTypes`           | تحتاج قائمة لمرة واحدة لجلسة واحدة.                     |

فضّل الـ configuration ID. قائمة الطرق اللي جوّه التهيئة بتفضل قابلة للتعديل في لوحة التحكم، فتغييرها مايحتاجش نشر.

الاتنين متعارضين: ابعت واحد أو التاني، مش الاتنين أبدًا.

```jsonc
// Restrict this session to card and Valu only
{ "paymentMethodTypes": ["card", "valu"] }
```

كل قيمة لازم تكون مفعّلة على حسابك أصلًا، وإلا الطلب بيفشل بخطأ [`parameter_invalid`](/integrate/errors/api-error-codes#parameter_invalid). الخطأ بيسرد المفعّل عندك فعلًا. راجع **الإعدادات ← طرق الدفع** قبل ما تكتب مصفوفة في الكود.

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

## أكواد الترويج والخصومات [#أكواد-الترويج-والخصومات]

حقلين مرتبطين. الاتنين بيشتغلوا مع سجلات <ApiLink href="/api-reference/objects/coupon">Coupon</ApiLink> اللي عملتها في لوحة التحكم.

`allowPromotionCodes` (منطقي، الافتراضي `false`) بيعرض حقل "أضف كود ترويج" على الفورم المستضاف. العميل بيكتب كود الترويج، والصفحة بتتحقق منه في السيرفر، والخصم بينطبق على إجماليات الجلسة على طول.

`discounts` (مصفوفة، الحد الأقصى 1) بتطبّق كوبون أو كود ترويج مسبقًا. استخدمها للروابط الشخصية أو حملات الخصم لمرة واحدة اللي ما تكونش عايز العميل يكتب فيها أي حاجة.

```jsonc
// Customer enters their own code
{ "allowPromotionCodes": true }

// You apply a specific coupon
{ "discounts": [{ "coupon": "coupon_test_AbC123" }] }

// Or a specific promotion code
{ "discounts": [{ "promotionCode": "promo_test_xyz789" }] }
```

`coupon` أو `promotionCode` لكل إدخال، مش الاتنين أبدًا. رد الجلسة بيحمل الخصم المطبّق (مع لقطة الكوبون) تحت `discounts[]`، و`totalDetails.amountDiscount` بيعكس اللي اتخصم.

قيدين يستاهلوا تعرفهم:

* **بنود المبلغ المخصّص بترفض الخصومات.** الجلسة اللي فيها بند من نوع `CUSTOM` مينفعش تتجمع مع `allowPromotionCodes` أو `discounts`. العميل اختار المبلغ؛ وإضافة كوبون بتكسر الاتفاق.
* **خصم واحد على الأكتر لكل جلسة.** الـ API الحالي بيرفض الخصم التاني.

للسطح الكامل للكوبون وكود الترويج (المدد، وحدود الاستخدام، وقيود العملاء)، شوف صفحة **الكتالوج ← الكوبونات** في لوحة التحكم.

## الرسوم وتمرير ضريبة القيمة المضافة [#الرسوم-وتمرير-ضريبة-القيمة-المضافة]

<Callout type="warn">
  التزامًا باللوائح، تمرير الرسوم (`feesPassThrough: true`) مرهون بموافقة XPay. اتواصل مع مدير حسابك علشان
  تفعّله على حسابك قبل استخدام الإعداد ده.
</Callout>

`feeConfig` بيتجاوز التعامل الافتراضي مع الرسوم على حسابك لجلسة واحدة. ثلاثة حقول.

```jsonc
{
  "feeConfig": {
    "feesPassThrough": true,
    "vatCollectionEnabled": true,
    "vatCollectionRate": 1400,
  },
}
```

| الحقل                  | التأثير                                                                                                                                                        |
| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `feesPassThrough`      | لما يكون `true`، رسوم منصة XPay بتتضاف فوق إجماليات بنود الفاتورة علشان العميل يدفعها بدلًا منك. ولما يكون `false` (الافتراضي)، الرسوم بتتخصم من تسوية التاجر. |
| `vatCollectionEnabled` | لما يكون `true`، ضريبة القيمة المضافة على منتجك بتتضاف فوق علشان العميل يدفعها. المبلغ بيتسوّى ليك ويتتبّع منفصل في رصيدك.                                     |
| `vatCollectionRate`    | معدّل الضريبة بنقاط الأساس. `1400` = 14%. مطلوب لما `vatCollectionEnabled` يكون `true`. المدى من 0 لـ 10000.                                                   |

الاستقرار: `feeConfig` بتاع الجلسة بيكسب، بعدها تهيئة الرسوم الافتراضية لحسابك التجاري (المظبوطة في إعدادات الرسوم في لوحة التحكم)، بعدها افتراضي النظام (من غير تمرير رسوم، من غير ضريبة). رد الجلسة بيحمل كائن `feeConfig` مستقرّ بحقل `source` بيقولك أي مستوى قدّم القيم.

لما `feesPassThrough` أو `vatCollectionEnabled` يكون مفعّل، رد الجلسة بيحمل كمان كائن `fees` بمبلغ رسوم المنصة بالظبط، والنسبة المئوية، و(للبطاقات) تفصيل واعي بالـ BIN. ده اللي هتعرضه في الواجهة بتاعتك لو عايز تعرض رسوم المنصة أو الضريبة كبنود فاتورة منفصلة.

## انتهاء الصلاحية [#انتهاء-الصلاحية]

`expiresAfterMinutes` بيتحكم في قد إيه الجلسة بتفضل مفتوحة قبل ما XPay يعلّمها `expired`. الافتراضي `1440` (24 ساعة). الحد الأدنى `30`. مقفول عند الإنشاء؛ `PATCH` ما بيقبلوش.

```jsonc
{ "expiresAfterMinutes": 60 }
```

لما المؤقّت يخلص، `status` بتاع الجلسة بيتحوّل لـ `expired`، والصفحة المستضافة بتعرض حالة نهائية "خلصت كل حاجة هنا"، وwebhook الـ `checkout.session.expired` بيتطلق. تقدر كمان توقّف صلاحية جلسة بدري بـ `POST /checkout/sessions/:id/expire` (مغطّى في [نظرة عامة ← انتهاء الصلاحية](/integrate/checkout-session/overview#انتهاء-الصلاحية)).

## البيانات الوصفية [#البيانات-الوصفية]

`metadata` هي خريطة مفتاح-قيمة حرة بتربطها بالجلسة. XPay بيخزّنها حرفيًا وعمره ما بيقراها. بتسافر مع الجلسة في كل مكان بتروحه.

```jsonc
{
  "metadata": {
    "user_id": "u_42",
    "order_id": "ord_193",
    "campaign": "spring-sale",
  },
}
```

بتظهر فين:

* في رد استرجاع الجلسة (`GET /checkout/sessions/:id`).
* في حمولة webhook الـ `checkout.session.completed`، في `data.object.metadata`.
* بتتمرّر للـ Payment Intent اللي بيتعمل وقت الدفع، فهي كمان على `paymentIntent.metadata` وعلى كل Charge تحت الـ PI ده.

استخدمها علشان تمرّر معرّفاتك إنت عبر مسار الدفع. أنفع نمط: ظبّط `metadata.user_id` علشان معالِج الـ webhook بتاعك يعرف أنهي مستخدم من مستخدمينك دفع من غير ما تربط جداول.

خلّي القيم نصوص. ما تحطّش بيانات شخصية أو أسرار هنا.

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

<Cards>
  <Card icon="<Webhook />" title="إعداد نقطة نهاية webhook" href="/integrate/webhooks/setting-up-an-endpoint">
    استقبل `checkout.session.completed` واقرا البيانات الوصفية اللي ربطتها.
  </Card>

  <Card icon="<TimerReset />" title="بعد إتمام الدفع" href="/integrate/checkout-session/after-completion">
    اظبط مكان وصول العميل بعد ما الدفع ينجح.
  </Card>

  <Card icon="<Tag />" title="بنود الفاتورة والتسعير" href="/integrate/checkout-session/line-items-and-pricing">
    الأسعار الموجودة مقابل `priceData` المضمَّن، والكميات، والمبالغ المخصّصة.
  </Card>
</Cards>