TypeScript لمتاجر الويب. افتح صفحة الدفع المستضافة في نافذة متصفح أو داخل modal.
esaalat· TypeScriptثبّت الحزمة من npm.
npm install esaalatأنشئ العميل، ثم استدعِ open() من حدث النقر.
1import { EsaalatCheckout } from "esaalat";
2
3const checkout = new EsaalatCheckout({
4 publishableKey: "pk_live_...",
5 locale: "ar",
6});
7
8button.addEventListener("click", async () => {
9 const result = await checkout.open({
10 amount: "5000.00",
11 currency: "YER",
12 externalOrderId: "order-123",
13 });
14
15 if (result.status === "VERIFIED") {
16 // Show success; fulfil only after payment.verified.
17 }
18});presentation: 'modal' لعرض iframe، أو كبديل عند حجب النافذة.خيارات constructor وopen(). المبالغ نصوص عشرية.
| الاسم | النوع | مطلوب | الوصف |
|---|---|---|---|
publishableKey | string | مطلوب | من لوحة التحكم ← مفاتيح API. آمن للتضمين، ولا يمكنه إلا إنشاء جلسات دفع. |
locale | "ar" | "en" | اختياري | لغة صفحة الدفع. الافتراضي ar، وopen({ locale }) يتجاوزها لعملية واحدة. |
presentation | "window" | "modal" | اختياري | الافتراضي window. القيمة modal تعرض الصفحة داخل iframe، وتُستخدم أيضاً عند حجب النافذة المنبثقة. |
apiBaseUrl | string | اختياري | عنوان API الأساسي. الافتراضي https://api.esaalat.com/api/v1. |
portalBaseUrl | string | اختياري | origin البديل لصفحة الدفع عند غياب portal_url من الاستجابة. الافتراضي https://pay.esaalat.com. |
amount | string | اختياري | إجمالي الطلب، مثل "5000.00". مطلوب إذا لم تُمرّر items أو sessionToken. |
items | array | اختياري | بنود الطلب: name وprice، مع description وquantity اختياريين. عند إرسالها يتجاهل الخادم amount. |
externalOrderId | string | اختياري | مرجع طلبك. يعود في النتيجة وفي payment.verified باسم order_id. |
sessionToken | string | اختياري | افتح جلسة أنشأها خادمك بدل إنشاء جلسة في المتصفح. له الأولوية على amount وitems. |
portalUrl | string | اختياري | رابط صفحة الدفع للجلسة التي أنشأها الخادم. اختياري، وتبنيه الحزمة من portalBaseUrl عند غيابه. |
idempotencyKey | string | اختياري | مفتاح UUID v4 لإعادة المحاولة. أعد استخدامه عند تكرار الإنشاء، ويُنشأ تلقائياً إذا لم يُمرّر. |
simulateResult | string | اختياري | نتيجة تجريبية: VERIFIED أو UNDERPAID أو OVERPAID أو CANCELLED أو EXPIRED. تُرفض إذا لم يسمح المفتاح بالمحاكاة. |
تنتهي كل عملية دفع بواحدة من هذه الحالات.
{
"status": "VERIFIED",
"reason": null,
"sessionToken": "640c912d-3ffe-4703-b951-52970c693c41",
"intentCode": "ZR269MP",
"amount": "5000.00",
"paidAmount": null,
"currency": "YER",
"externalOrderId": "order-123",
"merchantName": "Esaalat Store"
}| الحالة | المعنى |
|---|---|
VERIFIED | طابقت الدفعة الطلب، وتم التحقق من المبلغ. |
WRONG_AMOUNT | طابقت الدفعة الطلب، لكن المبلغ مختلف. راجع paidAmount لمعرفة المبلغ الواصل. |
EXPIRED | لم يكمل المشتري الدفع ضمن المهلة. |
CANCELLED | أغلق المشتري صفحة الدفع، أو أُلغيت نية الدفع. |
FAILED | تعذّر تحميل جلسة صالحة لصفحة الدفع. |
VERIFIED لا تعني أن الطلب جاهز للإتمام. أكّد أولاً من payment.verified الموقّع على خادمك.تحدث هذه الأخطاء قبل فتح صفحة الدفع. وإذا فُتحت الصفحة ثم انتهت بحالة غير ناجحة، فستعود النتيجة كـ status، لا كاستثناء.
| الرمز | متى يحدث |
|---|---|
configuration | مفتاح publishableKey مفقود، أو عنوان API غير صالح، أو لا يوجد amount أو items أو sessionToken. |
network | انتهت مهلة الطلب أو تعذّر الوصول إلى API. |
api | أعاد API استجابة غير ناجحة. يتضمن الخطأ حالة HTTP وجسم الاستجابة عندما تدعم المنصة ذلك. |
session | الاستجابة ليست جلسة صالحة، أو الجلسة غير معروفة، أو portalUrl غير صالح. |
unavailable | تعذّر عرض صفحة الدفع، مثلاً لأن activity أو root التطبيق لم يعد موجوداً. |
aborted | أُلغيت العملية قبل أن تكتمل. |
عند الفشل يُرفض الطلب بخطأ EsaalatCheckoutError. راجع code، وstatus لأخطاء HTTP.
استخدم نتيجة SDK لعرض الحالة للمشتري فقط. أكّد الطلب من payment.verified الموقّع قبل إتمامه.