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

במדריך הזה מפורטים הפניות טכניות ל-API וסכימות של מטען ייעודי (payload) לגרסה 2026-01-23 של תכונת ההפניה לדף התשלום המקורית של 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"
      }
    ]
  }
}

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

// Response Example: Initialize Session with multiple items.
{
  "ucp": {
    "version": "2026-01-23",
    "capabilities": {
      "dev.ucp.shopping.checkout": [ { "version": "2026-01-23" } ],
      "dev.ucp.shopping.fulfillment": [ { "version": "2026-01-23", "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": "da2e25ec-eef8-41b7-a439-4e62dea41bdc",
  "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": "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": 100
    },
    {
      "type": "total",
      "amount": 13100
    }
  ],
  "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
  }
]

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

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

  • נקודת קצה (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
    }
  ],
  "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": "da2e25ec-eef8-41b7-a439-4e62dea41bdc",
  "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", "amount": 12500 },
     // Shipping cost might change based on new address
     { "type": "fulfillment", "display_text": "Ground Shipping", "amount": 600 },
     // Tax will likely change based on new address
     { "type": "tax", "amount": 1120 },
     { "type": "total", "amount": 14220 }
  ],
  "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
}

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

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

// 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-01-23",
    "capabilities": {
      "dev.ucp.shopping.checkout": [ { "version": "2026-01-23" } ],
      "dev.ucp.shopping.fulfillment": [ { "version": "2026-01-23", "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": "da2e25ec-eef8-41b7-a439-4e62dea41bdc",
  "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": "tax", "display_text": "Estimated Tax", "amount": 1120 },
     { "type": "total", "display_text": "Total", "amount": 14220 }
  ],
  "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"
    }
  ]
}

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

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

בקשה: 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, כדי לציין איזה מידע חסר.

{
  "id": "da2e25ec-eef8-41b7-a439-4e62dea41bdc",
  "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, צריך:

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

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

{
  "ucp": {
      "version": "2026-01-23",
      "capabilities": [...]
  },
  "id": "da2e25ec-eef8-41b7-a439-4e62dea41bdc",
  "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-01-23, אם שגיאה בלוגיקה העסקית שלא ניתן לתקן מונעת יצירה של סשן מעבר לתשלום (למשל, אם כל הפריטים חסרים במלאי), צריך להחזיר קוד HTTP 200 OK.

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

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

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