نافذة modal أصلية حول صفحة الدفع المستضافة. ثبّت CheckoutHost مرة واحدة بجوار root التطبيق.
esaalat-react-native· TypeScriptثبّت الحزمة وتبعية WebView الخارجية (peer).
npm install esaalat-react-native react-native-webviewreact-native-webview تبعية peer.ثبّت CheckoutHost مرة واحدة، ثم استدعِ open() من أي شاشة.
1import {
2 CheckoutHost,
3 EsaalatCheckout,
4} from "esaalat-react-native";
5
6const checkout = new EsaalatCheckout({
7 publishableKey: "pk_live_...",
8 locale: "ar",
9});
10
11// Mount once, next to your app root.
12<CheckoutHost checkout={checkout} />;
13
14const result = await checkout.open({
15 amount: "5000.00",
16 currency: "YER",
17 externalOrderId: "order-123",
18});open() معلّقاً حتى تصل النتيجة. وإذا استُدعي مرة ثانية أثناء ظهور modal، يُرفض.خيارات constructor وopen(). لا تتوفر presentation وzIndex.
| الاسم | النوع | مطلوب | الوصف |
|---|---|---|---|
publishableKey | string | مطلوب | من لوحة التحكم ← مفاتيح API. آمن للتضمين، ولا يمكنه إلا إنشاء جلسات دفع. |
locale | "ar" | "en" | اختياري | لغة صفحة الدفع. الافتراضي ar، وopen({ locale }) يتجاوزها. |
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 اختياريين. |
externalOrderId | string | اختياري | مرجع طلبك. يعود في النتيجة وفي payment.verified. |
sessionToken | string | اختياري | افتح جلسة أنشأها خادمك بدل إنشاء جلسة في التطبيق. |
portalUrl | string | اختياري | رابط صفحة الدفع لتلك الجلسة. اختياري، وتبنيه الحزمة عند غيابه. |
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 | أُلغيت العملية قبل أن تكتمل. |
يرفض open() بخطأ EsaalatCheckoutError. عدم تثبيت host هو خطأ configuration.
استخدم نتيجة SDK لعرض الحالة للمشتري فقط. أكّد الطلب من payment.verified الموقّع قبل إتمامه.