Эта страница переведена с помощью Cloud Translation API.

Реализация нативного REST API для оформления заказа, Реализация нативного REST API для оформления заказа

В этом руководстве представлены техническая справочная информация по API и схемы полезной нагрузки для версии 2026-01-23 нативного протокола проверки Universal Commerce Protocol (UCP).

Прежде чем создавать конечные точки, убедитесь, что вы ознакомились с обзором процесса оформления заказа в нативном режиме , где изложены основные этапы оформления заказа, требования к аутентификации и инструменты разработчика.

Создать сессию оформления заказа

Этот конечный пункт позволяет создать сессию оформления заказа, содержащую товары, которые пользователь хочет приобрести.

Конечная точка: 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
    }
  ],
  "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 должно включать все применимые налоги.
Опускайте отдельные записи о налогах: не включайте в массив totals отдельный объект с type: "tax" .
Укажите пользовательский текст для отображения: необходимо включить атрибут 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
  }
]

Пройти процедуру оформления заказа

Этот конечный пункт позволяет получить информацию о ходе оформления заказа.

Конечная точка: GET /checkout-sessions/{id}

Запрос: Google отправляет идентификатор сессии оформления заказа. Если вы используете глобальные идентификаторы (например, gid://merchant.example.com/Checkout/session_abc123 ), обратите внимание, что идентификатор в пути запроса будет только последним компонентом этого идентификатора (например, session_abc123 ).

Ответ: Вы возвращаете полный объект оформления заказа. Для сессии с несколькими товарами, созданной в версии 2026-01-23 или более поздней, массив line_items будет содержать несколько записей о товарах.

Обновить сессию оформления заказа

Этот конечный пункт позволяет обновлять данные в процессе оформления заказа. При обновлении адреса доставки система должна пересчитать и вернуть налоги и варианты доставки.

Конечная точка: 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": [
      {
        "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
}

Полное увлажнение объекта оформления заказа

Запрос: 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
    }
  ],
  "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"
    }
  ]
}

Завершить процедуру оформления заказа

Этот конечный пункт позволяет завершить сессию оформления заказа и разместить его. Он должен возвращать завершенную сессию оформления заказа, включая информацию о заказе. Обработка платежа должна начаться после получения этого вызова.

Конечная точка: POST /checkout-sessions/{id}/complete
Триггер: Пользователь нажимает кнопку «Оплатить через GPay», и Google получает успешный ответ от полностью обновленной системы оформления заказа .

Запрос: Google отправляет выбранный платежный инструмент от обработчика платежей, включая учетные данные (например, данные токенизации Google Pay ) и сигналы риска, касающиеся покупателя, чтобы вы могли самостоятельно провести обнаружение мошенничества. Содержимое токена будет зависеть от вашего поставщика платежных услуг.

{
  "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
}

Если для завершения оформления заказа требуется обязательная информация, которая не была предоставлена в процессе оформления, вы можете предотвратить завершение оформления и запросить эту информацию, вернув в ответе статус "незавершено".

Если 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 вы должны:

Проверка обработчика: Убедитесь, что handler_id соответствует обработчику платежей Google Pay.
Извлечение токена: Получите сгенерированный токен способа оплаты из payment_data.credential.token .
Обработка платежа: используйте токен и данные транзакции для завершения платежа. Подробную информацию о спецификации и обработке токенизации см. в документации API Google Pay .

Ответ: Если оформление заказа завершено и оплата обработана, возвращается полный объект оформления заказа, указывающий на его завершение, включая идентификатор заказа и постоянную ссылку на заказ.

{
  "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

Запрос: Google отправляет идентификатор сессии оформления заказа.

Ответ: Вы возвращаете полный объект оформления заказа со статусом, измененным на canceled .

Обработка ошибок

Полные рекомендации по форматированию сообщений об ошибках и разграничению ошибок протокола и ошибок бизнес-логики см. в обзоре кодов ошибок .

Неустранимая ошибка

В версии 2026-01-23 , если неустранимая ошибка бизнес-логики препятствует созданию сессии оформления заказа (например, все товары отсутствуют на складе), возвращается HTTP-код 200 OK .

В версии 2026-01-23 необходимо указать на конечный сбой, опустив идентификатор сессии оформления заказа и указав в массиве messages "severity": "unrecoverable" . Это сообщает 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/"
}