للسماح للمستخدمين بإتمام عملية الدفع، يجب تنفيذ عملية دمج ميزة "الدفع المدمج". يتضمّن ذلك إنشاء واجهة REST API عادية تتيح لـ Google إدارة عملية الدفع آليًا باستخدام الخوادم. وتوفّر هذه الطريقة تجربة أكثر سلاسة للمستخدمين. في البداية، ستعرض Google واجهة المستخدم للمشتري، مع خطط مستقبلية لتوفير تجارب أكثر تفاعلية.
مسار الدفع
يتطلّب الدمج الأصلي إنشاء واجهة RESTful API يمكن أن تستدعيها Google لإنشاء جلسات الدفع وإدارتها.
في ما يلي المسار العام:
- إنشاء جلسة الدفع: يكون المستخدم ووكيل اختياري في حلقة لإضافة عناصر إلى الجلسة.
- تسليم إلى واجهة مستخدم من Google: بعد أن يقرر المستخدم إتمام عملية الدفع، يسلّم الوكيل (إذا كان متفاعلاً) عنصر التحكّم إلى واجهة مستخدم من Google (مع تمرير بيانات جلسة الدفع).
- إتمام الدفع يدويًا: يتفاعل المستخدم الآن مع واجهة مستخدم Google فقط لملء تفاصيل الدفع والتوصيل الحساسة وإرسال الطلب. لا يشارك الوكيل في هذا الجزء، ما يضمن تحديد النتائج.
- الإكمال والإرجاع: تعرض واجهة مستخدم Google صفحة "شكرًا لك" لتأكيد الطلب. يمكن للمستخدم بشكل اختياري إعادة توجيهه إلى "الوكيل" الذي ربما تم إعلامه بعملية الشراء المكتملة.
مراحل نشاط حالة جلسة الدفع
أثناء تقدّم المستخدم في مسار عملية الدفع، عليك تعديل جلسة الدفع status لتعكس حالتها الحالية. تنتقل الجلسة خلال دورة الحياة التالية:
incomplete: هي الحالة الأولية عند إنشاء جلسة. يشير ذلك إلى أنّ المعلومات الإلزامية (مثل طرق الشحن أو الضرائب أو تفاصيل المستخدم) غير متوفّرة أو لم يتم احتسابها.ready_for_payment: هي الحالة التي يجب استخدامها بعد أن يعدّل المستخدم عنوان الشحن ويتم احتساب خيارات الشحن والمبالغ الإجمالية، ولكن قبل الانتهاء من إعداد وسيلة الدفع.-
ready_for_complete: هي الحالة التي سيتم استخدامها أثناء عملية إعداد كائن الدفع الكامل، وذلك بعد اختيار وسيلة الدفع والتحقّق من صحة جميع تفاصيل الطلب. completed: هي الحالة النهائية التي يتم عرضها بعد معالجة الدفعة وتقديم الطلب بنجاح.canceled: هي الحالة التي يتم عرضها في حال تم إلغاء جلسة الدفع.-
error: هي الحالة التي يتم عرضها إذا منع خطأ غير قابل للاسترداد في منطق النشاط التجاري إتمام عملية الدفع. تتوفّر هذه الحالة في الإصدار2026-04-08من UCP والإصدارات الأحدث.
مسار الدفع لعدة منتجات:
يتيح Google الآن عناصر متعدّدة ومختلفة في جلسة دفع واحدة. وتكون العملية العامة على النحو التالي:
- يبدأ المستخدم عملية الدفع من واجهة متوافقة مع "منصة تجربة المستخدم الموحّدة" (على سبيل المثال، من خلال النقر على "الشراء الآن" على أحد المنتجات).
- يتم تنفيذ طلب
POST /checkout-sessions، بما في ذلك جميع العناصر المميزة في مصفوفةline_items. سيحتوي مصفوفةline_itemsعلى عنصر منفصل لكل سلعة فريدة يتم الدفع مقابلها. - يمكن للمستخدم تعديل وسيلة الدفع أو تفاصيل التنفيذ أو تطبيق الخصومات باستخدام طلبات
PUT /checkout-sessions/{id}. - عندما ينقر المستخدم على الزر "الدفع باستخدام GPay"، يتم إجراء طلب
POST /checkout-sessions/{id}/complete.
المصادقة
للحصول على تفاصيل حول تأمين نقاط نهاية Native Checkout API، بما في ذلك طرق المصادقة المتوافقة مثل مفاتيح واجهة برمجة التطبيقات وOAuth 2.0، يُرجى الاطّلاع على دليل المصادقة والأمان.
أدوات المطوّرين
للمساعدة في تنفيذ Native Checkout API، يمكنك العثور على المراجع التالية في مستودع Universal Commerce Protocol على GitHub:
- مستودع UCP على GitHub: يمكنك الاطّلاع على المستودع الرئيسي للحصول على مستندات ومواصفات شاملة ومراجع خاصة بالمنتدى.
- حِزم تطوير البرامج (SDK): استخدِم حِزم تطوير البرامج لتسريع عملية الدمج. تتوفّر حِزم تطوير برامج (SDK) خاصة بكل لغة، بما في ذلك:
اختبارات التوافق: يمكنك التحقّق من صحة نقاط نهاية واجهة برمجة التطبيقات مقارنةً بمواصفات UCP باستخدام مجموعة اختبارات التوافق.
يساعد ذلك في ضمان استيفاء عملية التنفيذ للمعايير والسلوكيات المطلوبة.
ننصحك بشدة باستخدام هذه الأدوات لتبسيط عملية التطوير والاختبار.
أهداف مستوى الخدمة
تنطبق أهداف مستوى الخدمة (SLO) التالية على نقاط نهاية واجهة برمجة التطبيقات REST الخاصة بميزة "الدفع المضمّن". يُتوقّع من الأنشطة التجارية التي تتكامل مع Google استيفاء هذه الأهداف المتعلّقة بأداء واجهة برمجة التطبيقات وتوفّرها.
| نقطة نهاية | مدى التوفّر | وقت الاستجابة (الشريحة المئوية الخمسون) | وقت الاستجابة (الشريحة المئوية الخامسة والتسعون) |
|---|---|---|---|
POST /checkout-sessions (إنشاء) |
>= 95% | <= ثانية واحدة | 4 ثوانٍ أو أقل |
PUT /checkout-sessions/{id} (تعديل) |
>= 95% | <= ثانية واحدة | <= 5 ثوانٍ |
POST /checkout-sessions/{id}/complete (مكتمل) |
>= 95% | 6 ثوانٍ أو أقل | <= 10 ثوانٍ |
يشير معدّل وقت الاستجابة في الشريحة المئوية الخمسين إلى أنّه من المتوقّع أن يكتمل% 50 على الأقل من الطلبات خلال هذا الوقت. يشير وقت الاستجابة عند الشريحة المئوية الخامسة والتسعين إلى أنّه من المتوقّع أن يكتمل% 95 على الأقل من الطلبات خلال هذا الوقت.
الخطوات التالية
اطّلِع على حمولات واجهة برمجة التطبيقات الخاصة بالدفع وتفاصيل التنفيذ الفني لإصدار UCP: