إعداد Checkout

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

يجب أن يستجيب معالج الدفع في خدمة الويب لطلبات POST. عندما العميل الذي يختار إتمام الدفع، فسترسل Google خدمة الويب الشاملة للطلب نص طلب JSON على شكل CheckoutRequestMessage، والذي يحتوي على تفاصيل Cart للعميل. ثم تستجيب خدمة الويب لديك باستخدام CheckoutResponseMessage يوضح الرسم التخطيطي التالي هذه العملية.

عند تلقّي طلب الدفع، يجب أن تنفّذ خدمة الويب الشاملة للطلب ما يلي:

• تحقق من صلاحية سلة التسوق بناءً على أسعار العناصر الحالية ومدى توفّرها ومزود الخدمة.
• احسب السعر الإجمالي (بما في ذلك أي خصومات وضرائب وتسليمات. الرسوم).
• في حال نجاح الإجراء، يمكنك الردّ باستخدام سلة تسوّق غير معدّلة.
• إذا لم ينجح الأمر، يمكنك الرد برسالة خطأ وطلب مقترح جديد.

قبل البدء في تنفيذ عملية الدفع، ننصحك بمراجعة مقالة توصيل الطلبات. نظرة عامة التوثيق.

رسالة طلب الدفع

للتحقّق من صحة سلة تسوّق العميل، عندما يختار العميل إتمام الدفع، ترسل Google طلبًا إلى خدمة الويب باستخدام نص JSON على شكل CheckoutRequestMessage لا يتم إرسال طلب العميل إلا في وقت لاحق من ترتيب التدفق الشامل.

البيانات الموجودة في CheckoutRequestMessage ما يلي:

• الغرض: inputs[0].intent الخاص بكل نص طلب دفع قيمة السلسلة actions.foodordering.intent.CHECKOUT.
• سلة التسوق: الحقل inputs[0].arguments[0].extension لطلب الدفع يحتوي على عنصر Cart يمثّل سلة تسوّق العميل.
• التسليم أو التصدير: يحتوي حقل إضافة العنصر Cart على كائن FoodCartExtension الذي يحدد الخصائص للتسليم أو طلب الوجبات لتناولها خارج المطعم:
  • بالنسبة إلى طلبات التسليم، يتضمّن العنصر FoodCartExtension السمة وعنوان التسليم.
  • بالنسبة إلى طلبات الاستلام من المطعم أو خارجه، لا يمكن للعنصر FoodCartExtension سيحتوي على أي معلومات عن الموقع.
• وضع الحماية: يحتوي الحقل isInSandbox في طلب الدفع على قيمة منطقية. تشير إلى ما إذا كانت المعاملة تستخدم دفعات وضع الحماية.

مثال على طلب الدفع

في ما يلي مثال على CheckoutRequestMessage:

{
    "user": {},
    "conversation": {
        "conversationId": "CTZbZfUlHCybEdcz_5PB3Ttf"
    },
    "inputs": [
        {
            "intent": "actions.foodordering.intent.CHECKOUT",
            "arguments": [
                {
                    "extension": {
                        "@type": "type.googleapis.com/google.actions.v2.orders.Cart",
                        "merchant": {
                            "id": "restaurant/Restaurant/QWERTY",
                            "name": "Tep Tep Chicken Club"
                        },
                        "lineItems": [
                            {
                                "name": "Spicy Fried Chicken",
                                "type": "REGULAR",
                                "id": "299977679",
                                "quantity": 2,
                                "price": {
                                    "type": "ESTIMATE",
                                    "amount": {
                                        "currencyCode": "AUD",
                                        "units": "39",
                                        "nanos": 600000000
                                    }
                                },
                                "offerId": "MenuItemOffer/QWERTY/scheduleId/496/itemId/143",
                                "extension": {
                                    "@type": "type.googleapis.com/google.actions.v2.orders.FoodItemExtension"
                                }
                            }
                        ],
                        "extension": {
                            "@type": "type.googleapis.com/google.actions.v2.orders.FoodCartExtension",
                            "fulfillmentPreference": {
                                "fulfillmentInfo": {
                                    "delivery": {
                                        "deliveryTimeIso8601": "P0M"
                                    }
                                }
                            },
                            "location": {
                                "coordinates": {
                                    "latitude": -33.8376441,
                                    "longitude": 151.0868736
                                },
                                "formattedAddress": "Killoola St, 1, Concord West NSW 2138",
                                "zipCode": "2138",
                                "city": "Concord West",
                                "postalAddress": {
                                    "regionCode": "AU",
                                    "postalCode": "2138",
                                    "administrativeArea": "NSW",
                                    "locality": "Concord West",
                                    "addressLines": [
                                        "Killoola St",
                                        "1"
                                    ]
                                }
                            }
                        }
                    }
                }
            ]
        }
    ],
    "directActionOnly": true,
    "isInSandbox": true
}

