پیاده‌سازی API REST برای پرداخت بومی، پیاده‌سازی API REST برای پرداخت بومی

این راهنما مرجع فنی API و طرحواره‌های بار داده برای نسخه 2026-01-23 از پرداخت بومی پروتکل تجارت جهانی (UCP) را ارائه می‌دهد.

قبل از ساخت نقاط پایانی خود، مطمئن شوید که نمای کلی پرداخت بومی را برای جریان پرداخت سطح بالا، الزامات احراز هویت و ابزارهای توسعه‌دهنده بررسی کرده‌اید.

ایجاد جلسه پرداخت

این نقطه پایانی امکان ایجاد یک جلسه پرداخت شامل محصولاتی را که کاربر به خرید آنها علاقه‌مند است، فراهم می‌کند.

  • نقطه پایانی: POST /checkout-sessions
  • فعال‌کننده: کاربر روی «همین حالا بخرید» روی یک محصول یا «پرداخت در گوگل» از سبد خرید کلیک می‌کند.

درخواست: گوگل موارد مورد نظر و اطلاعات محدودی از آدرس خریدار، شامل شهر، استان و کد پستی را ارسال می‌کند.

// 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
    }
  ],
  "fulfillment": {
    "methods": [
      {
        "type": "shipping",
        "destinations": [
          {
            "address_locality": "Sunnyvale",
            "address_region": "CA",
            "postal_code": "94089",
            "address_country": "US"
          }
        ]
      }
    ]
  }
}

پاسخ: شما جلسه اولیه را با جمع کل، مالیات (تخمین اولیه) و قابلیت‌های پرداخت برمی‌گردانید.

// 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" ],
                  "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": "Shipping", // Tax-inclusive markets: Provide display text for fulfillment totals.
      "amount": 0
    },
    {
      "type": "tax", // Tax-inclusive markets: Omit this entry.
      "display_text": "Estimated Tax",
      "amount": 100
    },
    {
      "type": "total",
      "amount": 12600
    }
  ],
  "fulfillment": {
    "methods": [
      {
        "id": "method1",
        "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": "fg1",
            "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"
    }
  ]
}

قیمت‌گذاری شامل مالیات

برای بازارهایی که مالیات در جمع جزئی نمایش داده شده به جای جزئیات جداگانه لحاظ می‌شود، پیاده‌سازی شما باید هنگام ارائه داده‌های جلسه پرداخت، الزامات زیر را رعایت کند:

  • مالیات را در جمع جزئی لحاظ کنید: فیلد amount برای ورودی subtotal باید شامل تمام مالیات‌های مربوطه باشد.
  • حذف ورودی‌های جداگانه مالیات: یک شیء اختصاصی با type: "tax" را در آرایه totals قرار ندهید.
  • متن نمایشی سفارشی ارائه دهید: شما باید یک ویژگی display_text در شیء subtotal قرار دهید که به صراحت بیان کند مالیات‌ها شامل می‌شوند، مانند "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
  }
]

دریافت جلسه تسویه حساب

این نقطه پایانی امکان بازیابی یک جلسه پرداخت را فراهم می‌کند.

  • نقطه پایانی: GET /checkout-sessions/{id}

درخواست: گوگل شناسه‌ی جلسه‌ی پرداخت را ارسال می‌کند. اگر از شناسه‌های سراسری (Global IDs) استفاده می‌کنید (مثلاً gid://merchant.example.com/Checkout/session_abc123 )، توجه داشته باشید که شناسه‌ی موجود در مسیر درخواست، تنها آخرین جزء این شناسه خواهد بود (مثلاً session_abc123 ).

پاسخ: شما شیء پرداخت کامل را برمی‌گردانید. برای یک جلسه چند موردی که تحت نسخه 2026-01-23 یا بالاتر ایجاد شده است، آرایه line_items شامل چندین ورودی کالا خواهد بود.

جلسه تسویه حساب را به‌روزرسانی کنید

این نقطه پایانی امکان به‌روزرسانی جلسه پرداخت را فراهم می‌کند. وقتی آدرس ارسال به‌روزرسانی می‌شود، باید مالیات و گزینه‌های ارسال را دوباره محاسبه و برگرداند.

  • نقطه پایانی: PUT /checkout-sessions/{id}

به‌روزرسانی آدرس حمل و نقل

  • فعال‌ساز: کاربر آدرس ارسال خود را انتخاب یا تغییر می‌دهد.

درخواست: گوگل وقتی کاربر آدرس ارسال خود را تغییر می‌دهد، آدرس تحویل سفارش را به‌روزرسانی می‌کند.

// 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": [
      {
        "type": "shipping",
        "line_item_ids": [
          "line_1",
          "line_2"
        ],
        "destinations": [
          {
            "address_locality": "Mountain View",
            "address_region": "CA",
            "postal_code": "94043",
            "address_country": "US"
          }
        ],
        "groups": [
          {
            "id": "group1",
             "line_item_ids": [
              "line_1",
              "line_2"
            ],
            "options": [
              {
                "id": "ship_ground"
              }
            ],
            "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 } ]
              }
            ]
          }
        ]
      }
    ]
  }
  // ... other fields like ucp, status, messages, links
}

