مرجع العميل

يصف هذا المرجع طرق عميل JavaScript التي يمكنك استخدامها لتنفيذ Google Pay API في تطبيقات الويب.

الشركة المصنِّعة

تُستخدَم هذه الشركة المصنِّعة لتهيئة عنصر PaymentsClient. يجب استدعاء هذه الشركة المصنِّعة قبل استدعاء طرق الأعضاء.

new PaymentsClient(paymentOptions)

الوسيطات

الموقع الوصف
paymentOptions

عنصر يحتوي على أزواج مفتاح/قيمة لبيانات إعداد Google Pay API راجِع PaymentOptions للاطّلاع على الخصائص المختلفة التي يمكن ضبطها.

مثال: {environment:'PRODUCTION'}

المرتجعات

النوع الوصف
google.payments.api.PaymentsClient عنصر PaymentsClient

عمليات الطرح

النوع الوصف
Error

قيمة سمة البيئة التي تم تمريرها غير مسموح بها.

طرق الكائنات

createButton(options)

تُستخدَم هذه الطريقة المريحة لإنشاء زر دفع Google Pay مصمَّم باستخدام الـ أحدث علامة تجارية لـ Google Pay لإدراجه في صفحة ويب.

يتضمّن HTMLElement الذي تم إنشاؤه ملف CSS تم إدراجه ديناميكيًا وصورة بتنسيق SVG مستضافة على شبكة توصيل المحتوى (CDN) من Google.

راجِع إرشادات العلامة التجارية لمزيد من المعلومات حول كيفية اختيار لون الزر ونوعه المناسبَين لتصميم موقعك الإلكتروني. قد تحتاج إلى تغيير أبعاد الزر لتتطابق مع الأزرار أو عناصر الدفع المماثلة في صفحتك. استخدِم أداة تخصيص الزر لضبط زر لحالة الاستخدام.

الوسيطات

الاسم الوصف
options

عنصر يحتوي على أزواج مفتاح/قيمة لإعدادات الزر راجِع ButtonOptions للاطّلاع على الخصائص التي يمكن ضبطها.

مثال: {onClick:onGooglePaymentButtonClicked}

المرتجعات

النوع الوصف
HTMLElement علامة HTML <button> داخل حاوية محتوى تدفق عام مثل <div>

عمليات الطرح

النوع الوصف
Error

لم يتم ضبط سمة مطلوبة.

isReadyToPay(isReadyToPayRequest)

استخدِم طريقة isReadyToPay(isReadyToPayRequest) لتحديد ما إذا كان بإمكان المستخدم إرجاع طريقة دفع من Google Pay API.

إذا كان المتصفّح يتيح استخدام Google Pay، تعرض isReadyToPay القيمة true. لتحديد ما إذا كان المستخدم مسجّلاً الدخول إلى حساب Google أو سبق له حفظ طريقة دفع في Google Pay، اضبط IsReadyToPayRequest.existingPaymentMethodRequired على true وتأكَّد من أنّ paymentMethodPresent تعرض true في الوعد الذي تم تنفيذه. لمزيد من التفاصيل، راجِع IsReadyToPayResponse.

إذا تم تهيئة PaymentsClient باستخدام سمة بيئة بقيمة TEST، تعرض paymentMethodPresent دائمًا القيمة true.

الوسيطات

الاسم الوصف
isReadyToPayRequest عنصر يحتوي على طرق الدفع التي يتيحها التاجر للحصول على تفاصيل حول الـ خصائص المختلفة التي يمكن ضبطها، راجِع IsReadyToPayRequest.

المرتجعات

النوع الوصف
Promise

تم التنفيذ: عنصر يحتوي على معلومات حول قدرة المستخدم على الدفع لمزيد من المعلومات، راجِع IsReadyToPayResponse.

تم الرفض: عنصر خطأ يحتوي على مزيد من المعلومات حول سبب الرفض. لمزيد من المعلومات، راجِع PaymentsError.

الأخطاء

statusCode الوصف
DEVELOPER_ERROR
  • تم تنسيق عنصر IsReadyToPayRequest الذي تم تمريره بشكلٍ غير صحيح، أو لم يتضمّن الحد الأدنى من المَعلمات المطلوبة لتحديد مدى استعداد المستخدم للدفع، أو يحتوي على مَعلمة و/أو قيمة غير صالحة.
  • تم بدء الطلب من سياق أمان اختار وكيل الدفع أو المتصفّح عدم تنفيذه. ويحدث ذلك غالبًا بسبب خطأ في سياق المتصفّح غير الآمن.

loadPaymentData(paymentDataRequest)

تعرض هذه الطريقة ورقة دفع Google Pay تتيح اختيار طريقة دفع ومَعلمات تم ضبطها اختياريًا.

