@xpayeg/sdk

الـ JavaScript SDK بتاع XPay مكتبة صغيّرة بتتحمّل من الـ CDN، وبتديك XPayInstance مكتوب بالأنواع من مفتاحك القابل للنشر. ومنها تقدر تركّب واجهة دفع كـ Elements، أو تفتح drop-in checkout، أو تشغّل initCheckout باستدعاء واحد وتأكّد دفعة.

pnpm add @xpayeg/sdk
# or: npm install @xpayeg/sdk / yarn add @xpayeg/sdk

الـ package بيوفّر بناءات ESM وCJS، زائد أنواع TypeScript كاملة. وقت التشغيل نفسه بيتحمّل عند الطلب من https://checkout.xpay.app/v1/sdk.js.

فيه طريقتين لتحميل الـ SDK، وكل واحدة بتعرض الـ factory باسم مختلف. ده أكتر غلط شائع في التكامل، فخلّيك مظبّطه من البداية:

// استورد loadXPay واعمله await. ده المسار اللي باقي الصفحة بتوثّقه.
import { loadXPay } from "@xpayeg/sdk";

const xpay = await loadXPay("pk_test_...");

<!-- حطّ الـ CDN script tag، وبعدين استدعي الـ factory العام XPay() اللي الـ runtime
     بيحطّه على window. من غير import، ولا await، ولا build step. -->
<script src="https://checkout.xpay.app/v1/sdk.js"></script>
<script>
  const xpay = XPay("pk_test_...");
</script>

loadXPay موجود بس في الـ package بتاع npm؛ والـ CDN runtime بيعرض بس الـ global XPay. مش قابلين للتبديل: استدعاء loadXPay(...) بعد الـ script tag بيرمي ReferenceError: loadXPay is not defined، والـ global XPay مش قابل للاستيراد. اختار الصف اللي يناسب الإعداد بتاعك؛ أي حاجة بعد ما تحصل على نسخة xpay هي نفسها بالظبط. الصفحة دي بتوثّق مدخل npm (loadXPay). على مسار الـ HTML العادي، بدّل await loadXPay(k) بـ XPay(k) في أي مثال تحت.

الصفحة دي مرجع لكل تصدير عام. للشروحات، شوف Drop-in وElements تحت Integrate.

استخدم الـ package ده لما

@xpayeg/sdk هو الـ SDK الـ vanilla وهو الاختيار الصح كل ما تكون مش على React. ده بيغطي:

• HTML العادي والمواقع الثابتة (الـ CDN script tag + الـ factory العام XPay()؛ شوف مساري التحميل فوق).
• Vue، وSvelte، وSolid، وAngular، وLit، وQwik، وAstro، وأي إطار تاني. استدعي الـ SDK من جوّه دورة حياة مكوّن الإطار ده (mount، وonMount، وما يعادل useEffect، إلخ).
• React Native عن طريق WebView لحد ما ينزل package أصلي.
• سكربتات من ناحية السيرفر محتاجة تكتب حمولات الـ clientSecret بالأنواع (أنواع TypeScript بتاعة الـ package مستقلة عن الإطار).

لـ React، @xpayeg/react غلاف راحة رفيع فوق الـ package ده. مبني على loadXPay، وxpay.initCheckout، وxpay.elements، فأي حاجة بتقراها هنا بتنطبق تحت الكواليس هناك كمان.

البداية السريعة

المسار المنصوح بيه هو loadXPay على مستوى الموديول، وبعدين xpay.initCheckout() بمجرد ما يبقى عندك clientSecret من السيرفر بتاعك.

import { loadXPay } from "@xpayeg/sdk";

// Module-level: call once, share across the app.
const xpayPromise = loadXPay("pk_test_...");

async function startCheckout() {
  const xpay = await xpayPromise;
  if (!xpay) return; // SSR returns null on the server

  // initCheckout accepts a Promise<string> too, so you can pass the fetch directly.
  const checkout = await xpay.initCheckout({
    clientSecret: fetch("/api/create-checkout", { method: "POST" })
      .then((r) => r.json())
      .then((d) => d.clientSecret as string),
  });

  // Mount the payment element.
  const elements = checkout.getElements();
  const paymentElement = elements.create("payment");
  paymentElement.mount("#payment-element");

  // Listen for state changes (promo codes, quantity updates, fee recalcs).
  checkout.on("change", (session) => {
    document.getElementById("total")!.textContent =
      `${session.currency} ${(session.amountTotal / 100).toFixed(2)}`;
  });

  // Confirm when the customer submits.
  document.getElementById("pay")!.addEventListener("click", async () => {
    const result = await checkout.confirm({
      customerDetails: { email: "customer@example.com", name: "Aya Hassan" },
    });
    if (result.type === "error") {
      console.error(result.error.message);
      return;
    }
    window.location.href = "/thank-you";
  });
}

