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

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

PaymentData

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

استبدِل PaymentDataRequestPaymentDataRequestPaymentDataRequest.
الموقع النوع موجود دائمًا الوصف
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 سلسلة مطلوب

الغرض من الخطأ.

  • 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

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

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

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

  • INITIALIZE
  • SHIPPING_ADDRESS
  • SHIPPING_OPTION
shippingAddress IntermediateAddress اختياري عنوان الشحن المحدّد في ورقة الدفع
shippingOptionData SelectionOptionData اختياري خيار الشحن الذي تم تحديده في ورقة الدفع

مثال

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

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

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