رسالة الرد على الدفع

بعد تلقّي طلب من خدمة "الطلب الشاملة"، على صفحة الويب الخاصة بالدفع على الخدمة معالجة الرسالة والاستجابة للطلب باستخدام CheckoutResponseMessage. تشير رسالة الأشكال البيانية على "CheckoutResponseMessage" أن يغطي طلبك بنجاح أو غير ناجح طلبك.

طلب ناجح

إذا نجح طلب إتمام الدفع، على "CheckoutResponseMessage" تضمين ProposedOrder أو PaymentOptions:

• ProposedOrder

  • cart: عنصر cart مطابق لسلة التسوّق المقدّمة في CheckoutRequestMessage إذا كان أي من محتويات سلة التسوق بحاجة إلى تم تغييره، يجب أن تتضمن CheckoutResponseMessage بدلاً من ذلك FoodErrorExtension مع ProposedOrder مصحّح.
  • otherItems: السلع التي أضافها مقدّم الخدمة، مثل رسوم التسليم والضرائب والرسوم الأخرى. قد يحتوي أيضًا على مزايا أضافها المستخدم.
  • totalPrice: السعر الإجمالي للطلب
  • extension: عنصر FoodOrderExtension الذي يحدّد معلومات توصيل الطلب للطلب، مثل مدة التسليم.

• PaymentOptions

  • يتم تناول إعداد معالجة الدفعات لاحقًا في مقالة إعداد Google. الدفع يمكنك استخدام العنصر النائب JSON في CheckoutResponseMessage إلى أن جاهز لتنفيذ عملية معالجة الدفعات
  • لإضافة خيارات الدفع النائبة في "CheckoutResponseMessage": يُرجى الرجوع إلى المثال أدناه، والذي يستخدم مثال على بوابة الدفع في PaymentOptions.

مثال على استجابة ناجحة