يجب استدعاء هذه الطريقة أثناء معالجة المتصفّح لـ سلوك تفعيل نتيجةً لحدث ناتج عن النقر. قد يتم عرض نافذة منبثقة للمستخدم لاختيار طريقة دفع أو بيانات أخرى مطلوبة محدّدة في مَعلمة الطلب التي تم تمريرها.

الوسيطات

الاسم الوصف
paymentDataRequest عنصر يحتوي على أزواج مفتاح/قيمة لإعدادات Google Pay API الكاملة راجِع PaymentDataRequest للاطّلاع على الخصائص التي يمكن ضبطها.

المرتجعات

النوع الوصف
Promise

تم التنفيذ: عنصر يحتوي على بيانات المتسوّق المطلوبة راجِع PaymentData لمزيد من المعلومات.

تم الرفض: عنصر يحتوي على رمز خطأ ومزيد من المعلومات حول سبب الرفض. راجِع PaymentsError لمزيد من المعلومات.

الأخطاء

statusCode الوصف
CANCELED
  • لا يتيح المتصفّح الحالي أو مستخدم Google الذي تم تسجيل الدخول إليه استخدام Google Pay.
  • أغلق المتسوّق ورقة دفع Google Pay بدون منح إذن الدفع.
  • تم بدء الطلب من سياق أمان اختار وكيل الدفع أو المتصفّح عدم تنفيذه. ويحدث ذلك غالبًا بسبب سياق المتصفّح غير الآمن .
  • تم استدعاء الطريقة أثناء عرض ورقة دفع Google Pay.
  • تم رفض عنصر PaymentDataRequest الذي تم تمريره من قِبل ورقة دفع Google Pay. يُعدّ عدم توفّر مَعلمات PaymentMethodTokenizationSpecification أو عدم اكتمالها لبوابتك أو قيم المَعلمات غير الصالحة سببًا شائعًا.
DEVELOPER_ERROR تم تنسيق عنصر PaymentDataRequest الذي تم تمريره بشكلٍ غير صحيح، أو لم يتضمّن الحد الأدنى من المَعلمات المطلوبة، أو يحتوي على مَعلمة و/أو قيمة غير صالحة.

prefetchPaymentData(paymentDataRequest)

استخدِم هذه الطريقة لإجراء جلب مسبق لإعدادات PaymentDataRequest لتحسين loadPaymentData وقت التنفيذ عند تفاعل المستخدم لاحقًا. لا يتم عرض أي قيمة.

تتوفّر تحسينات الجلب المسبق على Chrome لنظام Android.

الوسيطات

الاسم الوصف
paymentDataRequest عنصر يحتوي على أزواج مفتاح/قيمة لإعدادات Google Pay API الكاملة راجِع PaymentDataRequest للاطّلاع على الخصائص التي يمكن ضبطها. لا يؤثر تغيير سمة transactionInfo في قيمة الجلب المسبق المخزّنة مؤقتًا.

برامج معاودة الاتصال لبيانات الدفع

يمكن تمرير معالِجات معاودة الاتصال التالية إلى PaymentOptions.paymentDataCallbacks لدعم تفويض الدفعات وتعديلات الأسعار الديناميكية.

onPaymentAuthorized(paymentData)

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

الوسيطات

الاسم الوصف
paymentData عنصر يحتوي على بيانات المتسوّق المطلوبة للحصول على التفاصيل، راجِع PaymentData.

المرتجعات

النوع الوصف
Promise

تم التنفيذ: عنصر يحتوي على معلومات حول نتائج معاملة الدفع للحصول على التفاصيل، راجِع PaymentAuthorizationResult.

تم الرفض: عنصر خطأ يحتوي على هدف ورسالة خطأ سيتم عرضهما في ورقة الدفع. للحصول على التفاصيل، راجِع PaymentDataError.

onPaymentDataChanged(intermediatePaymentData)

تتعامل هذه الطريقة مع تغييرات بيانات الدفع في ورقة الدفع، مثل عنوان الشحن و خيارات الشحن.

الوسيطات

الاسم الوصف
intermediatePaymentData عنصر يحتوي على العنوان وخيار الشحن المحدّدَين في ورقة الدفع للحصول على التفاصيل، راجِع IntermediatePaymentData.

المرتجعات

النوع الوصف
Promise

تم التنفيذ: عنصر يحتوي على معلومات حول معلومات المعاملة الجديدة، خيارات الشحن وأخطاء بيانات الدفع. للحصول على التفاصيل، راجِع PaymentDataRequestUpdate.

تم الرفض: عنصر خطأ يحتوي على هدف ورسالة خطأ سيتم عرضهما في ورقة الدفع. للحصول على التفاصيل، راجِع PaymentDataError.