‫Google משתמשת בטכנולוגיית AI כדי לתרגם תוכן לשפה המועדפת עליך. בתרגומים כאלו עשויות להיות שגיאות.

הטמעה של API בארכיטקטורת REST לתהליך תשלום מובנה

במדריך הזה מפורטים הפניות טכניות ל-API וסכימות של מטען ייעודי (payload) לגרסה 2026-04-08 של תכונת ההפניה לדף התשלום המקורית של Universal Commerce Protocol‏ (UCP).

לפני שיוצרים את נקודות הקצה, חשוב לעיין בסקירה הכללית של תהליך התשלום המקורי כדי להבין את תהליך התשלום ברמה גבוהה, את דרישות האימות ואת כלי הפיתוח.

יצירת סשן של תשלום בקופה

נקודת הקצה הזו מאפשרת ליצור סשן תשלום שמכיל את המוצרים שהמשתמש מעוניין לקנות.

נקודת קצה (endpoint): POST /checkout-sessions
טריגר: משתמש לוחץ על 'קנייה עכשיו' במוצר או על 'תשלום ב-Google' מתוך עגלת הקניות.

בקשה: Google שולחת את פריטי ההזמנה ופרטי כתובת מוגבלים לגבי הקונה, כולל עיר, מדינה ומיקוד.

// Request Example: Create checkout with multiple items.
{
  "line_items": [
    {
      "item": {
        // Must match ID in product feed
        "id": "product_12345"
      },
      "quantity": 1
    },
    {
      "item": {
        // Must match ID in product feed
        "id": "product_67890"
      },
      "quantity": 1
    }
  ],
  "context": {
    "language": "en"
  },
  "fulfillment": {
    "methods": [
      {
        "type": "shipping",
        "line_item_ids": [
          "line_1",
          "line_2"
        ],
        "destinations": [
          {
            "id": "addr_1",
            "address_locality": "Sunnyvale",
            "address_region": "CA",
            "postal_code": "94089",
            "address_country": "US"
          }
        ],
        "selected_destination_id": "addr_1"
      }
    ]
  }
}

תגובה: מחזירים את הסשן שאותחל עם סכומים כוללים, מיסים (בהתחלה משוערים) ויכולות תשלום.

הערה לגבי השדה ucp.status:

השדה ucp.status, שהוצג בגרסה 2026-04-08, מציין את תוצאת היצירה:

‫"success" (או אם לא מציינים): ברירת המחדל. הסשן נוצר, גם עם messages שניתן לשחזר.
"error": יצירת הסשן נכשלה בגלל שגיאה שלא ניתן לתקן (לדוגמה, כל הפריטים חסרים במלאי). במקרה כזה, גוף התשובה צריך להיות אובייקט של תגובת שגיאה, ולא אובייקט של דף תשלום. אפשר לעיין בדוגמה לשגיאה שלא ניתן לתקן בקטע בנושא טיפול בשגיאות.

הערה לגבי שינויים במערך totals:

השדה type בכל אובייקט במערך totals הוא עכשיו מחרוזת פתוחה.
השדה amount יכול להיות עכשיו שלילי (לדוגמה, כדי לייצג הנחות).
אובייקטים ב-totals (כמו type: "fee" ו-type: "tax") יכולים לכלול אופציונלית מערך lines עם פירוט של רכיבי משנה (לדוגמה, עמלות שירות או מיחזור, או פירוט של מיסים ברמה הפרובינציאלית והפדרלית כמו GST, ‏ PST או QST בקנדה).
מחירים שכוללים מס: בשווקים שבהם המחירים כוללים מס, המחיר subtotal צריך לכלול מס, אין צורך לציין את פריט השורה tax, וחובה לציין במפורש את display_text עבור הערכים subtotal ו-fulfillment ב-totals. פרטים נוספים מופיעים במאמר בנושא תמחור שכולל מס.