{
    "finalResponse": {
        "richResponse": {
            "items": [
                {
                    "structuredResponse": {
                        "checkoutResponse": {
                            "proposedOrder": {
                                "cart": {
                                    "merchant": {
                                        "id": "restaurant/Restaurant/QWERTY",
                                        "name": "Tep Tep Chicken Club"
                                    },
                                    "lineItems": [
                                        {
                                            "name": "Spicy Fried Chicken",
                                            "type": "REGULAR",
                                            "id": "299977679",
                                            "quantity": 2,
                                            "price": {
                                                "type": "ESTIMATE",
                                                "amount": {
                                                    "currencyCode": "AUD",
                                                    "units": "39",
                                                    "nanos": 600000000
                                                }
                                            },
                                            "offerId": "MenuItemOffer/QWERTY/scheduleId/496/itemId/143",
                                            "extension": {
                                                "@type": "type.googleapis.com/google.actions.v2.orders.FoodItemExtension"
                                            }
                                        }
                                    ],
                                    "extension": {
                                        "@type": "type.googleapis.com/google.actions.v2.orders.FoodCartExtension",
                                        "fulfillmentPreference": {
                                            "fulfillmentInfo": {
                                                "delivery": {
                                                    "deliveryTimeIso8601": "P0M"
                                                }
                                            }
                                        },
                                        "location": {
                                            "coordinates": {
                                                "latitude": -33.8376441,
                                                "longitude": 151.0868736
                                            },
                                            "formattedAddress": "Killoola St, 1, Concord West NSW 2138",
                                            "zipCode": "2138",
                                            "city": "Concord West",
                                            "postalAddress": {
                                                "regionCode": "AU",
                                                "postalCode": "2138",
                                                "administrativeArea": "NSW",
                                                "locality": "Concord West",
                                                "addressLines": [
                                                    "Killoola St",
                                                    "1"
                                                ]
                                            }
                                        }
                                    }
                                },
                                "totalPrice": {
                                    "type": "ESTIMATE",
                                    "amount": {
                                        "currencyCode": "AUD",
                                        "units": "43",
                                        "nanos": 100000000
                                    }
                                },
                                "extension": {
                                    "@type": "type.googleapis.com/google.actions.v2.orders.FoodOrderExtension",
                                    "availableFulfillmentOptions": [
                                        {
                                            "fulfillmentInfo": {
                                                "delivery": {
                                                    "deliveryTimeIso8601": "P0M"
                                                }
                                            }
                                        }
                                    ]
                                },
                                "otherItems": [
                                    {
                                        "name": "Delivery fee",
                                        "price": {
                                            "type": "ESTIMATE",
                                            "amount": {
                                                "currencyCode": "AUD",
                                                "units": "3",
                                                "nanos": 500000000
                                            }
                                        },
                                        "type": "DELIVERY"
                                    }
                                ]
                            },
                            "paymentOptions": {
                                "googleProvidedOptions": {
                                    "facilitationSpecification": "{\"apiVersion\":2,\"apiVersionMinor\":0,\"merchantInfo\":{\"merchantName\":\"merchantName\"},\"allowedPaymentMethods\":[{\"type\":\"CARD\",\"parameters\":{\"allowedAuthMethods\":[\"PAN_ONLY\"],\"allowedCardNetworks\":[\"VISA\",\"MASTERCARD\"],\"billingAddressRequired\":true,\"cvcRequired\":false},\"tokenizationSpecification\":{\"type\":\"PAYMENT_GATEWAY\",\"parameters\":{\"gatewayMerchantId\":\"YOUR_MERCHANT_ID\",\"gateway\":\"cybersource\"}}}],\"transactionInfo\":{\"currencyCode\":\"AUD\",\"totalPriceStatus\":\"ESTIMATED\",\"totalPrice\":\"43.1\"}} "
                                }
                            },
                            "additionalPaymentOptions": [
                                {
                                    "actionProvidedOptions": {
                                        "paymentType": "ON_FULFILLMENT",
                                        "displayName": "Pay when you get your food.",
                                        "onFulfillmentPaymentData": {
                                            "supportedPaymentOptions": []
                                        }
                                    }
                                }
                            ]
                        }
                    }
                }
            ]
        }
    }
}

تعذّر تنفيذ الطلب.

في حال عدم نجاح طلب الدفع، على "CheckoutResponseMessage" تنفيذ ما يلي: تتضمن FoodErrorExtension، التي تحتوي على قائمة FoodOrderError البنود التي تصف أي أخطاء حدثت. فإذا كانت هناك أي نقاط قابلة للاسترداد أخطاء في الطلب، مثل تغيير سعر سلعة ما في سلة التسوق، يجب أن يتضمّن FoodErrorExtension السمة correctedProposedOrder.

مثال على ردّ غير ناجح

{
  "expectUserResponse": false,
  "finalResponse": {
    "richResponse": {
      "items": [
        {
          "structuredResponse": {
            "error": {
              "@type": "type.googleapis.com/google.actions.v2.orders.FoodErrorExtension",
              "foodOrderErrors": [
                {
                  "error": "CLOSED",
                  "description": "The restaurant is closed."
                }
              ]
            }
          }
        }
      ]
    }
  }
}

تنفيذ عملية الدفع

يجب اتّباع الخطوات التالية عند تنفيذ عملية الدفع.

التحقّق من الخدمة

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

1. اقرأ السمة FulfillmentOptionInfo في لتحديد ما إذا كان نوع توصيل الطلب يعود إلى delivery أو pickup.