آبرسانی کامل به شیء پرداخت

درخواست: گوگل وقتی خریدار روی «پرداخت با 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
    }
  ],
  "payment": {
    "instruments": [
      {
        "id": "gpay",
        "handler_id": "8c9202bd-63cc-4241-8d24-d57ce69ea31c",
        "type": "com.google.pay",
        "selected": true
      }
    ]
  },
  "fulfillment": {
    "methods": [
      {
        "type": "shipping",
        "line_item_ids": ["line_1", "line_2"],
        "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"
          }
        ],
        "groups": [
          {
            "id": "group_1",
             "line_item_ids": ["line_1", "line_2"],
            "options": [ { "id": "ship_ground" } ],
            "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" ],
                  "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 }
  ],
  "payment": {
    "instruments": [
      {
        "id": "gpay",
        "handler_id": "8c9202bd-63cc-4241-8d24-d57ce69ea31c",
        "type": "com.google.pay",
        "selected": true
      }
    ]
  },
  "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"
          }
        ],
        "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 } ]
              }
            ]
          }
        ]
      }
    ]
  },
  "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"
    }
  ]
}

جلسه تسویه حساب کامل

این نقطه پایانی امکان تکمیل جلسه پرداخت و ثبت سفارش را فراهم می‌کند. این نقطه باید جلسه پرداخت تکمیل‌شده را برگرداند و شامل اطلاعات سفارش باشد. پردازش پرداخت باید پس از دریافت این تماس آغاز شود.

درخواست: گوگل ابزار پرداخت انتخاب‌شده از طرف مدیریت‌کننده پرداخت، شامل اطلاعات احراز هویت (مثلاً داده‌های توکن‌سازی گوگل پی ) و سیگنال‌های ریسک مربوط به خریدار را برای شما ارسال می‌کند تا بتوانید تشخیص کلاهبرداری را خودتان انجام دهید. محتوای توکن به ارائه‌دهنده خدمات پرداخت شما بستگی دارد.

