دورة حياة العميل
قرّر مين العميل، وإيه اللي الفورم بيجمعه، وإزاي سجل العميل في XPay بيتطوّر بين الدافعين لمرة واحدة والعملاء العائدين.
الـ العميلAPI هو سجل XPay لحد دفعلك. بيحمل اسمه، وإيميله، وتليفونه، وعنوانه، وإجمالي الإنفاق المربوط بالمعرّفات دي. الصفحة دي عن إزاي السجل ده بيتعمل، ويتعبّى مسبقًا، ويتعاد استخدامه عبر سيناريوهين الدمج اللي على الأرجح هتبنيهم: العملاء اللي عاملين تسجيل دخول، وعمليات دفع الضيوف.
القاعدة الوحيدة اللي بتحرّك كل قرار تحت: سمّي المستخدمين اللي عاملين تسجيل دخول بالـ ID بتاعهم عندك، في externalCustomerId، وسيب الضيوف لـ XPay. عمرك ما هتحتاج تخزّن IDs الـ cus_* بتاعة XPay، وXPay بيتعرّف على الضيوف اللي بيرجعوا لوحده.
نوعَي العميل
XPay بيتتبّع نوعين من سجلات العميل.
| النوع | إمتى بيتعمل | الاستخدام |
|---|---|---|
| مسجَّل | سمّيت العميل بـ externalCustomerId أو customerId، أو عملته من Customers API، أو ظبّطت customerCreation: "always" والعميل دفع. لوحة التحكم بتعدّهم عملاء معروفين. | المستخدم بتاعك دفع وهو عامل تسجيل دخول. سمّيه بالـ ID بتاعه عندك في كل جلسة. |
| ضيف | بيتعمل تلقائيًا أثناء الدفع لما الجلسة ما تسمّيش عميل وcustomerCreation يكون if_required (الافتراضي). XPay بيجمّع الضيوف حسب الإيميل، والتليفون، وبصمة البطاقة علشان يتعرّف على نفس الشخص عبر الزيارات. | دافع لمرة واحدة أو حد ما سجّلش دخوله. ما تخزّنش الـ cus_*: XPay بيربط نفس الضيف عبر الزيارات بدالك. |
النوعين الاتنين بيظهروا في لوحة التحكم. حقول تجميع الضيف (كل إيميل وتليفون استخدمهم، وكل بطاقة دفع بيها) بتتراكم تلقائيًا. لوحة التحكم بتعرض كمان "العملاء المرتبطين" علشان تشوف لما سجل ضيف يتقاطع مع سجل مسجَّل.
نمطين حسب سيناريو التاجر
شكل externalCustomerId، وcustomerDetails، وcustomerCreation اللي بتبعتهم بيعتمد على اللي إنت عارفه عن الشخص اللي بيدفع.
مستخدم عامل تسجيل دخول
ابعت الـ ID بتاع المستخدم عندك في externalCustomerId، واللي تعرفه عنه في customerDetails. أول مرة عميل يقدّم الدفع بالـ ID ده، XPay بيعمل عميل مسجَّل الـ externalId بتاعه هو الـ ID ده. ده بيحصل قبل الدفع، فالعميل بيفضل موجود حتى لو ما كمّلش الدفع. وكل جلسة بعد كده بتلاقي نفس العميل، وبتعبّي الفورم منه، وبتحدّثه بالبيانات اللي بتبعتها. مفيش حاجة تخزّنها عندك.
curl -X POST https://api.xpay.app/checkout/sessions \
-H "Authorization: Bearer sk_test_..." \
-H "Content-Type: application/json" \
-d '{
"afterCompletion": { "type": "redirect", "redirect": { "url": "https://yourshop.example/order/{CHECKOUT_SESSION_ID}" } },
"externalCustomerId": "u_42",
"customerDetails": {
"name": "Aya Hassan",
"email": "aya@example.com",
"phone": "+201234567890"
},
"lineItems": [ { "price": "price_test_xyz", "quantity": 1 } ]
}'علشان تقرا العميل بعدين، نادي GET /customers/external/u_42. ولو إنت بالفعل بتخزّن IDs بتاعة cus_*، تقدر تكمّل تبعتها في customerId؛ وإدّي العملاء دول externalId بـ PATCH /customers/:id علشان تنقل للطريقة الجديدة.
لما جلسة دفع تعمل عميل مسجَّل، من externalCustomerId أو customerCreation: "always"، بيوصلك customer.created. ولما جلسة تغيّره، بالبيانات اللي بتبعتها أو بـ customerUpdate، بيوصلك customer.updated. الضيوف مش بيبعتوا webhooks خاصة بالعميل؛ وcheckout.session.completed بيحمل الضيف.
دفع ضيف
مفيش مستخدم عامل تسجيل دخول. سيب externalCustomerId وcustomerId، واترك customerCreation على الافتراضي (if_required). XPay بينشئ أو بيطابق سجل ضيف بالإيميل، والتليفون، وبصمة البطاقة. مش محتاج تتبّع الـ cus_* على ناحيتك. لوحة التحكم بتجمّع الضيوف تلقائيًا.
curl -X POST https://api.xpay.app/checkout/sessions \
-H "Authorization: Bearer sk_test_..." \
-H "Content-Type: application/json" \
-d '{
"afterCompletion": { "type": "redirect", "redirect": { "url": "https://yourshop.example/order/{CHECKOUT_SESSION_ID}" } },
"lineItems": [ { "price": "price_test_xyz", "quantity": 1 } ]
}'الـ webhook اللي بيتطلق عند النجاح (checkout.session.completed) بيحمل العميل في data.object.customer.
externalCustomerId وcustomerId وcustomerDetails
دي الطرق اللي بتحدّد بيها العميل على الجلسة.
| الحقل | بيعمل إيه | النوع المطلوب |
|---|---|---|
externalCustomerId | الـ ID بتاع العميل عندك. بيستخدم العميل اللي ليه الـ externalId ده، أو بيعمله بيه أول مرة العميل يقدّم الدفع. الفورم بيتعبّى مسبقًا من العميل ده. | مسجَّل |
customerId | بيشير لعميل موجود (cus_*). الفورم بيتعبّى مسبقًا بالاسم، والإيميل، والتليفون، وعنوان الفوترة، والشحن من السجل ده. | مسجَّل |
customerDetails | بيانات تواصل وعنوان مضمَّنة (name، email، phone، billingDetails.address، shipping). بتعبّي الفورم مسبقًا. ومع externalCustomerId بتحدّث العميل اللي اتلاقى. | لا ينطبق |
ابعت واحد بس بالكتير من externalCustomerId وcustomerId. customerDetails بيشتغل مع externalCustomerId، بس مش مع customerId. ولو ما بعتّش ولا حاجة يبقى تمام: الفورم بيبقى فاضي والعميل بيملاه.
customerId لازم يشير لعميل مسجَّل. تمرير cus_* بتاع ضيف بيترفض. مينفعش تسمّي ضيف في جلسة بعدين، ومينفعش يبقى ليه externalId.
الـ externalId مش بيتكرر في حسابك: POST /customers أو PATCH /customers/:id بـ ID عند عميل تاني بيفشل بـ resource_already_exists. وضع الاختبار والوضع الفعلي ليهم عملاء منفصلين، فنفس الـ ID ممكن يكون موجود في الاتنين.
قواعد التعبئة المسبقة
لما الصفحة تتعرض، الفورم بيتعبّى مسبقًا بترتيب أولوية:
customerDetails.{name, email, phone}لو متقدّم.name، وemail، وphone، وaddress، وshippingبتوع العميل الموجود لوcustomerIdأوexternalCustomerIdسمّى عميل.- فاضي غير كده. العميل بيملاه.
حقول الإيميل والتليفون بتبقى مقفولة (للقراءة بس) لما الجلسة تسمّي عميل موجود والسجل يحملها. العميل مينفعش يغيّر إيميل أو تليفون حد تاني في وسط الدفع.
customerCreation
بيتحكم في إمتى XPay بينشئ سجل عميل وقت الدفع. قيمتين؛ الافتراضي if_required.
| القيمة | بيعمل إيه |
|---|---|
if_required | الافتراضي. لما الجلسة ما تسمّيش عميل: لو العميل ملا إيميل أو تليفون، بيتعمل أو بيتطابق عميل ضيف؛ ولو ما ملاش الاتنين، مفيش سجل عميل بيتعمل. |
always | بيتعمل عميل مسجَّل من customerDetails وقت الدفع، حتى لو كتب اسم بس. استخدمه لما تكون عايز حساب معروف محفوظ (زيارات عائدة، إيميلات بعد الشراء). |
customerCreation: "always" مينفعش يتبعت مع customerId أو externalCustomerId. الجلسة اللي بتسمّي عميلها بتقول بالفعل تستخدم مين.
customerUpdate
لما الجلسة تسمّي عميل (customerId أو externalCustomerId)، اللي العميل بيكتبه في الفورم مش بيتكتب رجوعًا للعميل ده افتراضيًا. ظبّط customerUpdate علشان تختار التحديث لكل حقل. كل علم فرعي بيبقى auto (يكتب) أو never (الافتراضي، ما يكتبش).
{
"customerId": "cus_test_AbC123",
"customerUpdate": {
"name": "auto", // overwrite customer.name with the form value
"address": "auto", // overwrite customer.address with the billing address
"shipping": "auto", // overwrite customer.shipping with the shipping address
},
}customerUpdate ليه معنى بس لما الجلسة تسمّي عميل. إرساله من غير customerId أو externalCustomerId بيبقى خطأ تحقّق.
email وphone مش موجودين في customerUpdate لأنهم مقفولين على مستوى الفورم لما العميل الموجود يحملهم. ينفع بس يتـملّوا لما يكونوا ناقصين (شوف إزاي XPay بيتعامل مع العملاء الضيوف).
إيه اللي الفورم بيجمعه
أربعة مفاتيح منطقية بتتحكم في أنهي حقول الفورم المستضاف بيطلبها من العميل. كلها افتراضيًا false.
| المفتاح | بيطلب إيه | مطلوب عند الإرسال؟ |
|---|---|---|
nameCollection | اسم العميل الكامل. | نعم لما يكون مفعّل. |
phoneNumberCollection | تليفون العميل مع رمز الدولة. | نعم لما يكون مفعّل. الإرسال بيفشل بـ parameter_missing على customerDetails.phone لو فاضي. |
billingAddressCollection | اسم حامل البطاقة وعنوان الفوترة الكامل (الشارع، المدينة، المحافظة). | نعم لما يكون مفعّل. الإرسال بيفشل لو customerDetails.billingDetails.address.line1 ناقص. |
shippingAddressCollection | اسم المستلِم وعنوان الشحن. | نعم لما يكون مفعّل. الإرسال بيفشل لو customerDetails.shipping.address.line1 ناقص. |
الإيميل بيتطلب دايمًا ومطلوب دايمًا. هو وجهة الإيصال والمعرّف الأساسي لمنع تكرار الضيوف.
تسمية زر الإرسال بتتظبّط لوحدها عن طريق submitType (pay / subscribe / book / donate).
الحقول المخصّصة
محتاج تطلب رقم ضريبي، أو ملاحظة على الطلب، أو تفضيل توصيل؟ customFields مصفوفة لحد 3 إدخالات. كل واحد بيعرض حقل إدخال على الفورم وإجابة العميل بترجع في رد الجلسة وحمولة الـ webhook.
| نوع الحقل | الإدخال المعروض | التحقّق |
|---|---|---|
TEXT | حقل نص سطر واحد. | minCharacters / maxCharacters اختياري عن طريق hasLimits + limitType. |
NUMBER | حقل أرقام بس. | نفس حدود الأحرف بتنطبق. |
DROPDOWN | قائمة بـ dropdownOptions بيحدّدها التاجر. | خيارين على الأقل مطلوبين. |
CHECKBOX | مربع اختيار واحد العميل بيعلّمه. | مفيش حدود أحرف. |
{
"customFields": [
{
"label": "Tax ID",
"type": "TEXT",
"isOptional": false,
"hasLimits": true,
"limitType": "BETWEEN",
"minCharacters": 9,
"maxCharacters": 15,
},
{
"label": "Delivery preference",
"type": "DROPDOWN",
"dropdownOptions": [{ "label": "Leave at door" }, { "label": "Hand to recipient" }],
},
],
}كل حقل بياخد key ثابت في السيرفر (مشتق من label) علشان الإجابة ترجع على نفس المفتاح في حمولة الرد. القيمة المجمَّعة بتعيش في الخانة المطابقة text / numeric / dropdown على كل إدخال.
إزاي XPay بيتعامل مع العملاء الضيوف
مسار الدفع الافتراضي (من غير customerId، وcustomerCreation: "if_required") بينشئ عميل ضيف أول مرة حد يدفع. نفس الضيف بيتطابق في الزيارات اللي بعدها لما أي معرّف يتقاطع. مش بتكتب أي كود لده.
XPay بيطابق بـ:
- الإيميل، من غير حساسية للأحرف الكبيرة/الصغيرة ومتشال منه الفراغات.
- التليفون، متطبّع (رمز الدولة، وبادئة
00بتتحوّل لـ+). - بصمة البطاقة، بتتلتقط بعد عملية دفع ناجحة. لو ضيف دفع ببطاقة اتشافت على سجل ضيف تاني، XPay بيدمج السجلين في سجل واحد، بكل مدفوعاتهم وإنفاقهم.
ده بيديك إيه في لوحة التحكم:
- ملف الضيف بيتراكم فيه كل إيميل، وتليفون، وبطاقة استخدمهم على مدار الوقت.
- إنفاق الضيف، والمبالغ المستردة، وعدد عمليات الدفع بتبقى دقيقة حتى لو دفع تلات مرات بثلاث فورمات مختلفة شوية.
- قسم "العملاء المرتبطين" في ملف العميل المسجَّل بيعرض سجلات الضيوف اللي بتشاركه بيانات التواصل، علشان تربط بينهم.
تجنّب تكرار سجلات العميل
أكبر طريقة بيقع فيها التجار: إنهم يبعتوا بيانات العميل مع كل طلب من غير ما يقولوا هو مين، فكل طلب يبان كأنه شخص جديد. النمط اللي تحت بيتجنّب ده.
سمّي كل مستخدم عامل تسجيل دخول بالـ ID بتاعه عندك
ظبّط externalCustomerId على الـ ID بتاع المستخدم في كل جلسة بيدفع منها. أول جلسة دفع ليه بتعمل العميل بتاعه، حتى لو ما كمّلش الدفع؛ وكل جلسة بعدها بتستخدمه تاني، والإنفاق بيتجمّع تحت نفس السجل. مش بتخزّن أي حاجة.
const session = await fetch("https://api.xpay.app/checkout/sessions", {
method: "POST",
headers: { Authorization: `Bearer ${process.env.XPAY_SECRET_KEY}`, "Content-Type": "application/json" },
body: JSON.stringify({
afterCompletion: { type: "redirect", redirect: { url: returnUrl } },
externalCustomerId: user.id, // the same ID every time
customerDetails: { name: user.name, email: user.email },
lineItems: [...],
}),
});اقرا العميل بنفس الـ ID
GET /customers/external/:externalId بيرجّع العميل بتاع المستخدم بتاعك. والـ webhooks بتحمل نفس الـ externalId، فالـ handler بتاعك بيعرف مين دفع من غير جدول ربط.
سيب الضيوف لـ XPay
لو مستخدم دفع كضيف الأول (قبل ما يعمل حساب) وبعدين عمل حساب، ابعت الـ ID بتاعه في externalCustomerId في كل جلسة بيدفع فيها وهو عامل تسجيل دخول. XPay بيتعرّف على الضيوف اللي بيرجعوا لوحده. ولو الضيف والعميل المسجَّل بيشاركوا إيميل أو تليفون أو بطاقة، قسم "العملاء المرتبطين" في لوحة التحكم بيوري الربط.
استخدم metadata لأي حاجة تانية
ظبّط metadata على الجلسة لأي حاجة تانية نظامك محتاجها ترجع، زي رقم الطلب. بترجع في الـ webhook، وفي رد استرجاع الجلسة، وعلى الـ Payment Intent.
النتيجة: عميل XPay مسجَّل واحد لكل مستخدم عامل تسجيل دخول، والإنفاق على مدار الوقت بيتجمّع صح، والضيوف بيتتبّعوا لوحدهم من غير ما تضطر تديرهم.
رايح فين بعد كده
بنود الفاتورة والتسعير
إزاي بتشتغل `lineItems` على جلسة الدفع: الأسعار الموجودة ومفاتيح البحث و`priceData` المضمَّن، والـ IDs بتاعة منتجاتك، والكمية الثابتة والقابلة للتعديل، وبنود المبلغ المخصّص، والعملة، وبوابة الإتاحة.
بعد إتمام الدفع
رجّع العميل لموقعك، أو سيب XPay يعرض صفحة شكر مستضافة. بالإضافة لإزاي تتعامل مع عمليات الدفع الفاشلة وليه الـ webhook هو مصدر الحقيقة.