نظرة عامة على ميزة "الدفع المدمج"

للسماح للمستخدمين بإتمام عملية الدفع، عليك تنفيذ عملية دمج ميزة "الدفع المدمج". ويشمل ذلك إنشاء واجهة REST API عادية تتيح لـ Google إدارة عملية الدفع آليًا باستخدام خوادمك. توفّر هذه الطريقة تجربة أكثر سلاسة للمستخدمين. في البداية، ستعرض Google واجهة المستخدم للمشتري، مع خطط مستقبلية لتوفير المزيد من التجارب المستندة إلى الوكلاء.

مسار الدفع

يتطلّب الدمج الأصلي إنشاء واجهة RESTful API يمكن أن تستدعيها Google لإنشاء جلسات الدفع وإدارتها.

يكون المسار العام على النحو التالي:

1. إنشاء جلسة الدفع: يكون المستخدم وربما الوكيل في حلقة لإضافة عناصر إلى الجلسة.
2. تسليم العملية إلى واجهة مستخدم من Google: بعد أن يقرّر المستخدم إكمال عملية الدفع، يسلّم الوكيل (في حال التفاعل معه) التحكّم إلى واجهة مستخدم من Google (مع تمرير بيانات جلسة الدفع).
3. إتمام الدفع يدويًا: يتفاعل المستخدم الآن مع واجهة مستخدم Google فقط لملء تفاصيل الشحن والدفع الحساسة وإرسال الطلب. لا يشارك الوكيل في هذا الجزء، ما يضمن تحديد النتائج.
4. الإكمال والإرجاع: تعرض واجهة المستخدم من Google صفحة "شكرًا لك" لتأكيد الطلب. يمكن إعادة توجيه المستخدم إلى "الوكيل"، الذي ربما تم إعلامه بعملية الشراء المكتملة.

مراحل نشاط حالة جلسة الدفع

أثناء تقدّم المستخدم في مسار عملية الدفع، عليك تعديل جلسة الدفع status لتعكس حالتها الحالية. تنتقل الجلسة خلال دورة الحياة التالية:

• incomplete: هي الحالة الأولية عند إنشاء جلسة. يشير ذلك إلى أنّ المعلومات الإلزامية (مثل طرق الشحن أو الضرائب أو تفاصيل المستخدم) غير متوفّرة أو لم يتم احتسابها.
• ready_for_payment: هي الحالة التي يجب استخدامها بعد أن يعدّل المستخدم عنوان الشحن ويتم احتساب خيارات الشحن والمبالغ الإجمالية، ولكن قبل الانتهاء من إعداد وسيلة الدفع.
• ‫ready_for_complete: هي الحالة التي سيتم استخدامها أثناء عملية إعداد كائن الدفع الكامل، وذلك بعد اختيار وسيلة الدفع والتحقّق من صحة جميع تفاصيل الطلب.
• completed: هي الحالة النهائية التي يتم عرضها بعد معالجة الدفعة وإكمال الطلب بنجاح.
• canceled: هي الحالة التي يتم عرضها في حال تم إلغاء جلسة الدفع.
• ‫error: هي الحالة التي يتم عرضها إذا منع خطأ غير قابل للاسترداد في منطق النشاط التجاري عملية الدفع. تتوفّر هذه الحالة في الإصدار 2026-04-08 والإصدارات الأحدث من "منصة إدارة الشركاء الموحّدة".

مسار الدفع لعدة منتجات:

تتيح Google الآن عناصر متعدّدة ومختلفة في جلسة دفع واحدة. يكون المسار العام على النحو التالي:

1. يبدأ المستخدم عملية الدفع من واجهة مفعّلة باستخدام UCP (مثلاً، من خلال النقر على "الشراء الآن" على أحد المنتجات).
2. يتم تنفيذ طلب البيانات POST /checkout-sessions، بما في ذلك جميع العناصر المميزة في المصفوفة line_items. ستحتوي مصفوفة line_items على عنصر منفصل لكل سلعة فريدة يتم الدفع مقابلها.
3. يمكن للمستخدم تعديل وسيلة الدفع أو تفاصيل التنفيذ أو تطبيق الخصومات باستخدام طلبات PUT /checkout-sessions/{id}.
4. عندما ينقر المستخدم على الزر "الدفع باستخدام GPay"، يتم إجراء طلب POST /checkout-sessions/{id}/complete.