2. اعرض أنواع الأخطاء التالية إذا لزم الأمر:

   نوع الخطأ	حالة الاستخدام
   غير صالحة	نوع طريقة الطلب غير صالح.
   NOT_FOUND	لم يتم العثور على نوع توصيل الطلب.
   مغلقة	ما مِن نوافذ OperationHours للطلب. الطلب يتم في أقرب وقت ممكن ولا تتوفر ServiceHours في أقرب وقت ممكن في الوقت الحالي. حدث إغلاق طارئ أو أنّ الخدمة isDisabled صحيحة. يُرجى العلم أنّ النوافذ الخاصة تحظى بالأولوية على النوافذ العادية. اطّلِع على أمثلة في التحقّق من صحة نوافذ طلب الشراء وإزالة كيانات الخدمة مؤقتًا.
   UNAVAILABLE_SLOT	يتعذّر تنفيذ الطلب المسبق.
   NO_CAPACITY	المطعم مشغول ولا يتلقى الطلبات في الوقت الحالي.
   OUT_OF_SERVICE_AREA	لا يمكن تسليم الطلب إلى عنوان المستخدم. راجِع التحقُّق من صحة عنوان التسليم للحصول على مثال.
   NO_COURIER_AVAILABLE	لا يمكن تسليم الطلب لأنّ عدد موظفي التسليم محدود.

التحقّق من صحة سلة التسوّق وتسعيرها

1. ابحث عن كل سلة التسوق.lineItems وتحقق من صحتها باستخدام البيانات الحالية في في نظامك أو في نظام التاجر تشير رسالة الأشكال البيانية MenuItemOffer.sku تم تضمين القيمة من الكيان في الخلاصة. باعتباره LineItem.offerId. إنشاء FoodOrderError لكل عنصر إذا لزم الأمر. إنشاء خطأ واحد بحد أقصى لكل عنصر. عرض أنواع الأخطاء التالية إذا مطلوبة:

   نوع الخطأ	حالة الاستخدام	قابل للاسترداد
   غير صالحة	بيانات السلع أو بيانات أي من الخيارات غير صالحة.	لا
   NOT_FOUND	لم يتم العثور على العنصر أو أي من الخيارات.	لا
   PRICE_CHANGED	تم تغيير سعر المنتج أو مجموعة الإضافات. يمكن التعامل مع هذا الخطأ على أنّه قابل للاسترداد.	نعم
   AVAILABILITY_CHANGED	المبلغ المطلوب لتفاصيل الإعلان أو أيٍّ من الخيارات غير متوفّر.	نعم
   REQUIREMENTS_NOT_MET	لم يتم استيفاء الحد الأدنى للطلب أو الحد الأقصى للطلب. ويمكن تحديد ذلك من خلال التحقّق مما إذا كان سعر سلة التسوّق أقل من الرسوم.eligibleTransactionVolumeMin أو أعلى من الرسومeligibleTransactionVolumeMax. راجِع المثال في مقالة التحقّق من الحدّ الأدنى لقيمة طلب الشراء.	لا

   ملاحظة: عند احتساب سعر LineItem مع الإضافات، يجب مراعاة سعر البند يتضمن سعر MenuItemOptions. إذا كانت هناك numberOfFreeAddOns المحدد في MenuSection للإضافة، ويمثل السعر الفردي يتم تضمين الإضافة في سعر FoodItemOption ولكن لا تتم إضافة سعر المنتج المجاني إلى سعر LineItem. في حال حذف عدد الخيارات المحدّدة أكبر من numberOfFreeAddOns، هناك إضافات التي تحتسب الإضافات المجانية ذات الأسعار الأعلى.

2. عرض القائمة التي تم التحقق منها للعناصر باستخدام LineItemType REGULAR فإن مجموع كل أسعار عناصر سلة التسوق هو سعر سلة التسوق أو SUBTOTAL

اطّلِع على أمثلة في مقالة التحقّق من صحة عناصر سلة التسوّق.

حساب رسوم الخدمة