{
  "payment": {
    "instruments": [
      {
        "billing_address": {
          "first_name": "John",
          "last_name": "Buyer",
          "street_address": "1600 Amphitheatre Pkwy",
          "address_locality": "Mountain View",
          "address_region": "CA",
          "postal_code": "94043",
          "address_country": "US"
        },
        "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": {} // Placeholder for risk signals
}

اگر برای تکمیل پرداخت به اطلاعات اجباری نیاز دارید که در جلسه پرداخت ارائه نشده است، می‌توانید با برگرداندن وضعیت ناقص در پاسخ، از تکمیل پرداخت جلوگیری کرده و آن اطلاعات را درخواست کنید.

اگر گوگل می‌تواند اطلاعات از دست رفته را با استفاده از فیلدهای تعریف شده توسط 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_id مربوط به کنترل‌کننده پرداخت Google Pay است.
  2. استخراج توکن: توکن روش پرداخت تولید شده را از payment_data.credential.token بازیابی کنید.
  3. پردازش پرداخت: برای تکمیل پرداخت از توکن و جزئیات تراکنش استفاده کنید. برای مشاهده مستندات دقیق در مورد مشخصات و نحوه‌ی توکن‌سازی، به مستندات API گوگل پی مراجعه کنید.

پاسخ: اگر پرداخت تکمیل شده باشد و شما پرداخت را پردازش کرده باشید، شیء پرداخت کامل را که نشان می‌دهد سفارش کامل شده است، شامل شناسه سفارش و یک URL پیوند دائمی به سفارش، برمی‌گردانید. 

{
  "ucp": {
      "version": "2026-01-23",
      "capabilities": [...]
  },
  "id": "da2e25ec-eef8-41b7-a439-4e62dea41bdc",
  "status": "completed",

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

  "order": {
    "id": "ORD1773956535.2727807",
    // Example customer-facing order number
    "label": "#100",
    "permalink_url": "https://merchant.example.com/orders/789"
  }
}

لغو جلسه پرداخت

این نقطه پایانی، جلسه پرداخت را لغو می‌کند.

  • نقطه پایانی: POST /checkout-sessions/{id}/cancel

درخواست: گوگل شناسه جلسه پرداخت را ارسال می‌کند.

پاسخ: شما شیء پرداخت کامل را با وضعیت به‌روزرسانی‌شده به canceled برمی‌گردانید.

مدیریت خطا

برای راهنمایی‌های کامل در مورد نحوه قالب‌بندی پیام‌های خطا و تمایز بین خطاهای پروتکل و منطق کسب‌وکار، به نمای کلی کدهای خطا مراجعه کنید.

خطای غیرقابل بازیابی

برای نسخه 2026-01-23 ‎، هنگامی که یک خطای منطقی غیرقابل بازیابی مانع از ایجاد جلسه پرداخت می‌شود (مثلاً همه اقلام موجود نیستند)، یک HTTP 200 OK برگردانید.

در نسخه 2026-01-23 ، شما باید با حذف شناسه جلسه پرداخت و مشخص کردن "severity": "unrecoverable" در آرایه messages ، خرابی ترمینال را مشخص کنید. این به گوگل می‌گوید که درخواست معتبر بوده، اما یک قانون تجاری ایجاد جلسه را مسدود کرده است. 

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/"
}
،

این راهنما مرجع فنی API و طرحواره‌های بار داده برای نسخه 2026-01-23 از پرداخت بومی پروتکل تجارت جهانی (UCP) را ارائه می‌دهد.

قبل از ساخت نقاط پایانی خود، مطمئن شوید که نمای کلی پرداخت بومی را برای جریان پرداخت سطح بالا، الزامات احراز هویت و ابزارهای توسعه‌دهنده بررسی کرده‌اید.

ایجاد جلسه پرداخت

این نقطه پایانی امکان ایجاد یک جلسه پرداخت شامل محصولاتی را که کاربر به خرید آنها علاقه‌مند است، فراهم می‌کند.

  • نقطه پایانی: POST /checkout-sessions
  • فعال‌کننده: کاربر روی «همین حالا بخرید» روی یک محصول یا «پرداخت در گوگل» از سبد خرید کلیک می‌کند.

درخواست: گوگل موارد مورد نظر و اطلاعات محدودی از آدرس خریدار، شامل شهر، استان و کد پستی را ارسال می‌کند.

// 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
    }
  ],
  "fulfillment": {
    "methods": [
      {
        "type": "shipping",
        "destinations": [
          {
            "address_locality": "Sunnyvale",
            "address_region": "CA",
            "postal_code": "94089",
            "address_country": "US"
          }
        ]
      }
    ]
  }
}

پاسخ: شما جلسه اولیه را با جمع کل، مالیات (تخمین اولیه) و قابلیت‌های پرداخت برمی‌گردانید.

// 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" ],
                  "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": "Shipping", // Tax-inclusive markets: Provide display text for fulfillment totals.
      "amount": 0
    },
    {
      "type": "tax", // Tax-inclusive markets: Omit this entry.
      "display_text": "Estimated Tax",
      "amount": 100
    },
    {
      "type": "total",
      "amount": 12600
    }
  ],
  "fulfillment": {
    "methods": [
      {
        "id": "method1",
        "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": "fg1",
            "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"
    }
  ]
}

قیمت‌گذاری شامل مالیات

