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

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

IsReadyToPayResponse

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

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

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

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

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

مثال

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

{
  "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 سلسلة لا

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

مثال

هذا مثال على ردّ تم تحويله إلى رموز مميّزة وتم إعداده لبوابة 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"]
}