حزمة واحدة لـ Android وiOS. تفتح صفحة الدفع داخل WebView بملء الشاشة.
esaalat· Dartأضف الحزمة عبر Flutter.
flutter pub add esaalatwebview_flutter، وتتطلب Android 5+ وiOS 12+.أنشئ العميل مرة واحدة، ثم استدعِ open() مع context جاهز.
1import 'package:esaalat/esaalat.dart';
2
3final checkout = EsaalatCheckout(publishableKey: 'pk_live_...');
4
5Future<void> pay() async {
6 final result = await checkout.open(
7 context,
8 amount: '5000.00',
9 currency: 'YER',
10 externalOrderId: 'order-123',
11 );
12
13 if (result.status == CheckoutResultStatus.verified) {
14 // Show success; fulfil only after payment.verified.
15 }
16}CANCELLED.خيارات constructor وopen(). المبالغ نصوص عشرية.
| الاسم | النوع | مطلوب | الوصف |
|---|---|---|---|
publishableKey | String | مطلوب | من لوحة التحكم ← مفاتيح API. آمن للتضمين، ولا يمكنه إلا إنشاء جلسات دفع. |
locale | EsaalatLocale | اختياري | لغة صفحة الدفع. الافتراضي EsaalatLocale.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 | List<CheckoutItem> | اختياري | بنود الطلب: name وprice، مع description وquantity اختياريين. تحدد العناصر المبلغ. |
externalOrderId | String | اختياري | مرجع طلبك. يعود في النتيجة وفي payment.verified. |
sessionToken | String | اختياري | افتح جلسة أنشأها خادمك بدل إنشاء جلسة في التطبيق. |
portalUrl | String | اختياري | رابط صفحة الدفع لتلك الجلسة. اختياري، وتبنيه الحزمة عند غيابه. |
idempotencyKey | String | اختياري | مفتاح UUID v4 لإعادة المحاولة. أعد استخدامه عند تكرار الإنشاء، ويُنشأ تلقائياً إذا لم يُمرّر. |
simulateResult | CheckoutSimulation | اختياري | نتيجة تجريبية: verified أو underpaid أو overpaid أو cancelled أو expired. تُرفض إذا لم يسمح المفتاح بالمحاكاة. |
pollInterval | Duration | اختياري | الفاصل بين استعلامات WebView عن الجلسة العامة. الافتراضي أربع ثوانٍ. |
تنتهي كل عملية دفع بواحدة من هذه الحالات.
{
"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 وmessage.
استخدم نتيجة SDK لعرض الحالة للمشتري فقط. أكّد الطلب من payment.verified الموقّع قبل إتمامه.