مرجع العميل

يصف هذا المرجع طرق عميل 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

Resolved: عنصر يحتوي على معلومات حول قدرة المستخدم على الدفع. لمزيد من المعلومات، يمكنك الاطّلاع على IsReadyToPayResponse.

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

الأخطاء

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

loadPaymentData(paymentDataRequest)

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

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

الوسيطات

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

المرتجعات

النوع الوصف
Promise

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

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

الأخطاء

statusCode الوصف
CANCELED
  • المتصفّح الحالي أو مستخدم Google الذي سجّل الدخول غير متوافقَين.
  • أغلق المتسوّق صفحة الدفع في 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

Resolved: عنصر يحتوي على معلومات حول نتائج معاملات الدفع. لمعرفة التفاصيل، يُرجى الاطّلاع على PaymentAuthorizationResult.

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

onPaymentDataChanged(intermediatePaymentData)

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

الوسيطات

مرحبًا
الاسم الوصف
intermediatePaymentData عنصر يحتوي على العنوان المحدّد وخيار الشحن في نموذج الدفع لمعرفة التفاصيل، يُرجى الاطّلاع على IntermediatePaymentData.

المرتجعات

النوع الوصف
Promise

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

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