الدفع بدون تسجيل دخول

يتطلّب الدمج الأصلي إنشاء واجهة برمجة تطبيقات RESTful يمكن أن تستدعيها Google لإنشاء جلسات الدفع وإدارتها.

في ما يلي المسار العام:

1. إنشاء جلسة الدفع: يكون المستخدم ووكيل اختياري في حلقة لإضافة عناصر إلى الجلسة.
2. التسليم إلى واجهة مستخدم Google: بعد أن يقرّر المستخدم إكمال عملية الدفع من خلال "الوكيل" (في حال التفاعل معه)، يتم نقل التحكّم إلى واجهة مستخدم Google (مع تمرير بيانات جلسة الدفع).
3. إتمام الدفع يدويًا: يتفاعل المستخدم الآن فقط مع واجهة مستخدم Google لملء تفاصيل حساسة حول عملية التنفيذ والدفع وإرسال الطلب. لا يشارك الوكيل في هذا الجزء، ما يضمن تحديد النتائج.
4. الإكمال والإرجاع: تعرض واجهة مستخدم Google صفحة "شكرًا لك" لتأكيد الطلب. يمكن إعادة توجيه المستخدم إلى "الوكيل"، الذي ربما تم إعلامه بعملية الشراء المكتملة.

توضّح الخطوات التالية نقاط نهاية واجهة برمجة التطبيقات التي عليك تنفيذها وسلوكياتها.

1- إنشاء جلسة دفع

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

• نقطة النهاية: POST /checkout-sessions
• المشغّل: ينقر المستخدم على "شراء" في أحد المنتجات.

الطلب: ترسل Google عناصر الحملة والعملة.

{
  "line_items": [
    {
      "item": {
        "id": "product_12345", // Must match Product Feed ID
        "title": "Running Shoes"
      },
      "quantity": 1
    }
  ],
  "currency": "USD"
}

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

{
  "ucp": {
    "version": "2026-01-11",
    "capabilities": [
      {
        "name": "dev.ucp.shopping.checkout",
        "version": "2026-01-11"
      },
      {
        "name": "dev.ucp.shopping.fulfillment",
        "version": "2026-01-11"
      }
    ]
  },
  "id": "gid://merchant.example.com/Checkout/session_abc123",
  "status": "incomplete",
  "line_items": [
    {
      "id": "line_1",
      "item": {
        "id": "product_12345",
        "title": "Running Shoes",
        "price": 10000
      },
      "quantity": 1,
      "base_amount": 10000,
      "subtotal": 10000,
      "total": 10000
    }
  ],
  "totals": [
    { "type": "subtotal", "amount": 10000 }, // in cents
    { "type": "tax", "amount": 0 },
    { "type": "total", "amount": 10000 }
  ],
  "payment": {
    "handlers": [
      {
        "id": "gpay",
        "name": "com.google.pay",
        "config": {
           "api_version": 2,
           "api_version_minor": 0,
           "merchant_info": {
             "merchant_id": "12345678901234567890",
             "merchant_name": "Example Merchant"
           },
           "allowed_payment_methods": [
             {
               "type": "CARD",
               "parameters": {
                 "allowed_auth_methods": ["PAN_ONLY", "CRYPTOGRAM_3DS"],
                 "allowed_card_networks": ["VISA", "MASTERCARD"]
               },
               "tokenization_specification": {
                 "type": "PAYMENT_GATEWAY",
                 "parameters": {
                   "gateway": "stripe",
                   "gateway_merchant_id": "exampleGatewayMerchantId"
                 }
               }
             }
           ]
        }
      }
    ]
  },
  "links": [
    { "type": "privacy_policy", "url": "https://m.com/privacy" },
    { "type": "terms_of_service", "url": "https://m.com/terms" }
  ]
}

2. الحصول على جلسة الدفع

تتيح نقطة النهاية هذه استرداد جلسة دفع.

• نقطة النهاية: GET /checkout-sessions/{id}

