كائنات الاستجابة

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

IsReadyToPayResponse

يوفّر هذا العنصر معلومات حول إمكانية زائر الموقع الإلكتروني تقديم معلومات الدفع إلى الموقع الإلكتروني الذي يطلبها.

الموقع النوع موجود دائمًا الوصف
result قيمة منطقية نعم يمكن للزائر الحالي تقديم معلومات الدفع إلى الموقع الإلكتروني الذي يطلبها. قد تكون قدرة الزائر على الدفع مرتبطة بقدرة متصفّح الويب على عرض المكوّنات المطلوبة لطرق الدفع المحدّدة. ويشمل ذلك الحالات التي يسجّلون فيها الدخول إلى حساب Google ويقدّمون طريقة دفع.
paymentMethodPresent قيمة منطقية لا

إذا كانت القيمة true، يعني ذلك أنّ الزائر لديه طريقة دفع واحدة أو أكثر كما هو محدّد في السمة allowedPaymentMethods الخاصة بـ IsReadyToPayRequest المقدَّمة.

تتوفّر هذه السمة فقط عندما تم ضبط existingPaymentMethodRequired على true في IsReadyToPayRequest.

إذا تمّت تهيئة PaymentsClient باستخدام السمة environment بقيمة TEST، سيتم دائمًا اعتبار طريقة الدفع متوفّرة.

مثال

يوضّح لك المثال التالي الحالات التي يمكن فيها للزائر الحالي تقديم معلومات الدفع إلى الموقع الإلكتروني الذي يطلبها.

{
  "result": true
}

PaymentData

هذا هو عنصر الاستجابة الذي تعرضه Google بعد أن يوافق المسؤول عن الدفع على الدفع.

PaymentDataRequest.PaymentDataRequest.PaymentDataRequest
الموقع النوع موجود دائمًا الوصف
apiVersion الرقم نعم رقم الإصدار الرئيسي لواجهة برمجة التطبيقات تتطابق القيمة في الردّ مع القيمة المقدَّمة في PaymentDataRequest.
apiVersionMinor الرقم نعم الإصدار الثانوي لواجهة برمجة التطبيقات تتطابق القيمة في الردّ مع القيمة المقدَّمة في PaymentDataRequest.
paymentMethodData PaymentMethodData نعم بيانات حول طريقة الدفع المحدّدة
email سلسلة لا عنوان البريد الإلكتروني، إذا تم ضبط emailRequired على true في PaymentDataRequest إذا كان طلب آخر يتضمّن السمة مضبوطة على true، لن يكون هناك أي تأثير.
shippingAddress العنوان لا عنوان الشحن، إذا كانت قيمة shippingAddressRequired هي true في PaymentDataRequest

مثال

تعرض استجابة المثال هذه لإصدار 2.0 من Google Pay API CARD طريقة دفع تم اختيارها في ورقة الدفع في Google Pay. تم إنشاء رمز مميّز لطريقة الدفع لبوابة الدفع example.

{
  "apiVersion": 2,
  "apiVersionMinor": 0,
  "paymentMethodData": {
    "type": "CARD",
    "description": "Visa •••• 1234",
    "info": {
      "cardNetwork": "VISA",
      "cardDetails": "1234",
      "cardFundingSource": "CREDIT"
    },
    "tokenizationData": {
      "type": "PAYMENT_GATEWAY",
      "token": "examplePaymentMethodToken"
    }
  }
}

IntermediatePaymentData

يتم عرض هذا العنصر من خلال إدخال onPaymentDataChanged() في Google Pay API عند تغيير عنوان الشحن أو خيارات الشحن في ورقة الدفع.

الموقع النوع الضرورة الوصف
callbackTrigger سلسلة اختياري

توضّح هذه السمة سبب استدعاء معاودة الاتصال ببيانات الدفع.

  • INITIALIZE
  • SHIPPING_ADDRESS
  • SHIPPING_OPTION
  • OFFER
offerData OfferData اختياري الرمز الترويجي الذي قدّمه المستخدم.
shippingAddress IntermediateAddress اختياري العنوان المحدّد في ورقة الدفع
shippingOptionData SelectionOptionData اختياري خيار الشحن المحدّد في ورقة الدفع

مثال

يعرض هذا المثال الحمولة الوسيطة التي يتم إرجاعها من Google Pay API.

