إعداد الدفع

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

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

عند استلام طلب دفع، يجب أن تنفّذ خدمة "الطلب من خلال Google" على الويب ما يلي:

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

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

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

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

تتضمن البيانات الواردة في 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
}

رسالة الرد في عملية الدفع

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

طلب ناجح

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

• ProposedOrder

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

• PaymentOptions

  • نتناول لاحقًا عملية إعداد معالجة الدفعات في إعداد Google Pay. يمكنك استخدام عنصر نائب 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."
                }
              ]
            }
          }
        }
      ]
    }
  }
}