الطلب: تُرسِل Google معرّف جلسة الدفع. إذا كنت تستخدم المعرّفات العالمية (مثل gid://merchant.example.com/Checkout/session_abc123)، يُرجى العِلم أنّ المعرّف في مسار الطلب سيكون المكوّن الأخير فقط من هذا المعرّف (مثلاً، session_abc123).

الاستجابة: عليك إرجاع عنصر الدفع الكامل.

3- تعديل جلسة الدفع

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

• نقطة النهاية: PUT /checkout-sessions/{id}
• المشغّل: يختار المستخدم عنوان الشحن أو يغيّره، أو يعدّل خيار الشحن، أو يعدّل معلومات الدفع.

الطلب: تُرسِل Google كائن الدفع الكامل مع المعلومات المعدَّلة.

{
  "id": "gid://merchant.example.com/Checkout/session_abc123",
  "buyer": {
      "first_name": "John",
      "last_name": "Doe",
      "email": "[e-mail]"
  },
  "fulfillment": {
     "methods": [
       {
         "type": "shipping",
         "destinations": [
           {
             "id": "dest_1",
             "postal_code": "94043",
             "country": "US",
             "address_locality": "Mountain View",
             "address_region": "CA"
           }
         ],
         "selected_destination_id": "dest_1"
       }
     ]
  },
  "payment": {
    "selected_instrument_id": "pi_gpay_5678",
    "instruments": [
      {
        "id": "pi_gpay_5678",
        "handler_id": "gpay",
        "type": "card",
        "brand": "mastercard",
        "last_digits": "5678",
        "rich_text_description": "Google Pay •••• 5678"
      }
    ]
  }
  // ... other fields (line_items, currency, etc.)
}

الردّ: عليك إعادة احتساب الضرائب وخيارات الشحن حسب الحاجة، ثم إرجاع عنصر الدفع الكامل.

{
  "id": "gid://merchant.example.com/Checkout/session_abc123",
  "totals": [
     { "type": "subtotal", "amount": 10000 },
     { "type": "shipping", "display_text": "Ground Shipping", "amount": 500 },
     { "type": "tax", "amount": 850 },
     { "type": "total", "amount": 11350 }
  ],

  // ... other fields (line_items, currency, etc.)

  "fulfillment": {
      "methods": [
          {
            "id": "method_shipping",
            "type": "shipping",
            "line_item_ids": ["line_1"],
            "selected_destination_id": "dest_1",
            "destinations": [
               {
                 "id": "dest_1",
                 "postal_code": "94043",
                 "country": "US",
                 "address_locality": "Mountain View",
                 "address_region": "CA"
               }
            ],
            "groups": [
              {
                "id": "group_1",
                "line_item_ids": ["line_1"],
                "selected_option_id": "ship_ground",
                "options": [
                  {
                    "id": "ship_ground",
                    "title": "Ground (3-5 days)",
                    "total": 500
                  },
                  {
                    "id": "ship_express",
                    "title": "Express (1-2 days)",
                    "total": 1500
                  }
                ]
              }
            ]
          }
      ]
  }
}

4. إكمال جلسة الدفع

تتيح نقطة النهاية هذه إكمال جلسة دفع وتقديم طلب. يجب أن تعرض هذه الطريقة جلسة الدفع المكتملة وأن تتضمّن معلومات الطلب. يجب أن تبدأ عملية معالجة الدفع بعد تلقّي هذه المكالمة.

• نقطة النهاية: POST /checkout-sessions/{id}/complete
• الإجراء: ينقر المستخدم على "تقديم الطلب".

الطلب: ترسل Google الرمز المميّز للدفع (كائن ثنائي كبير الحجم مشفّر) من مقدّم الخدمة (مثل ‫Google Pay)، وإشارات المخاطر حول المشتري لتتمكّن من رصد عمليات الاحتيال بنفسك.

{
  "payment_data": {
    "id": "pi_gpay_5678",
    "handler_id": "gpay",
    "type": "card",
    "brand": "mastercard",
    "last_digits": "5678",
    "billing_address": {
      "postal_code": "94043",
      "address_country": "US"
    },
    "credential": {
       "type": "PAYMENT_GATEWAY",
       "token": "{\"signature\":\"...\",\"protocolVersion\":\"ECv2\"...}"
    }
  }
}

الردّ: عليك عرض عنصر الدفع الكامل الذي يشير إلى أنّ الطلب قد اكتمل، بما في ذلك معرّف الطلب وعنوان URL ثابت يؤدي إلى الطلب.

{
  "ucp": {
      "version": "2026-01-11",
      "capabilities": [...]
  },
  "id": "gid://merchant.example.com/Checkout/session_abc123",
  "status": "completed",

  // ... other fields (line_items, currency, etc.)

  "order_id": "gid://merchant.example.com/Order/789",
  "order_permalink_url": "https://merchant.example.com/orders/789"
}

5- إلغاء جلسة الدفع

تلغي نقطة النهاية هذه جلسة دفع.

• نقطة النهاية: POST /checkout-sessions/{id}/cancel

الطلب: تُرسِل Google معرّف جلسة الدفع.

الردّ: عليك إرجاع عنصر الدفع الكامل مع تعديل الحالة إلى canceled.