التصديرات بنظرة سريعة

loadXPay(publishableKey)

بيحمّل وقت تشغيل الـ SDK من الـ CDN ويرجّع XPayInstance. استدعيه مرة واحدة على مستوى الموديول، مش جوّه مكوّن.

import { loadXPay } from "@xpayeg/sdk";

const xpayPromise = loadXPay("pk_test_...");
// later, when you have a clientSecret:
const xpay = await xpayPromise;
const elements = xpay.elements({ clientSecret: "cs_test_..." });

بيرجّع Promise<XPayInstance | null>. الـ null بيرجع أثناء العرض من ناحية السيرفر (مفيش window). الـ XPayProvider من @xpayeg/react بيتعامل مع الـ null بسلاسة بإعادة المحاولة على العميل.

وقت التشغيل بيتجاب مرة واحدة؛ واستدعاءات loadXPay اللي بعدها بتعيد استخدام نفس الـ script tag. لو فيه سكربت بـ sdk.js موجود أصلًا على الصفحة، ما بيتحقنش تاني.

XPayInstance

الـ factory اللي بيرجعلك من loadXPay. أربع دوال.

interface XPayInstance {
  elements(options: ElementsOptions): Elements;
  checkout(options: CheckoutOptions): CheckoutInstance;
  confirmPayment(options: ConfirmPaymentOptions): Promise<ActionResult>;
  initCheckout(options: InitCheckoutOptions): Promise<InitCheckoutResult>;
}

elements(options)

بينشئ نسخة Elements لواجهة دفع مخصّصة. مرّر له الـ clientSecret من جلسة دفع.

const elements = xpay.elements({
  clientSecret: "cs_test_...",
  appearance: { colorMode: "dark", borderStyle: "rounded" },
  locale: "en",
});

ElementsOptions بيقبل شكل من اتنين. إنشاء الجلسة الأول، بـ clientSecret:

أو مؤجّل، من غير جلسة لسه:

const elements = xpay.elements({
  mode: "payment",
  amount: 149900, // بالوحدات الصغرى
  currency: "EGP",
});

الشكلين ما ينفعش يتجمعوا. في الوضع المؤجّل السيرفر بتاعك بينشئ الجلسة لما العميل يدفع، وبتمرّر الـ clientSecret بتاعها لـ confirmPayment({ elements, clientSecret }). إجمالي الجلسة لازم يساوي المبلغ المعروض، وإلا الدفعة بتترفض بـ amount_reconfirmation_required ومفيش أي مبلغ بيتخصم. شوف Elements: الوضع المؤجّل.

checkout(options)

بينشئ نسخة drop-in checkout. شوف CheckoutOptions تحت.

confirmPayment(options)

بيقدّم دفعة باستخدام البيانات اللي Elements جمّعها. شوف ConfirmPaymentOptions تحت.

initCheckout(options)

الـ API العصري باستدعاء واحد: بيرجّع بيانات الجلسة ودوال الإجراءات مع بعض. شوف InitCheckoutOptions تحت.

Elements

بيرجعه xpay.elements(). بيدير iframe دفع مشترك واحد وبيكشف دوال تعديل الجلسة.

interface Elements {
  create(type: "payment", options?: PaymentElementOptions): PaymentElement;
  getElement(type: "payment"): PaymentElement | null;
  fetchPaymentMethods(): Promise<PaymentMethodInfo[]>;

  on(event: "ready" | "change" | "loaderror" | "error", handler): void;
  off(event: string, handler): void;

  applyPromotionCode(code: string): Promise<ActionResult>;
  removePromotionCode(): Promise<ActionResult>;
  updateLineItemQuantity(args: { lineItem: string; quantity: number }): Promise<ActionResult>;
  submit(): Promise<{ error?: XPayError; selectedPaymentMethod?: string }>;
  fetchUpdates(): Promise<ActionResult>;
  changeAppearance(appearance: Appearance): void;
  update(options: ElementsUpdateOptions): Promise<void>;
  destroy(): void;
}

