عناصر استجابة JSON

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

PaymentData

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

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

مثال

يعرض نموذج الاستجابة هذا للإصدار 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"
    }
  }
}

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 سلسلة مطلوب

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

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

The intent of the error.

  • 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"
}

IntermediatePaymentData

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

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

يصف سبب استدعاء دالة ردّ الاتصال لبيانات الدفع.

  • INITIALIZE
  • SHIPPING_ADDRESS
  • SHIPPING_OPTION
  • PAYMENT_METHOD
shippingAddress IntermediateAddress اختياري العنوان المحدّد في صفحة الدفع
shippingOptionData SelectionOptionData اختياري خيار الشحن المحدّد في صفحة الدفع
paymentMethodData IntermediatePaymentMethodData اختياري بيانات طريقة الدفع المحدّدة في صفحة الدفع

أمثلة

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

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

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

{
  "callbackTrigger": "PAYMENT_METHOD",
  "paymentMethodData": {
    "type": "CARD",
    "info": {
      "cardNetwork": "VISA",
      "cardFundingSource": "CREDIT",
      "billingAddress": {
        "administrativeArea": "NY",
        "countryCode": "US",
        "locality": "New York",
        "postalCode": "10011"
      }
    }
  }
}

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"
}

IntermediatePaymentMethodData

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

الموقع النوع الضرورة الوصف
type سلسلة مطلوب نوع طريقة الدفع يُسمح فقط بالقيمة CARD لعملية الاستدعاء هذه.
info IntermediateCardInfo اختياري معلومات عن البطاقة المحدّدة لا يتم ذكر هذا التاريخ إلا إذا كانت قيمة type هي CARD.

IntermediateCardInfo

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

الموقع النوع الضرورة الوصف
billingAddress IntermediateAddress اختياري عنوان إرسال الفواتير المرتبط بالبطاقة لا تتم تعبئة هذا الحقل إلا عند ضبط عنوان إرسال الفواتير على أنّه مطلوب.
cardNetwork سلسلة اختياري

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

يجب عدم عرض قيمة شبكة البطاقات هذه للمشتري.
cardFundingSource سلسلة اختياري

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

  • UNKNOWN
  • CREDIT
  • DEBIT
  • PREPAID