1. ابحث عن كيان الرسوم الصحيح للخدمة استنادًا إلى "eligibleRegion" و"validFrom" و"validThrough" و"priority"
2. احسب مبلغ الرسوم بناءً على ما إذا تم تحديد الكيان باستخدام price. السمة percentageOfCart أو pricePerMeter.
3. إرجاع رسوم خدمة التوصيل أو طلب الوجبات لتناولها خارج المطعم على شكل LineItem باستخدام LineItemType DELIVERY أو FEE على التوالي. إضافة الرسوم إلى قائمة سلة التسوقotherItems.

تطبيق العروض الترويجية

1. ابحث عن كيان الصفقة استنادًا إلى مطابقة العرض الترويجي.coupon مع الصفقة.dealCode.

2. يُرجى التحقّق من صحة الصفقة وعرض FoodOrderError إذا لزم الأمر. يمكن التعامل مع هذه الأخطاء على أنّها قابلة للاسترداد. عرض أنواع الأخطاء التالية إذا لزم الأمر:

   نوع الخطأ	حالة الاستخدام
   PROMO_NOT_RECOGNIZED	لم يتم التعرّف على رمز القسيمة.
   PROMO_EXPIRED	انتهت صلاحية الصفقة.
   PROMO_ORDER_INELIGIBLE	الطلب غير مؤهّل للحصول على القسيمة.
   PROMO_NOT_APPLICABLE	أي سبب آخر

   ملاحظة: يمكنك التحقّق مما إذا كان طلب الدفع يتضمّن معلومات المستخدم يكون المستخدِم المحدّد مؤهَّلاً للصفقة عند استلام الطلب المُرسَل. .

3. احسب مبلغ سعر الصفقة بناءً على الصفقة.discount أو عرضdiscountPercentage.

4. يمكنك تطبيق مبلغ سعر الصفقة باستخدام إجمالي رسوم سلة التسوّق أو إجمالي الرسوم استنادًا إلى صفقة.dealType.

5. عليك إرجاع سلّة التسوّق.promotions مع تطبيق العرض الترويجي.

6. إرجاع العرض الترويجي على شكل LineItem باستخدام LineItemType DISCOUNT. أضِف الخصم إلى سلة التسوق.otherItems تتضمّن قائمة أسعار سلبية.

عرض الردّ

1. أنشئ ProposedOrder.cart، حيث إن سلة تسوق الاستجابة هي مثل سلة تسوق الطلب في حالة عدم حدوث أي أخطاء أثناء التحقق.
2. اعرض قائمة ProposedOrder.otherItems بما في ذلك الضريبة والرسوم والإكرامية والخصم إذا تم تطبيقها. عرض التقدير على مزيد من التفاصيل حول كيفية ضبط عنصر الإكرامية.
3. أدرِج ProposedOrder.totalPrice من خلال إضافة سلة التسوق السعر والرسوم والخصم والضرائب والإكرامية.
4. إرجاع FoodOrderExtension.availableFulfillmentOptions مع FulfillmentOption المعني. تعديل القيم المقدَّرة للاستلام أو التسليم إلى الوقت المتوقع.
5. في حال ظهور أخطاء FoodOrderErrors من عمليات التحقق السابقة:
   • ضمِّن StructuredResponse.error وقائمة في FoodErrorExtension.foodOrderErrors.
   • أدخِل ProposedOrder في correctedProposedOrder إذا كان من الممكن استرداد جميع الأخطاء.
   • إرجاع PaymentOptions في paymentOptions ما إذا كانت جميع الأخطاء قابلة للاستعادة.
   • يمكنك اختياريًا تضمين additionalPaymentOptions إذا كانت هناك سمات أخرى خيارات الدفع المتاحة ويمكن إصلاح جميع الأخطاء.
6. إذا لم تكن هناك أخطاء في عملية التحقّق، يمكنك عرض proposedOrder paymentOptions في الكائن CheckoutResponse. يمكنك اختياريًا تضمين additionalPaymentOptions إذا كانت هناك سمات أخرى خيارات الدفع المتاحة.