برای بازارهایی که مالیات در جمع جزئی نمایش داده شده به جای جزئیات جداگانه لحاظ می‌شود، پیاده‌سازی شما باید هنگام ارائه داده‌های جلسه پرداخت، الزامات زیر را رعایت کند:

  • مالیات را در جمع جزئی لحاظ کنید: فیلد amount برای ورودی subtotal باید شامل تمام مالیات‌های مربوطه باشد.
  • حذف ورودی‌های جداگانه مالیات: یک شیء اختصاصی با type: "tax" را در آرایه totals قرار ندهید.
  • متن نمایشی سفارشی ارائه دهید: شما باید یک ویژگی display_text در شیء subtotal قرار دهید که به صراحت بیان کند مالیات‌ها شامل می‌شوند، مانند "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
  }
]

دریافت جلسه تسویه حساب

این نقطه پایانی امکان بازیابی یک جلسه پرداخت را فراهم می‌کند.

  • نقطه پایانی: GET /checkout-sessions/{id}

درخواست: گوگل شناسه‌ی جلسه‌ی پرداخت را ارسال می‌کند. اگر از شناسه‌های سراسری (Global IDs) استفاده می‌کنید (مثلاً gid://merchant.example.com/Checkout/session_abc123 )، توجه داشته باشید که شناسه‌ی موجود در مسیر درخواست، تنها آخرین جزء این شناسه خواهد بود (مثلاً session_abc123 ).

پاسخ: شما شیء پرداخت کامل را برمی‌گردانید. برای یک جلسه چند موردی که تحت نسخه 2026-01-23 یا بالاتر ایجاد شده است، آرایه line_items شامل چندین ورودی کالا خواهد بود.

جلسه تسویه حساب را به‌روزرسانی کنید

این نقطه پایانی امکان به‌روزرسانی جلسه پرداخت را فراهم می‌کند. وقتی آدرس ارسال به‌روزرسانی می‌شود، باید مالیات و گزینه‌های ارسال را دوباره محاسبه و برگرداند.

  • نقطه پایانی: PUT /checkout-sessions/{id}

به‌روزرسانی آدرس حمل و نقل

  • فعال‌ساز: کاربر آدرس ارسال خود را انتخاب یا تغییر می‌دهد.

درخواست: گوگل وقتی کاربر آدرس ارسال خود را تغییر می‌دهد، آدرس تحویل سفارش را به‌روزرسانی می‌کند.

// 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": [
      {
        "type": "shipping",
        "line_item_ids": [
          "line_1",
          "line_2"
        ],
        "destinations": [
          {
            "address_locality": "Mountain View",
            "address_region": "CA",
            "postal_code": "94043",
            "address_country": "US"
          }
        ],
        "groups": [
          {
            "id": "group1",
             "line_item_ids": [
              "line_1",
              "line_2"
            ],
            "options": [
              {
                "id": "ship_ground"
              }
            ],
            "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 } ]
              }
            ]
          }
        ]
      }
    ]
  }
  // ... other fields like ucp, status, messages, links
}

آبرسانی کامل به شیء پرداخت

درخواست: گوگل وقتی خریدار روی «پرداخت با 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
    }
  ],
  "payment": {
    "instruments": [
      {
        "id": "gpay",
        "handler_id": "8c9202bd-63cc-4241-8d24-d57ce69ea31c",
        "type": "com.google.pay",
        "selected": true
      }
    ]
  },
  "fulfillment": {
    "methods": [
      {
        "type": "shipping",
        "line_item_ids": ["line_1", "line_2"],
        "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"
          }
        ],
        "groups": [
          {
            "id": "group_1",
             "line_item_ids": ["line_1", "line_2"],
            "options": [ { "id": "ship_ground" } ],
            "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" ],
                  "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 }
  ],
  "payment": {
    "instruments": [
      {
        "id": "gpay",
        "handler_id": "8c9202bd-63cc-4241-8d24-d57ce69ea31c",
        "type": "com.google.pay",
        "selected": true
      }
    ]
  },
  "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"
          }
        ],
        "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 } ]
              }
            ]
          }
        ]
      }
    ]
  },
  "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"
    }
  ]
}

جلسه تسویه حساب کامل