المصادقة

للحصول على تفاصيل حول تأمين نقاط نهاية Native Checkout API، بما في ذلك طرق المصادقة المتوافقة مثل مفاتيح واجهة برمجة التطبيقات وبروتوكول OAuth 2.0، يُرجى الاطّلاع على دليل المصادقة والأمان.

أدوات المطوّرين

للمساعدة في تنفيذ واجهة برمجة التطبيقات Native Checkout API، يمكنك العثور على المراجع التالية في مستودع Universal Commerce Protocol على GitHub:

• مستودع UCP على GitHub: يمكنك الاطّلاع على المستودع الرئيسي للحصول على مستندات ومواصفات شاملة ومراجع خاصة بالمنتدى.
• حِزم تطوير البرامج (SDK): استخدِم حِزم تطوير البرامج لتسريع عملية الدمج. تتوفّر حِزم تطوير برامج (SDK) خاصة بكل لغة، بما في ذلك:
  • حزمة تطوير البرامج (SDK) للغة Python
  • حزمة تطوير البرامج (SDK) في JavaScript

• اختبارات التوافق: يمكنك التحقّق من صحة نقاط نهاية واجهة برمجة التطبيقات مقارنةً بمواصفات UCP باستخدام مجموعة اختبارات التوافق.

  يساعد ذلك في ضمان استيفاء عملية التنفيذ للمعايير والسلوكيات المطلوبة.

ننصحك بشدة باستخدام هذه الأدوات لتبسيط عملية التطوير والاختبار.

أهداف مستوى الخدمة

تنطبق أهداف مستوى الخدمة (SLO) التالية على نقاط نهاية Native Checkout REST API. يُتوقّع من الأنشطة التجارية التي تتكامل مع Google استيفاء هذه الأهداف المتعلّقة بأداء واجهة برمجة التطبيقات وتوفّرها.

نقطة نهاية	مدى التوفّر	وقت الاستجابة (الشريحة المئوية الخمسون)	وقت الاستجابة (الشريحة المئوية الخامسة والتسعون)
POST /checkout-sessions (إنشاء)	‫>= 95%	أقل من أو يساوي ثانية واحدة	‫4 ثوانٍ أو أقل
PUT /checkout-sessions/{id} (تعديل)	‫>= 95%	أقل من أو يساوي ثانية واحدة	‫<= 5 ثوانٍ
POST /checkout-sessions/{id}/complete (مكتمل)	‫>= 95%	‫6 ثوانٍ أو أقل	‫<= 10 ثوانٍ

يشير معدّل الاستجابة عند النسبة المئوية الخمسين إلى أنّه من المتوقّع أن يتم إكمال% 50 على الأقل من الطلبات خلال هذا الوقت. يشير وقت الاستجابة في الشريحة المئوية الخامسة والتسعين إلى أنّه من المتوقّع أن يكتمل% 95 على الأقل من الطلبات خلال هذا الوقت.

الخطوات التالية

اطّلِع على حمولات واجهة برمجة التطبيقات الخاصة بالدفع وتفاصيل التنفيذ الفني لإصدار UCP:

• الإصدار 2026-04-08 من واجهة برمجة تطبيقات REST الأصلية لعملية الدفع
• الإصدار 2026-01-23 من واجهة برمجة تطبيقات REST الأصلية لعملية الدفع

إذا كنت بصدد إجراء عملية الدمج كمقدّم خدمة تابع لجهة خارجية، انتقِل إلى إعداد خدمة "الدفع الموحّد" لاستضافة ملفات التاجرين الشخصية وإعداد عمليات المصافحة الخاصة بعلاقة الحساب.