الأحداث

الدوال

• create("payment", options?): بيرجّع PaymentElement تقدر تركّبه. options.layout بيحدد طريقة عرض المختار، شوف التخطيط.
• getElement("payment"): بيرجّع الـ element الموجود أو null لو ما اتعملش واحد.
• fetchPaymentMethods(): بيرجّع قائمة الـ PaymentMethodInfo اللي الجلسة بتدعمها.
• applyPromotionCode(code): بيطبّق كود خصم، ويرجّع ActionResult.
• removePromotionCode(): بيشيل الكود المطبَّق، ويرجّع ActionResult.
• updateLineItemQuantity({ lineItem, quantity }): بيحدّث بند، ويرجّع ActionResult.
• submit(): بيتحقّق من حقول الـ element. بيرجّع يا إما error أو نص نوع الـ selectedPaymentMethod.
• fetchUpdates(): بيعيد جلب الجلسة من السيرفر وبيرجّع البيانات الجديدة. استخدمه بعد أي تغيير في الجلسة من ناحية السيرفر.
• changeAppearance(appearance): بيحدّث العلامة التجارية في وقت التشغيل من غير ما يعيد إنشاء الـ elements.
• update({ amount, currency }): للوضع المؤجّل بس. بيحدّث المبلغ المعروض لما إجمالي السلة يتغيّر. بيرمي خطأ على النسخ المُنشأة بـ clientSecret؛ مبالغ الجلسة ملك السيرفر.
• destroy(): بيفكّك النسخة ويحرّر الموارد.

PaymentElement

مختار وسيلة الدفع الكامل مع فورم البطاقة، وBNPL، وكشك، ووسائل المحفظة. خُد واحد من elements.create("payment").

interface PaymentElement {
  mount(container: string | HTMLElement): void;
  unmount(): void;
  destroy(): void;
  focus(): void;
  blur(): void;
  collapse(): void;
  update(options: { layout?: "accordion" | "tabs" }): void;

  on(event: "ready" | "loaderstart" | "loaderror", handler): void;
  off(event: string, handler): void;
}

التخطيط (Layout)

elements.create("payment", { layout }) بيتحكم في طريقة عرض مختار وسيلة الدفع:

• "accordion" (الافتراضي): قايمة رأسية، صف لكل وسيلة، وفورم الوسيلة المختارة بيتفتح تحت صفها. لو فيه وسيلة واحدة بس، المختار بيختفي والـ element بيعرض عنوان ثابت (اللوجو والاسم من غير زرار راديو) فوق المحتوى. البطاقة استثناء: حقول الفورم بتاعتها بتعرّف الوسيلة بنفسها، فوسيلة بطاقة واحدة بتترسم فورم من غير عنوان.
• "tabs": شبكة بلاطات، وفورم الوسيلة المختارة تحتها. البلاطات بتتقاسم كل صف بالتساوي وبتنزل صف جديد لما ما تبقاش مكفية، فكل الوسايل باينة دايمًا. لو فيه وسيلة واحدة بس، شبكة البلاطات بتختفي خالص والمحتوى بس هو اللي بيترسم. استخدمه لما صفحتك بتعرض لوجو الوسيلة واسمها بنفسها، زي صف لكل بوابة في إضافة (plugin) للمتجر.

const paymentElement = elements.create("payment", { layout: "tabs" });

تقدر تغيّر التخطيط بعد الإنشاء بـ paymentElement.update({ layout: "accordion" }). التخطيطين بيسيبوا فورم كل وسيلة متركّب، فرقم البطاقة المكتوب بيفضل موجود لو العميل بدّل وسيلة ورجع تاني.

PaymentElementChangeEvent هو الحمولة لحدث "change" بتاع الـ Elements الأب لما يتطلق من تغيير وسيلة دفع:

ConfirmPaymentOptions

الشكل المُمرَّر لـ xpay.confirmPayment() وcheckout.confirm().

دلالات redirect:

• "if_required" بيرجّع النتيجة لكودك؛ وبيحوّل بس لما وسيلة الدفع تتطلّب كده (مثلًا 3-D Secure، وBNPL).
• "always" بيحوّل دايمًا لـ afterCompletion.redirect.url بتاع الجلسة بعد الدفع. الصفحة بتتنقّل بعيد والدالة عمرها ما بترجع عند النجاح.

العنوان هو afterCompletion.redirect.url بتاع الجلسة، اللي بيتحدد لما السيرفر بتاعك ينشئ الجلسة. وXPay بتوجّه ليه من غير ما تضيف عليه حاجة.

في الوضع المؤجّل، إجمالي الجلسة لازم يساوي المبلغ اللي الـ element بيعرضه. إجمالي مختلف بيفشّل التأكيد بـ amount_reconfirmation_required ومفيش أي مبلغ بيتخصم: حدّث مبلغ الـ element وأكّد تاني.

في إعادة المحاولة، مرّر نفس الـ clientSecret: جلسة واحدة لكل عملية دفع بتخلّي دورة حياة العملية كلها على Payment Intent واحد. لو الإجمالي اتغيّر، السيرفر بتاعك بيحدّث الجلسة الموجودة الأول. أنشئ جلسة جديدة بس لما القديمة تموت، والتأكيد بيبلّغ عن ده بـ checkout_session_expired. شوف Elements: إعادة المحاولة.

CheckoutOptions

إعداد الـ drop-in xpay.checkout().

CheckoutInstance

بيرجعه xpay.checkout(). مقبض أمري.

interface CheckoutInstance {
  open(): void; // modal mode
  close(): void;
  destroy(): void;
  on(event: "complete" | "close" | "ready" | "confirmed" | "error", handler): void;
  off(event: string, handler): void;
}

CheckoutCompleteResult (الحمولة لـ onComplete):

InitCheckoutOptions

الـ API العصري باستدعاء واحد. بيدمج elements() مع تحميل الجلسة، وبيكشف بيانات الجلسة زائد دوال الإجراءات على كائن واحد.

const checkout = await xpay.initCheckout({ clientSecret: "cs_test_..." });
console.log(checkout.amountTotal); // session field
const result = await checkout.confirm({ customerDetails: { email } });

InitCheckoutResult هو CheckoutSession & CheckoutActions. دوال الإجراءات على CheckoutActions:

CheckoutSession (نوع بيانات)

بيانات الجلسة المكشوفة للتاجر. مشتقّة من رد السيرفر، مقصوصة على الحقول الموجّهة للتاجر.

presentmentDetails

موجود بس لما المتجر مسعّر بعملة غير عملة المعالجة. بيشيل المبالغ اللي بيشوفها العميل: amountTotal وamountSubtotal وamountDiscount وcurrency وسعر الصرف المثبّت. اقرأ المبالغ من الـ presentment الأول: استخدم presentmentDetails.amountTotal وpresentmentDetails.currency لما الحقل موجود، وamountTotal وcurrency الرئيسيين غير كده.

SessionStatus:

type SessionStatus =
  | { type: "open" }
  | { type: "expired" }
  | { type: "complete"; paymentStatus: "paid" | "unpaid" | "no_payment_required" };

PaymentMethodInfo:

ActionResult وXPayError

كل إجراء بيعدّل الجلسة بيرجّع ActionResult. ده tagged union، فضيّق حسب result.type قبل ما تقرا الحمولة.

type ActionResult<E = XPayError> =
  | { type: "success"; session: CheckoutSession }
  | { type: "error"; error: E };

XPayError هو شكل الخطأ الموحَّد. الحقول الخاصة بالدفع بتبقى null للأخطاء اللي مش دفع.

لدليل التعامل مع أخطاء الـ API وفضاءات أكواد الخطأ التلاتة، شوف الأخطاء، وأكواد أخطاء الـ API، وأكواد أخطاء الدفع، وأكواد الرفض.

Appearance

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

مرّر Appearance لـ xpay.elements()، أو xpay.checkout()، أو xpay.initCheckout(). أو استدعي elements.changeAppearance() / checkout.changeAppearance() علشان تحدّث في وقت التشغيل.

CustomerDetails وAddress

الأشكال لحقول العميل اللي بتجمّعها على فورمك وبتمرّرها وقت التأكيد.

interface CustomerDetails {
  email?: string;
  name?: string;
  phone?: string;
  billingDetails?: { name?: string; email?: string; phone?: string; address?: Address };
  shipping?: { name?: string; phone?: string; address?: Address };
}

interface Address {
  line1?: string;
  line2?: string;
  city?: string;
  state?: string;
  postalCode?: string;
  country?: string;
}

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

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