این نقطه پایانی امکان تکمیل جلسه پرداخت و ثبت سفارش را فراهم می‌کند. این نقطه باید جلسه پرداخت تکمیل‌شده را برگرداند و شامل اطلاعات سفارش باشد. پردازش پرداخت باید پس از دریافت این تماس آغاز شود.

درخواست: گوگل ابزار پرداخت انتخاب‌شده از طرف مدیریت‌کننده پرداخت، شامل اطلاعات احراز هویت (مثلاً داده‌های توکن‌سازی گوگل پی ) و سیگنال‌های ریسک مربوط به خریدار را برای شما ارسال می‌کند تا بتوانید تشخیص کلاهبرداری را خودتان انجام دهید. محتوای توکن به ارائه‌دهنده خدمات پرداخت شما بستگی دارد.

{
  "payment": {
    "instruments": [
      {
        "billing_address": {
          "first_name": "John",
          "last_name": "Buyer",
          "street_address": "1600 Amphitheatre Pkwy",
          "address_locality": "Mountain View",
          "address_region": "CA",
          "postal_code": "94043",
          "address_country": "US"
        },
        "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": {} // Placeholder for risk signals
}

اگر برای تکمیل پرداخت به اطلاعات اجباری نیاز دارید که در جلسه پرداخت ارائه نشده است، می‌توانید با برگرداندن وضعیت ناقص در پاسخ، از تکمیل پرداخت جلوگیری کرده و آن اطلاعات را درخواست کنید.

اگر گوگل می‌تواند اطلاعات از دست رفته را با استفاده از فیلدهای تعریف شده توسط 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_id مربوط به کنترل‌کننده پرداخت Google Pay است.
  2. استخراج توکن: توکن روش پرداخت تولید شده را از payment_data.credential.token بازیابی کنید.
  3. پردازش پرداخت: برای تکمیل پرداخت از توکن و جزئیات تراکنش استفاده کنید. برای مشاهده مستندات دقیق در مورد مشخصات و نحوه‌ی توکن‌سازی، به مستندات API گوگل پی مراجعه کنید.

پاسخ: اگر پرداخت تکمیل شده باشد و شما پرداخت را پردازش کرده باشید، شیء پرداخت کامل را که نشان می‌دهد سفارش کامل شده است، شامل شناسه سفارش و یک URL پیوند دائمی به سفارش، برمی‌گردانید. 

{
  "ucp": {
      "version": "2026-01-23",
      "capabilities": [...]
  },
  "id": "da2e25ec-eef8-41b7-a439-4e62dea41bdc",
  "status": "completed",

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

  "order": {
    "id": "ORD1773956535.2727807",
    // Example customer-facing order number
    "label": "#100",
    "permalink_url": "https://merchant.example.com/orders/789"
  }
}

لغو جلسه پرداخت

این نقطه پایانی، جلسه پرداخت را لغو می‌کند.

  • نقطه پایانی: POST /checkout-sessions/{id}/cancel

درخواست: گوگل شناسه جلسه پرداخت را ارسال می‌کند.

پاسخ: شما شیء پرداخت کامل را با وضعیت به‌روزرسانی‌شده به canceled برمی‌گردانید.

مدیریت خطا

برای راهنمایی‌های کامل در مورد نحوه قالب‌بندی پیام‌های خطا و تمایز بین خطاهای پروتکل و منطق کسب‌وکار، به نمای کلی کدهای خطا مراجعه کنید.

خطای غیرقابل بازیابی

برای نسخه 2026-01-23 ‎، هنگامی که یک خطای منطقی غیرقابل بازیابی مانع از ایجاد جلسه پرداخت می‌شود (مثلاً همه اقلام موجود نیستند)، یک HTTP 200 OK برگردانید.

در نسخه 2026-01-23 ، شما باید با حذف شناسه جلسه پرداخت و مشخص کردن "severity": "unrecoverable" در آرایه messages ، خرابی ترمینال را مشخص کنید. این به گوگل می‌گوید که درخواست معتبر بوده، اما یک قانون تجاری ایجاد جلسه را مسدود کرده است. 

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/"
}
قبلی
نمایه UCP خود را منتشر کنید
بعدی
چرخه عمر سفارش (پس از خرید)