Flutter

هذه هي حزمة Flutter الرسمية من Dodo Payments (dodopayments_checkout على pub.dev). توجد أيضًا حزمة منفصلة طوّرها المجتمع، راجع مشاريع المجتمع.

Checkout Sessions API

أنشئ checkout_url الذي تفتحه هذه الحزمة، من الخادم الخلفي لديك.

Mobile Integration Guide

تعرّف على كيفية اندماج ذلك في تدفق الدفع الكامل على الأجهزة المحمولة.

تفتح dodopayments_checkout صفحة الدفع المستضافة من Dodo في SFSafariViewController على iOS وعلامة تبويب Chrome مخصصة على Android — وهي نفس النوى الأصلية المستخدمة في حزم iOS و Android المستقلة. توجد كل منطق الدفع في تلك النوى الأصلية؛ وتمرر طبقة Dart الاستدعاء عبر قناة مكتوبة النوع هي Pigeon. ولا تحتوي على مفتاح API، كما أنها لا تستدعي API الخاص بـ Dodo Payments مطلقًا. يتطلب Flutter 3.44+ / Dart 3.12+، وiOS 16+، وAndroid minSdk 23.

التثبيت

Add the Dependency

pubspec.yaml

dependencies:
  dodopayments_checkout: ^1.0.0

iOS
Android

أضف نوع URL لمخططك في ios/Runner/Info.plist:

ios/Runner/Info.plist

<key>CFBundleURLTypes</key>
<array>
  <dict>
    <key>CFBundleURLName</key>
    <string>myapp</string>
    <key>CFBundleURLSchemes</key>
    <array>
      <string>myapp</string>
    </array>
  </dict>
</array>

بعد ذلك مرّر عناوين URL الواردة (مثلًا عبر app_links) إلى الحزمة، لأن SFSafariViewController لا يمكنه التقاط عنوان URL الخاص بالعودة:

import 'package:dodopayments_checkout/dodopayments_checkout.dart';

DodoCheckout.instance.handleOpenURL(url);

من الآمن تمرير كل عنوان URL هنا. لا يتصرف handleOpenURL إلا مع عناوين URL التي تطابق returnUrl المسجّل لديك، ويحلّ false لأي شيء آخر.

عيّن مخطط استدعاءك كعنصر نائب في بيان Gradle:

android/app/build.gradle

android {
    defaultConfig {
        manifestPlaceholders["dodoCallbackScheme"] = "myapp"
    }
}

إذا كان MainActivity يعيّن android:taskAffinity="" (الإعداد الافتراضي في flutter create)، فأزله أو امنح أنشطة الحزمة نفس الانتماء. وإلا فقد تفقد بعض إصدارات Android من الشركات المصنّعة مسار الدفع الجاري وتعيد PLATFORM_ERROR.

الاستخدام

import 'package:dodopayments_checkout/dodopayments_checkout.dart';

final result = await DodoCheckout.instance.start(
  CheckoutParams(
    checkoutUrl: Uri.parse(checkoutUrl), // from your backend's checkout session
    returnUrl: Uri.parse('myapp://checkout/return'), // scheme must be registered (see Setup)
    onEvent: (event) => print(event.type), // logging only
  ),
);

switch (result.status) {
  case CheckoutStatus.succeeded: showSuccess(result.paymentId);
  case CheckoutStatus.failed:    showFailure();
  case CheckoutStatus.cancelled: dismiss();
  case CheckoutStatus.pending:   showPending();
  case CheckoutStatus.expired:   showExpired();
}

معنى النتيجة

result.status هو تلميح لواجهة المستخدم، وليس دليلًا على الدفع. أكّد كل عملية دفع من الخادم الخلفي لديك، عبر payment.succeeded / subscription.active webhook.

CheckoutStatus

مطلوب

واحد من succeeded، failed، cancelled، pending، expired.

String?

يُعيَّن عند تضمين أحدها في عنوان URL للعودة. اعرضه في واجهة المستخدم، ولا تستخدمه لمنح صلاحية الوصول. راجع قسم التحقق من الدفع أدناه.

String?

يُعيَّن لعمليات دفع الاشتراكات.

List<String>?

يُعيَّن عند تضمين منتجات مفاتيح الترخيص في عملية الدفع.

String?

يُعيَّن عند جمع عنوان بريد إلكتروني في عملية الدفع.

Map<String, String>

كل مَعلمات الاستعلام الواردة من عنوان URL للعودة، حرفيًا.

التحقق من الدفع

Webhooks

يستدعي Dodo Payments خادمك الخلفي عند نجاح عملية دفع أو تفعيل اشتراك.

Get Payment Detail

ابحث عن paymentId باستخدام مفتاحك السري للتحقق من حالته مباشرة.

امنح صلاحية الوصول بعد أن يؤكد أحد هذه العناصر الدفع، ولا تمنحها مطلقًا استنادًا إلى result.status وحده.

الأخطاء

يُطلق start الاستثناء CheckoutException فقط عند إساءة الاستخدام أو حدوث عطل في المنصة. أما عملية الدفع الملغاة أو المرفوضة فهي دائمًا نتيجة وليست استثناءً.

invalidCheckoutUrl (INVALID_CHECKOUT_URL): ليس عنوان URL لجلسة checkout.dodopayments.com.
invalidReturnUrl (INVALID_RETURN_URL): ليس عنوان URL مطلقًا صالحًا.
alreadyInProgress (ALREADY_IN_PROGRESS): توجد عملية دفع قيد التشغيل بالفعل.
platformError (PLATFORM_ERROR): عطل غير متوقع في المنصة.

الجلسات المتروكة

إذا أُغلِق التطبيق أثناء عملية الدفع، فاستعد الجلسة عند التشغيل التالي وطابِقها مع خادمك الخلفي.

import 'package:dodopayments_checkout/dodopayments_checkout.dart';

final abandoned = await DodoCheckout.instance.getAbandonedSession();
if (abandoned != null) {
  // reconcile abandoned.sessionId with your backend, then:
  await DodoCheckout.instance.clearAbandonedSession();
}

Mobile Integration Guide

نفس العقد الخاص بـ Android وiOS وReact Native.

Community Projects

توجد أيضًا حزمة Flutter منفصلة طوّرها المجتمع.

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

Checkout Sessions API

Mobile Integration Guide

التثبيت

الاستخدام

معنى النتيجة

التحقق من الدفع

Webhooks

Get Payment Detail

الأخطاء

الجلسات المتروكة

ذات صلة

Mobile Integration Guide

Community Projects

Checkout Sessions API

Mobile Integration Guide

​التثبيت

​الاستخدام

​معنى النتيجة

​التحقق من الدفع

Webhooks

Get Payment Detail

​الأخطاء

​الجلسات المتروكة

​ذات صلة

Mobile Integration Guide

Community Projects

التثبيت

الاستخدام

معنى النتيجة

التحقق من الدفع

الأخطاء

الجلسات المتروكة

ذات صلة