// Response Example: Initialize Session with multiple items.
{
  "ucp": {
    "version": "2026-04-08",
    "status": "success",
    "capabilities": {
      "dev.ucp.shopping.checkout": [ { "version": "2026-04-08" } ],
      "dev.ucp.shopping.fulfillment": [ { "version": "2026-04-08", "extends": "dev.ucp.shopping.checkout" } ]
    },
    "payment_handlers": {
      "com.google.pay": [
        {
          "id": "8c9202bd-63cc-4241-8d24-d57ce69ea31c",
          "version": "2026-01-23",
          "spec": "https://pay.google.com/gp/p/ucp/2026-01-23/",
          "schema": "https://pay.google.com/gp/p/ucp/2026-01-23/schemas/config.json",
          "config": {
            "api_version": 2,
            "api_version_minor": 0,
            "environment": "TEST",
            "merchant_info": {
              "merchant_name": "Example Merchant",
              "merchant_id": "KWMZPRLQFTYNXSDB",
              "merchant_origin": "checkout.merchant.com"
            },
            "allowed_payment_methods": [
              {
                "type": "CARD",
                "parameters": {
                  "allowed_auth_methods": [ "PAN_ONLY", "CRYPTOGRAM_3DS" ],
                  "allowed_card_networks": [ "AMEX", "DISCOVER", "JCB", "MASTERCARD", "VISA" ],
                  "billing_address_required": true,
                  "billing_address_parameters": {
                    "format": "FULL",
                    "phone_number_required": true
                  }
                },
                "tokenization_specification": {
                  "type": "PAYMENT_GATEWAY",
                  "parameters": {
                    "gateway": "example",
                    "gatewayMerchantId": "exampleGatewayMerchantId"
                  }
                }
              }
            ]
          }
        }
      ]
    }
  },
  "id": "bf8c1b4b-6b1c-4c6a-8f2a-53c2a7c3b2e1",
  "status": "incomplete",
  "messages": [
    {
      "type": "error",
      "code": "missing_buyer_info",
      "path": "$.buyer",
      "content_type": "plain",
      "content": "Buyer information is required for checkout",
      "severity": "recoverable"
    },
    {
      "type": "error",
      "code": "missing_fulfillment_info",
      "path": "$.fulfillment.methods[0].destinations[0]",
      "content_type": "plain",
      "content": "Shipping address is incomplete",
      "severity": "recoverable"
    }
  ],
  "currency": "USD",
  "line_items": [
    {
      "id": "line_1",
      "item": {
        "id": "product_12345",
        "title": "Running Shoes",
        "price": 10000,
        "image_url": "https://merchant.example.com/images/product_12345.png"
      },
      "quantity": 1,
      "totals": [
        {
          "type": "subtotal",
          "amount": 10000
        },
        {
          "type": "total",
          "amount": 10000
        }
      ]
    },
    {
      "id": "line_2",
      "item": {
        "id": "product_67890",
        "title": "T-Shirt",
        "price": 2500,
        "image_url": "https://merchant.example.com/images/product_67890.png"
      },
      "quantity": 1,
      "totals": [
        {
          "type": "subtotal",
          "amount": 2500
        },
        {
          "type": "total",
          "amount": 2500
        }
      ]
    }
  ],
  "totals": [
    {
      "type": "subtotal",
      "display_text": "Subtotal", // Tax-inclusive markets: Set to "Subtotal (including taxes)".
      "amount": 12500 // Tax-inclusive markets: Amount must include tax.
    },
    {
      "type": "fee",
      "display_text": "Fees",
      "amount": 549,
      "lines": [
        { "display_text": "Service Fee", "amount": 399 },
        { "display_text": "Recycling Fee", "amount": 150 }
      ]
    },
    {
      "type": "fulfillment",
      "display_text": "Ground Shipping", // Tax-inclusive markets: Provide display text for fulfillment totals.
      "amount": 500
    },
    {
      "type": "tax", // Tax-inclusive markets: Omit this entry.
      "display_text": "Estimated Tax",
      "amount": 1050
    },
    {
      "type": "total",
      "display_text": "Total",
      "amount": 14599
    }
  ],
  "fulfillment": {
    "methods": [
      {
        "id": "method_shipping",
        "type": "shipping",
        "line_item_ids": [
          "line_1",
          "line_2"
        ],
        "destinations": [
          {
            "id": "addr_1",
            "address_locality": "Sunnyvale",
            "address_region": "CA",
            "postal_code": "94089",
            "address_country": "US"
          }
        ],
        "selected_destination_id": "addr_1",
        "groups": [
          {
            "id": "group_1",
            "line_item_ids": [
              "line_1",
              "line_2"
            ],
            "options": [
              {
                "id": "ship_ground",
                "title": "Ground (3-5 days)",
                "description": "Estimated Delivery: Fri 5/8", // Maximum length: 200 characters.
                "totals": [ {"type": "total", "amount": 500} ]
              },
              {
                "id": "ship_express",
                "title": "Express (1-2 days)",
                "description": "Estimated Delivery: Wed 5/6", // Maximum length: 200 characters.
                "totals": [ {"type": "total", "amount": 1500} ]
              }
            ],
            "selected_option_id": "ship_ground"
          }
        ]
      }
    ]
  },
  "links": [
    {
      "type": "terms_of_service",
      "url": "https://m.com/terms",
      "title": "Terms of Service"
    },
    {
      "type": "privacy_policy",
      "url": "https://m.com/privacy",
      "title": "Privacy Policy"
    }
  ]
}

