תהליך תשלום מקורי

השילוב המקורי מחייב אתכם ליצור API בארכיטקטורת REST ש-Google יכולה להפעיל כדי ליצור ולנהל סשנים של מעבר לתשלום.

התהליך הכללי הוא כזה:

1. יצירת סשן של מעבר לתשלום: המשתמש, ואופציונלית סוכן, נמצאים בלולאה שבה הם מוסיפים פריטים לסשן.
2. העברה לממשק משתמש של Google: אחרי שהמשתמש מחליט לבצע תשלום, הסוכן (אם הוא פעיל) מעביר את השליטה לממשק משתמש של Google (כולל נתוני סשן התשלום).
3. מעבר לתשלום ידני: המשתמש ממלא את פרטי התשלום והמשלוח הרגישים ושולח את ההזמנה רק בממשק המשתמש של Google. הנציג לא מעורב בחלק הזה, כדי להבטיח דטרמיניזם.
4. השלמה והחזרה: בממשק המשתמש של Google מוצג הדף 'תודה' לאישור ההזמנה. אפשרות נוספת היא להפנות את המשתמש בחזרה לסוכן, שאולי כבר קיבל הודעה על השלמת הרכישה.

בשלבים הבאים מפורטים נקודות הקצה של ה-API שצריך להטמיע וההתנהגויות שלהן.

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 שולחת את אסימון התשלום (blob מוצפן) מהספק (לדוגמה, ‫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.