{
  "callbackTrigger": "SHIPPING_ADDRESS",
  "offerData": {
    "redemptionCode": "exampleCode"
  },
  "shippingAddress": {
    "administrativeArea": "NY",
    "countryCode": "US",
    "locality": "New York",
    "postalCode": "10011"
  },
  "shippingOptionData": {
    "id": "shipping-001"
  }
}

PaymentMethodData

يوفّر هذا العنصر بيانات لطريقة دفع محدّدة.

الموقع النوع موجود دائمًا الوصف
type سلسلة نعم PaymentMethod تم اختيار type في ورقة الدفع في Google Pay.
description سلسلة نعم

رسالة موجّهة إلى المستخدم لوصف طريقة الدفع التي تموّل هذه المعاملة.
info عنصر نعم تعتمد قيمة هذه السمة على طريقة الدفع type التي تم إرجاعها. في ما يتعلّق بـ CARD، يمكنك الاطّلاع على CardInfo.
tokenizationData PaymentMethodTokenizationData لا بيانات ترميز طريقة الدفع المحدّدة

مثال

يوضّح مثال الردّ هذا كيف تؤدي طريقة الدفع CARD المحدّدة في ورقة الدفع في Google Pay إلى إنشاء رمز مميّز لطريقة الدفع لبوابة example.

{
  "type": "CARD",
  "description": "Visa •••• 1234",
  "info": {
    "cardNetwork": "VISA",
    "cardDetails": "1234"
  },
  "tokenizationData": {
    "type": "PAYMENT_GATEWAY",
    "token": "examplePaymentMethodToken"
  }
}

CardInfo

يوفّر هذا العنصر معلومات عن بطاقة الدفع المحدّدة.

الموقع النوع موجود دائمًا الوصف
cardDetails سلسلة نعم تفاصيل البطاقة عادةً ما تكون هذه القيمة هي آخر أربعة أرقام من رقم حساب الدفع المحدّد.
assuranceDetails AssuranceDetailsSpecifications نعم يوفّر هذا العنصر معلومات حول عملية التحقّق من صحة بيانات الدفع التي تم عرضها إذا تم ضبط assuranceDetailsRequired على true في CardParameters.
cardNetwork سلسلة نعم

شبكة بطاقة الدفع التي تم اختيارها تتطابق القيم المعروضة مع تنسيق allowedCardNetworks في CardParameters.

يجب عدم عرض قيمة شبكة البطاقة هذه للمشتري. يتم استخدامها عند الحاجة إلى تفاصيل بطاقة المشتري. على سبيل المثال، إذا احتاج فريق دعم العملاء إلى هذه القيمة لتحديد البطاقة التي استخدمها المشتري في معاملته. لعرض وصف للمستخدم، استخدِم السمة description الخاصة بنوع PaymentMethodData بدلاً من ذلك.
billingAddress العنوان لا عنوان إرسال الفواتير المرتبط بطريقة الدفع المقدَّمة، إذا تم ضبط قيمة billingAddressRequired على true في CardParameters
cardFundingSource سلسلة نعم

مصدر تمويل البطاقة لطريقة الدفع المحدّدة

  • UNKNOWN
  • CREDIT
  • DEBIT
  • PREPAID

مثال

يعرض هذا المثال بطاقة على شبكة Visa.

{
  "cardNetwork": "VISA",
  "cardDetails": "1234",
  "cardFundingSource": "CREDIT",
  "assuranceDetails": {
    "cardHolderAuthenticated": false,
    "accountVerified": true
  }
}

AssuranceDetailsSpecifications

يوفّر هذا العنصر معلومات حول عملية التحقّق التي تم إجراؤها على بيانات اعتماد الدفع التي تم إرجاعها، وذلك حتى يمكن تطبيق عمليات التحقّق المناسبة من مخاطر وسيلة الدفع.

الاسم النوع الوصف
accountVerified قيمة منطقية إذا كانت القيمة true، يشير ذلك إلى أنّه تم التحقّق من ملكية Cardholder في بيانات اعتماد الدفع التي تم إرجاعها.
cardHolderAuthenticated قيمة منطقية

إذا كانت القيمة true، يشير ذلك إلى أنّه تم إجراء عملية تعريف الهوية وإثباتها (ID&V) على بيانات الدفع التي تم إرجاعها.