מחירים כולל מס

בשוקי יעד שבהם המס כלול בסכום הביניים שמוצג ולא מפורט בנפרד, ההטמעה שלכם צריכה לעמוד בדרישות הבאות כשאתם מספקים נתונים של סשן בקופה:

Include tax in the subtotal: בשדה amount של רשומת subtotal צריך לכלול את כל המיסים הרלוונטיים.
אל תכללו רשומות נפרדות של מיסים: אל תכללו אובייקט ייעודי עם type: "tax" במערך totals.
הוספת טקסט תצוגה בהתאמה אישית: צריך לכלול מאפיין display_text באובייקט של סכום הביניים, שבו מצוין במפורש שהמיסים כלולים, למשל "Subtotal (including taxes)". צריך לכלול גם מאפיין display_text של רשומות של מידע על משלוח (לדוגמה, "Shipping").

דוגמה: מערך של סכומים כוללים שכוללים מס

בדוגמה הבאה מוצג מערך totals של מוכר בשוק שכולל מס:

"totals": [
  {
    "type": "subtotal",
    "display_text": "Subtotal (including taxes)",
    "amount": 12500
  },
  {
    "type": "fulfillment",
    "display_text": "Shipping",
    "amount": 399
  },
  {
    "type": "total",
    "display_text": "Total",
    "amount": 12899
  }
]

פירוט פריטי מס בכמה רמות

בשוקי יעד שבהם נדרש פירוט של מיסים בכמה רמות או בכמה אזורי שיפוט (כמו מס GST או HST פדרליים ו-PST או QST פרובינציאליים בקנדה), אפשר לספק אובייקט type: "tax" ברמה העליונה עם מערך lines מקונן:

Aggregate top-level tax: מחזירה אובייקט tax מצטבר יחיד שמכיל את סכום המס הכולל amount ותיאור display_text (לדוגמה, "Taxes").
פירוט של שורות משנה: פירוט של רכיבי מס נפרדים במערך lines עם הערכים המתאימים של display_text (למשל "TPS / GST (5%)", "TVQ / QST (9.975%)") ושל amount.
כלל קבוע: סכום כל הסכומים של פריטי המשנה חייב להיות שווה לערך amount של רשומת האב tax.

דוגמה: פירוט מס רב-שכבתי

