الإعدادات المتقدّمة

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

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

نص زر الإرسال

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

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

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

اللغة

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

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

{ "locale": "ar" }

العلامة التجارية

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

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

الشكل:

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

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

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

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

طرق الدفع

افتراضيًا، كل طريقة دفع فعّلتها على حسابك التجاري بتتعرض للعميل. طريقتين لتضييق القائمة لكل جلسة.

الاتنين متعارضين: ابعت واحد أو التاني، مش الاتنين أبدًا. عدم إرسال ولا واحدة بيستخدم تهيئة التاجر الافتراضية.

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

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

القيم اللي تقدر تمرّرها في paymentMethodTypes:

ظهور كل قيمة فعليًا عند الدفع بيعتمد على إنك مفعّلها على حسابك التجاري وعلى إن مبلغ الجلسة يقع داخل حدود المعالج بتاع الطريقة.

أكواد الترويج والخصومات

حقلين مرتبطين. الاتنين بيشتغلوا مع سجلات CouponAPI اللي عملتها في لوحة التحكم.

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

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

// 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 الحالي بيرفض الخصم التاني.

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

الرسوم وتمرير ضريبة القيمة المضافة

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

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

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

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

انتهاء الصلاحية

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

{ "expiresAfterMinutes": 60 }

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

البيانات الوصفية

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

{
  "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 بتاعك يعرف أنهي مستخدم من مستخدمينك دفع من غير ما تربط جداول.

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

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