في حال false، يمكن إجراء المصادقة نفسها المستندة إلى تقييم المخاطر كما هو الحال مع معاملات البطاقة. يمكن أن يشمل هذا المصادقة المستندة إلى المخاطر، على سبيل المثال لا الحصر، خطوة إضافية باستخدام بروتوكول 3D Secure إذا كان ذلك منطبقًا.

يمكنك تلقّي كائن الاستجابة ومعالجته حتى إذا لم تستخدم الحقل assuranceDetails. لتلقّي هذا العنصر، أدرِج assuranceDetailsRequired: true في CardParameters ضمن عنصر الطلب.

PaymentMethodTokenizationData

يوفّر هذا العنصر بيانات الترميز لطريقة الدفع.

الموقع النوع موجود دائمًا الوصف
type سلسلة نعم نوع الترميز الذي سيتم تطبيقه على طريقة الدفع المحدّدة تتطابق هذه القيمة مع type المحدّدة في PaymentMethodTokenizationSpecification.
token سلسلة لا

الرمز المميّز لطريقة الدفع الذي تم إنشاؤه

  • PAYMENT_GATEWAY: سلسلة عنصر JSON تحتوي على رمز مميّز قابل لتحصيل الرسوم أصدرته بوابة الدفع.
  • مباشر: protocolVersion وsignature وsignedMessage لإلغاء التشفير. يمكنك الاطّلاع على بنية رمز طريقة الدفع لمزيد من المعلومات.

مثال

هذا مثال على ردّ تم تحويله إلى رموز مميّزة وتم إعداده لبوابة example.

{
  "type": "PAYMENT_GATEWAY",
  "token": "examplePaymentMethodToken"
}

PaymentAuthorizationResult

يوفّر هذا العنصر معلومات حول نتيجة تفويض الدفع.

الموقع النوع الضرورة الوصف
transactionState سلسلة مطلوب يتم تحديد حالة المعاملة من خلال إحدى نتائج التاجر التالية:
  • SUCCESS
  • ERROR
error PaymentDataError اختياري الخطأ الذي سيتم عرضه في صفحة الدفع للمستخدم عندما يكون من الضروري إعادة محاولة الدفع.

مثال

يعرض المثال التالي نتيجة الدفع التي يتم إرجاعها بعد معالجة عملية الدفع:

{
  "transactionState": "ERROR",
  "error": {
    "reason": "PAYMENT_DATA_INVALID",
    "message": "Cannot pay with payment credentials",
    "intent": "PAYMENT_AUTHORIZATION"
  }
}

PaymentDataError

الموقع النوع الضرورة الوصف
reason سلسلة مطلوب

قائمة بأسباب الخطأ المحدّدة مسبقًا:

  • OFFER_INVALID
  • PAYMENT_DATA_INVALID
  • SHIPPING_ADDRESS_INVALID
  • SHIPPING_ADDRESS_UNSERVICEABLE
  • SHIPPING_OPTION_INVALID
  • OTHER_ERROR
message سلسلة مطلوب رسالة الخطأ التي تظهر للمستخدم في مربّع حوار
intent سلسلة مطلوب

الغرض من الخطأ. يجب أن يكون هذا الغرض من الأغراض التي تم تسجيلها في PaymentDataRequest من بداية المسار.

  • OFFER
  • PAYMENT_AUTHORIZATION
  • SHIPPING_ADDRESS
  • SHIPPING_OPTION

مثال

يعرض هذا المثال الغرض من الخطأ والرسالة التي سيتم عرضها في ورقة الدفع.

{
  "error": {
    "reason": "SHIPPING_OPTION_INVALID",
    "message": "This shipping option is invalid for the given address",
    "intent": "SHIPPING_OPTION"
  }
}

العنوان

يقدّم هذا العنصر معلومات حول عنوان بريدي مطلوب. جميع السمات هي سلاسل.

يمكن عرض العناوين بالتنسيقات MIN وFULL وFULL-ISO3166. يمكن الاطّلاع على السمات التي تنتمي إلى كل تنسيق في الجدول التالي.