{
  "type": "tax",
  "display_text": "Taxes",
  "amount": 1498,
  "lines": [
    { "display_text": "TPS / GST (5%)", "amount": 500 },
    { "display_text": "TVQ / QST (9.975%)", "amount": 998 }
  ]
}

קבלת סשן מעבר לקופה

נקודת הקצה הזו מאפשרת לאחזר סשן של תהליך תשלום.

נקודת קצה (endpoint): GET /checkout-sessions/{id}

בקשה: Google שולחת את המזהה של סשן התשלום. אם אתם משתמשים במזהים גלובליים (למשל gid://merchant.example.com/Checkout/session_abc123), שימו לב שהמזהה בנתיב הבקשה יהיה רק הרכיב האחרון של המזהה הזה (למשל session_abc123).

תגובה: מחזירים את אובייקט הקופה המלא. בסשן עם כמה פריטים שנוצר בגרסה 2026-01-23 ואילך, המערך line_items יכיל כמה רשומות של פריטים.

עדכון סשן של תשלום בקופה

נקודת הקצה הזו מאפשרת לעדכן סשן של תהליך תשלום. כשמעדכנים את כתובת המשלוח, צריך לחשב מחדש את המיסים ואת אפשרויות המשלוח ולהחזיר אותם.

נקודת קצה (endpoint): PUT /checkout-sessions/{id}

עדכון הכתובת למשלוח

הפעלה: המשתמש בוחר או משנה את הכתובת למשלוח.

בקשה: Google מעדכנת את כתובת המשלוח כשהמשתמש משנה את כתובת המשלוח שלו.

// Request Example: Update shipping address with multiple items.
{
  "line_items": [
    {
      // line_items id from Create Checkout response
      "id": "line_1",
      "item": {
        "id": "product_12345"
      },
      "quantity": 1
    },
    {
      // line_items id from Create Checkout response
      "id": "line_2",
      "item": {
        "id": "product_67890"
      },
      "quantity": 1
    }
  ],
  "context": {
    "language": "en"
  },
  "fulfillment": {
    "methods": [
      {
        "id": "method_shipping",
        "type": "shipping",
        "line_item_ids": [
          "line_1",
          "line_2"
        ],
        "destinations": [
          {
            "id": "addr_1",
            "address_locality": "Mountain View",
            "address_region": "CA",
            "postal_code": "94043",
            "address_country": "US"
          }
        ],
        "selected_destination_id": "addr_1",
        "groups": [
          {
            "id": "group_1",
            "selected_option_id": "ship_ground"
          }
        ]
      }
    ]
  }
}

תגובה: מחשבים מחדש את המיסים ואת אפשרויות המשלוח לפי הצורך ומחזירים את אובייקט הקופה המלא.

// Response Example: Updated session with new address for multiple items.
{
  "id": "bf8c1b4b-6b1c-4c6a-8f2a-53c2a7c3b2e1",
  "currency": "USD",
  "line_items": [
    {
      "id": "line_1",
      "item": {
        "id": "product_12345",
        "title": "Running Shoes",
        "price": 10000,
        "image_url": "https://merchant.example.com/images/product_12345.png"
      },
      "quantity": 1,
      "totals": [
        { "type": "subtotal", "amount": 10000 },
        { "type": "total", "amount": 10000 }
      ]
    },
    {
      "id": "line_2",
      "item": {
        "id": "product_67890",
        "title": "T-Shirt",
        "price": 2500,
        "image_url": "https://merchant.example.com/images/product_67890.png"
      },
      "quantity": 1,
      "totals": [
        { "type": "subtotal", "amount": 2500 },
        { "type": "total", "amount": 2500 }
      ]
    }
  ],
  "totals": [
     { "type": "subtotal", "display_text": "Subtotal", "amount": 12500 },
     // Shipping cost might change based on new address
     { "type": "fulfillment", "display_text": "Ground Shipping", "amount": 600 },
     {
       "type": "fee",
       "display_text": "Fees",
       "amount": 549,
       "lines": [
         { "display_text": "Service Fee", "amount": 399 },
         { "display_text": "Recycling Fee", "amount": 150 }
       ]
     },
     // Tax will likely change based on new address
     { "type": "tax", "display_text": "Estimated Tax", "amount": 1120 },
     { "type": "total", "display_text": "Total", "amount": 14769 }
  ],
  "fulfillment": {
    "methods": [
      {
        "id": "method_shipping",
        "type": "shipping",
        "line_item_ids": ["line_1", "line_2"],
        "selected_destination_id": "addr_1",
        "destinations": [
          {
            "id": "addr_1",
            "address_locality": "Mountain View",
            "address_region": "CA",
            "postal_code": "94043",
            "address_country": "US"
          }
        ],
        "groups": [
          {
            "id": "group_1",
            "line_item_ids": ["line_1", "line_2"],
            "selected_option_id": "ship_ground",
            "options": [
              {
                "id": "ship_ground",
                "title": "Ground (3-5 days)",
                "description": "Estimated Delivery: Fri 5/8", // Maximum length: 200 characters.
                "totals": [ { "type": "total", "amount": 600 } ]
              },
              {
                "id": "ship_express",
                "title": "Express (1-2 days)",
                "description": "Estimated Delivery: Wed 5/6", // Maximum length: 200 characters.
                "totals": [ { "type": "total", "amount": 1600 } ]
              }
            ]
          }
        ]
      }
    ]
  }
  // ... other fields like ucp, status, messages, links
}

השלמת הנתונים של אובייקט התשלום בקופה

בקשה: Google שולחת את אובייקט התשלום המלא עם המידע המעודכן (כולל כתובת המשלוח המלאה והפרטים ליצירת קשר עם הקונה) כשהקונה לוחץ על 'תשלום באמצעות GPay'.

// Request Example: full checkout object hydration for multiple items.
{
  "buyer": {
    "first_name": "John",
    "last_name": "Buyer",
    "email": "johnbuyer@example.com",
    "phone_number": "+18888888888"
  },
  "line_items": [
    {
      "id": "line_1",
      "item": { "id": "product_12345" },
      "quantity": 1
    },
    {
      "id": "line_2",
      "item": { "id": "product_67890" },
      "quantity": 1
    }
  ],
  "fulfillment": {
    "methods": [
      {
        "id": "method_shipping",
        "type": "shipping",
        "line_item_ids": ["line_1", "line_2"],
        "selected_destination_id": "addr_1",
        "destinations": [
          {
            "id": "addr_1",
            "first_name": "Alice",
            "last_name": "Receiver",
            "street_address": "1600 Amphitheatre Pkwy",
            "extended_address": "Suite #60",
            "address_locality": "Mountain View",
            "address_region": "CA",
            "postal_code": "94043",
            "address_country": "US",
            "phone_number": "+18888888888"
          }
        ],
        "groups": [
          {
            "id": "group_1",
            "selected_option_id": "ship_ground"
          }
        ]
      }
    ]
  }
}

תגובה: מחשבים מחדש את המיסים ואת אפשרויות המשלוח לפי הצורך ומחזירים את אובייקט הקופה המלא.

// Response Example: Session after full hydration with multiple items.
{
  "ucp": {
    "version": "2026-04-08",
    "status": "success",
    "capabilities": {
      "dev.ucp.shopping.checkout": [ { "version": "2026-04-08" } ],
      "dev.ucp.shopping.fulfillment": [ { "version": "2026-04-08", "extends": "dev.ucp.shopping.checkout" } ]
    },
    "payment_handlers": {
      "com.google.pay": [
        {
          "id": "8c9202bd-63cc-4241-8d24-d57ce69ea31c",
          "version": "2026-01-23",
          "spec": "https://pay.google.com/gp/p/ucp/2026-01-23/",
          "schema": "https://pay.google.com/gp/p/ucp/2026-01-23/schemas/config.json",
          "config": {
            "api_version": 2,
            "api_version_minor": 0,
            "environment": "TEST",
            "merchant_info": {
              "merchant_name": "Example Merchant",
              "merchant_id": "KWMZPRLQFTYNXSDB",
              "merchant_origin": "checkout.merchant.com"
            },
            "allowed_payment_methods": [
              {
                "type": "CARD",
                "parameters": {
                  "allowed_auth_methods": [ "PAN_ONLY", "CRYPTOGRAM_3DS" ],
                  "allowed_card_networks": [ "AMEX", "DISCOVER", "JCB", "MASTERCARD", "VISA" ],
                  "billing_address_required": true,
                  "billing_address_parameters": {
                    "format": "FULL",
                    "phone_number_required": true
                  }
                },
                "tokenization_specification": {
                  "type": "PAYMENT_GATEWAY",
                  "parameters": {
                    "gateway": "example",
                    "gatewayMerchantId": "exampleGatewayMerchantId"
                  }
                }
              }
            ]
          }
        }
      ]
    }
  },
  "id": "bf8c1b4b-6b1c-4c6a-8f2a-53c2a7c3b2e1",
  "status": "ready_for_complete",
  "currency": "USD",
  "buyer": {
    "first_name": "John",
    "last_name": "Buyer",
    "email": "johnbuyer@example.com",
    "phone_number": "+18888888888"
  },
  "line_items": [
    {
      "id": "line_1",
      "item": {
        "id": "product_12345",
        "title": "Running Shoes",
        "price": 10000,
        "image_url": "https://merchant.example.com/images/product_12345.png"
      },
      "quantity": 1,
      "totals": [
        { "type": "subtotal", "amount": 10000 },
        { "type": "total", "amount": 10000 }
      ]
    },
    {
      "id": "line_2",
      "item": {
        "id": "product_67890",
        "title": "T-Shirt",
        "price": 2500,
        "image_url": "https://merchant.example.com/images/product_67890.png"
      },
      "quantity": 1,
      "totals": [
        { "type": "subtotal", "amount": 2500 },
        { "type": "total", "amount": 2500 }
      ]
    }
  ],
  "totals": [
     { "type": "subtotal", "display_text": "Subtotal", "amount": 12500 },
     { "type": "fulfillment", "display_text": "Ground Shipping", "amount": 600 },
      {
        "type": "fee",
        "display_text": "Fees",
        "amount": 549,
        "lines": [
          { "display_text": "Service Fee", "amount": 399 },
          { "display_text": "Recycling Fee", "amount": 150 }
        ]
      },
     { "type": "tax", "display_text": "Estimated Tax", "amount": 1120 },
     { "type": "total", "display_text": "Total", "amount": 14769 }
  ],
  "fulfillment": {
    "methods": [
      {
        "id": "method_shipping",
        "type": "shipping",
        "line_item_ids": ["line_1", "line_2"],
        "selected_destination_id": "addr_1",
        "destinations": [
          {
            "id": "addr_1",
            "first_name": "Alice",
            "last_name": "Receiver",
            "street_address": "1600 Amphitheatre Pkwy",
            "extended_address": "Suite #60",
            "address_locality": "Mountain View",
            "address_region": "CA",
            "postal_code": "94043",
            "address_country": "US",
            "phone_number": "+18888888888"
          }
        ],
        "groups": [
          {
            "id": "group_1",
            "line_item_ids": ["line_1", "line_2"],
            "selected_option_id": "ship_ground",
            "options": [
              {
                "id": "ship_ground",
                "title": "Ground (3-5 days)",
                "description": "Estimated Delivery: Fri 5/8", // Maximum length: 200 characters.
                "totals": [ { "type": "total", "amount": 600 } ]
              },
              {
                "id": "ship_express",
                "title": "Express (1-2 days)",
                "description": "Estimated Delivery: Wed 5/6", // Maximum length: 200 characters.
                "totals": [ { "type": "total", "amount": 1600 } ]
              }
            ]
          }
        ]
      }
    ]
  },
  "links": [
    {
      "type": "terms_of_service",
      "url": "https://m.com/terms",
      "title": "Terms of Service"
    },
    {
      "type": "privacy_policy",
      "url": "https://m.com/privacy",
      "title": "Privacy Policy"
    }
  ]
}

השלמת סשן של תשלום בקופה

נקודת הקצה הזו מאפשרת להשלים סשן של תשלום בקופה ולבצע הזמנה. היא צריכה להחזיר את סשן התשלום שהושלם ולכלול את פרטי ההזמנה. עיבוד התשלום צריך להתחיל אחרי קבלת השיחה הזו.

נקודת קצה (endpoint): POST /checkout-sessions/{id}/complete
טריגר: המשתמש לוחץ על 'תשלום באמצעות GPay', ו-Google מקבלת תגובה מוצלחת מעדכון של דף התשלום עם כל הנתונים.

בקשה: Google שולחת את אמצעי התשלום שנבחר מתוך רכיב הטיפול בתשלומים, כולל פרטי הכניסה (למשל נתוני טוקניזציה של Google Pay) ואותות סיכון לגבי הקונה, כדי שתוכלו לבצע זיהוי הונאות משלכם. התוכן של הטוקן תלוי בספק שירות התשלומים שלכם.

{
  "payment": {
    "instruments": [
      {
        "billing_address": {
          "first_name": "John",
          "last_name": "Buyer",
          "street_address": "100 Main St",
          "extended_address": "Apt 4B",
          "address_locality": "San Francisco",
          "address_region": "CA",
          "postal_code": "94105",
          "address_country": "US",
          "phone_number": "+18888888888"
        },
        "credential": {
          "token": "examplePaymentMethodToken",
          "type": "PAYMENT_GATEWAY"
        },
        "display": {
          "brand": "VISA",
          "description": "Visa •••• 1234",
          "last_digits": "1234"
        },
        "handler_id": "8c9202bd-63cc-4241-8d24-d57ce69ea31c",
        "id": "94e7fee0-1a82-4c2a-9ef4-0861a3c829b2",
        "selected": true,
        "type": "card"
      }
    ]
  },
  "signals": {
    "com.google.authentication_triggered": "",
    "com.google.authorization_processed_with_3ds": "",
    "com.google.avs_full_result": "",
    "com.google.cvv_result": "",
    "com.google.ip_address": "203.0.113.1",
    "dev.ucp.buyer_id": "ec46fedc6aad89d3660a50a61d00b4908fd160ecf5dda6d49ed41a605c5b180a",
    "dev.ucp.buyer_ip": "203.0.113.1"
  }
}

אם אתם צריכים מידע חובה כדי להשלים את תהליך התשלום, והמידע הזה לא סופק במהלך סשן התשלום, אתם יכולים למנוע את השלמת התשלום ולבקש את המידע הזה על ידי החזרת סטטוס לא מלא בתגובה.

אם Google יכולה לאסוף את המידע החסר באמצעות שדות שמוגדרים ב-UCP (לדוגמה, כתובת האימייל של הקונה), צריך להגדיר את status כ-incomplete ולכלול הודעה אחת או יותר במערך messages עם severity שמוגדר כ-recoverable, כדי לציין איזה מידע חסר.

{
  "ucp": {
    "version": "2026-04-08",
    "status": "success"
  },
  "id": "bf8c1b4b-6b1c-4c6a-8f2a-53c2a7c3b2e1",
  "status": "incomplete",
  "messages": [
    {
      "type": "error",
      "code": "missing_buyer_info",
      "severity": "recoverable",
      "content": "Buyer email is required"
    },
    {
      "type": "error",
      "code": "missing_fulfillment_info",
      "severity": "recoverable",
      "content": "Select delivery window for your purchase"
    }
  ]
}

כשמקבלים אמצעי תשלום ב-Google Pay, צריך:

בדיקת תקינות של רכיב handler: מוודאים שהערך handler_id תואם לרכיב handler של Google Pay שמוגדר בהגדרות.
שליפת טוקן: מאחזרים את הטוקן של אמצעי התשלום שנוצר מ-payment.instruments[0].credential.token.
עיבוד התשלום: שימוש בטוקן ובפרטי העסקה כדי להשלים את התשלום. במסמכי ה-API של Google Pay מופיע תיעוד מפורט על מפרט וטיפול בטוקניזציה.

תגובה: אם אפשר להשלים את תהליך התשלום ועיבדתם את התשלום, אתם מחזירים את אובייקט התשלום המלא שמציין שההזמנה הושלמה, כולל אמצעי התשלום המאושר (שיקוף של מטא-נתונים של אמצעי התשלום וכתובת לחיוב, ללא טוקן credential או signals רגיש), מזהה ההזמנה וכתובת URL של קישור קבוע להזמנה.

{
  "ucp": {
      "version": "2026-04-08",
      "status": "success",
      "capabilities": [...]
  },
  "id": "bf8c1b4b-6b1c-4c6a-8f2a-53c2a7c3b2e1",
  "status": "completed",

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

  "payment": {
    "instruments": [
      {
        "id": "94e7fee0-1a82-4c2a-9ef4-0861a3c829b2",
        "handler_id": "8c9202bd-63cc-4241-8d24-d57ce69ea31c",
        "type": "card",
        "selected": true,
        "display": {
          "brand": "VISA",
          "description": "Visa •••• 1234",
          "last_digits": "1234"
        },
        "billing_address": {
          "first_name": "John",
          "last_name": "Buyer",
          "street_address": "100 Main St",
          "extended_address": "Apt 4B",
          "address_locality": "San Francisco",
          "address_region": "CA",
          "postal_code": "94105",
          "address_country": "US",
          "phone_number": "+18888888888"
        }
      }
    ]
  },
  "order": {
    "id": "ORD1773956535.2727807",
    // Example customer-facing order number
    "label": "#100",
    "permalink_url": "https://merchant.example.com/orders/789"
  }
}

ביטול סשן תשלום

נקודת הקצה הזו מבטלת סשן של מעבר לתשלום.

נקודת קצה (endpoint): POST /checkout-sessions/{id}/cancel

בקשה: Google שולחת את המזהה של סשן התשלום.

תגובה: מחזירים את אובייקט התשלום המלא עם הסטטוס המעודכן לערך canceled.

טיפול בשגיאות

הנחיות מלאות לגבי הפורמט של הודעות שגיאה וההבדל בין שגיאות בפרוטוקול לבין שגיאות בלוגיקה העסקית מופיעות במאמר סקירה כללית על קודי שגיאה.

שגיאה שבעקבותיה אי אפשר לשחזר

החל מגרסה 2026-04-08, אם שגיאה שלא ניתן לשחזר מונעת יצירה של סשן מעבר לתשלום (למשל, אם כל הפריטים חסרים במלאי), צריך להחזיר HTTP 200 OK. בגוף התגובה, מגדירים את "status": "error" באובייקט ucp. ההודעה הזו מציינת שהבקשה הייתה תקינה, אבל כלל עסקי חסם את יצירת הסשן. במקרה כזה, לא מוחזר מזהה סשן של דף התשלום.

HTTP/1.1 200 OK
Content-Type: application/json

{
  "ucp": {
    "version": "2026-04-08",
    "status": "error"
  },
  "messages": [
    {
      "type": "error",
      "code": "out_of_stock",
      "content": "All requested items are currently out of stock",
      "severity": "unrecoverable"
    }
  ],
  "continue_url": "https://merchant.com/"
}