الموقع تنسيق العنوان الوصف
name ‫MIN، FULL، FULL-ISO3166 الاسم الكامل للمرسَل إليه
postalCode ‫MIN، FULL، FULL-ISO3166 تمثّل هذه السمة الرمز البريدي.
countryCode ‫MIN، FULL، FULL-ISO3166 رمز البلد المكوّن من حرفَين وفقًا لمعيار ISO 3166-1 alpha-2
phoneNumber ‫MIN، FULL، FULL-ISO3166 رقم هاتف، إذا تم ضبط phoneNumberRequired على true في PaymentDataRequest
address1 ‫FULL، FULL-ISO3166 السطر الأول من العنوان
address2 ‫FULL، FULL-ISO3166 السطر الثاني من العنوان
address3 ‫FULL، FULL-ISO3166 السطر الثالث من العنوان
locality ‫FULL، FULL-ISO3166 المدينة أو البلدة أو الحي أو الضاحية
administrativeArea ‫FULL، FULL-ISO3166 تمثّل هذه السمة قسمًا فرعيًا من البلد، مثل ولاية أو مقاطعة.
sortingCode ‫FULL، FULL-ISO3166 تمثّل هذه السمة رمز التصنيف.
iso3166AdministrativeArea FULL-ISO3166 رمز المنطقة الإدارية وفقًا لمعيار ISO 3166-2 الذي يتوافق مع administrativeArea

مثال

هذا مثال على عنوان بتنسيق FULL-ISO3166 في الولايات المتحدة يتضمّن عدة أسطر من بيانات عنوان الشارع.

{
  "name": "John Doe",
  "address1": "c/o Google LLC",
  "address2": "1600 Amphitheatre Pkwy",
  "address3": "Building 40",
  "locality": "Mountain View",
  "administrativeArea": "CA",
  "countryCode": "US",
  "postalCode": "94043",
  "sortingCode": ""
  "iso3166AdministrativeArea": "US-CA"
}

IntermediateAddress

يحتوي العنوان الوسيط على عنوان شحن تم إخفاء بعض تفاصيله (بدون أسطر العنوان على مستوى الشارع أو أسماء المستلمين) للسماح بحساب الضريبة وخيارات الشحن السارية قبل أن يوافق المستخدم على الدفع.

الموقع النوع الضرورة الوصف
administrativeArea سلسلة مطلوب تمثّل هذه السمة قسمًا فرعيًا من البلد، مثل ولاية أو مقاطعة.
countryCode سلسلة مطلوب رمز البلد المكوّن من حرفَين وفقًا لمعيار ISO 3166-1 alpha-2
locality سلسلة مطلوب المدينة أو البلدة أو الحي أو الضاحية
postalCode سلسلة مطلوب الرمز البريدي الذي تم إخفاء بعض أجزائه استنادًا إلى البلد بالنسبة إلى كندا والمملكة المتحدة، يحتوي هذا الحقل على الأحرف الثلاثة الأولى فقط. بالنسبة إلى الولايات المتحدة، يحتوي هذا الحقل على الأرقام الخمسة الأولى.
iso3166AdministrativeArea سلسلة اختياري رمز المنطقة الإدارية وفقًا لمعيار ISO 3166-2 الذي يتوافق مع administrativeArea يظهر هذا الحقل فقط إذا كان تنسيق عنوان الشحن هو FULL-ISO3166.

مثال

يعرض لك هذا المثال العنوان المحدّد في ورقة الدفع.

{
  "administrativeArea": "NY",
  "countryCode": "US",
  "locality": "New York",
  "postalCode": "10011"
  "iso3166AdministrativeArea": "US-NY"
}

SelectionOptionData

الموقع النوع الضرورة الوصف
id سلسلة مطلوب مطابقات مع SelectionOption.id

مثال

يوضّح لك هذا المثال خيار الشحن الذي تم اختياره في صفحة الدفع.

{
  "id": "shipping-001"
}

OfferData

يوفّر هذا العنصر معلومات عن رمز العرض الذي تم إدخاله في ورقة الدفع.

الموقع النوع الضرورة الوصف
redemptionCodes صفيف موجود دائمًا مجموعة الرموز الترويجية التي تم إدخالها في صفحة الدفع يتضمّن هذا الحقل الرموز التي تمت الموافقة عليها سابقًا.

مثال

يعرض المثال التالي عنصر OfferData مع مصفوفة redemptionCodes.

"offerData": {
    "redemptionCodes": ["PROMOTIONALCODE"]
}