Для интеграции с нативными сервисами вам потребуется создать RESTful API, который Google сможет вызывать для создания и управления сессиями оформления заказа.
Общий ход событий выглядит следующим образом:
- Создание сессии оформления заказа: пользователь и, при необходимости, агент находятся в цикле, добавляя товары в сессию.
- Передача управления пользовательскому интерфейсу Google: Как только пользователь принимает решение о оформлении заказа, агент (если он задействован) передает управление пользовательскому интерфейсу Google (передавая данные сессии оформления заказа).
- Ручная оплата: Теперь пользователь взаимодействует только с пользовательским интерфейсом Google для заполнения конфиденциальных данных о доставке и оплате, а также для отправки заказа. Агент не участвует в этой части, что обеспечивает детерминированность.
- Completion & return: The Google UI shows a "Thank You" page to confirm the order. Optionally, the user can be redirected back to the Agent, who may have already been notified of the completed purchase.
Следующие шаги описывают необходимые для реализации API-интерфейсы и их поведение.
1. Создать сессию оформления заказа
Этот конечный пункт позволяет создать сессию оформления заказа, содержащую товары, которые пользователь хочет приобрести.
- Конечная точка:
POST /checkout-sessions - Триггер: Пользователь нажимает кнопку «Купить» на товаре.
Запрос: Google отправляет позиции заказа и валюту.
{
"line_items": [
{
"item": {
"id": "product_12345", // Must match Product Feed ID
"title": "Running Shoes"
},
"quantity": 1
}
],
"currency": "USD"
}
Ответ: Вы возвращаете инициализированную сессию с итоговыми суммами, налогами (первоначально рассчитанными) и возможностями оплаты. Вы должны включить ссылки на ваши условия обслуживания и политику конфиденциальности, которые будут размещены ниже кнопки оплаты.
{
"ucp": {
"version": "2026-01-11",
"capabilities": [
{
"name": "dev.ucp.shopping.checkout",
"version": "2026-01-11"
},
{
"name": "dev.ucp.shopping.fulfillment",
"version": "2026-01-11"
}
]
},
"id": "gid://merchant.example.com/Checkout/session_abc123",
"status": "incomplete",
"line_items": [
{
"id": "line_1",
"item": {
"id": "product_12345",
"title": "Running Shoes",
"price": 10000
},
"quantity": 1,
"base_amount": 10000,
"subtotal": 10000,
"total": 10000
}
],
"totals": [
{ "type": "subtotal", "amount": 10000 }, // in cents
{ "type": "tax", "amount": 0 },
{ "type": "total", "amount": 10000 }
],
"payment": {
"handlers": [
{
"id": "gpay",
"name": "com.google.pay",
"config": {
"api_version": 2,
"api_version_minor": 0,
"merchant_info": {
"merchant_id": "12345678901234567890",
"merchant_name": "Example Merchant"
},
"allowed_payment_methods": [
{
"type": "CARD",
"parameters": {
"allowed_auth_methods": ["PAN_ONLY", "CRYPTOGRAM_3DS"],
"allowed_card_networks": ["VISA", "MASTERCARD"]
},
"tokenization_specification": {
"type": "PAYMENT_GATEWAY",
"parameters": {
"gateway": "stripe",
"gateway_merchant_id": "exampleGatewayMerchantId"
}
}
}
]
}
}
]
},
"links": [
{ "type": "privacy_policy", "url": "https://m.com/privacy" },
{ "type": "terms_of_service", "url": "https://m.com/terms" }
]
}
2. Пройти процедуру оформления заказа
Этот конечный пункт позволяет получить информацию о ходе оформления заказа.
- Конечная точка:
GET /checkout-sessions/{id}
Запрос: Google отправляет идентификатор сессии оформления заказа. Если вы используете глобальные идентификаторы (например, gid://merchant.example.com/Checkout/session_abc123 ), обратите внимание, что идентификатор в пути запроса будет только последним компонентом этого идентификатора (например, session_abc123 ).
Ответ: Вы возвращаете полный объект оформления заказа.
3. Обновите сессию оформления заказа.
Этот конечный пункт позволяет обновлять данные в процессе оформления заказа. При обновлении адреса доставки система должна пересчитать и вернуть налоги и варианты доставки.
- Конечная точка:
PUT /checkout-sessions/{id} - Триггер: Пользователь выбирает или изменяет свой адрес доставки, обновляет выбранный способ доставки или обновляет платежную информацию.
Запрос: Google отправляет полный объект оформления заказа с обновленной информацией.
{
"id": "gid://merchant.example.com/Checkout/session_abc123",
"buyer": {
"first_name": "John",
"last_name": "Doe",
"email": "john@example.com"
},
"fulfillment": {
"methods": [
{
"type": "shipping",
"destinations": [
{
"id": "dest_1",
"postal_code": "94043",
"country": "US",
"address_locality": "Mountain View",
"address_region": "CA"
}
],
"selected_destination_id": "dest_1"
}
]
},
"payment": {
"selected_instrument_id": "pi_gpay_5678",
"instruments": [
{
"id": "pi_gpay_5678",
"handler_id": "gpay",
"type": "card",
"brand": "mastercard",
"last_digits": "5678",
"rich_text_description": "Google Pay •••• 5678"
}
]
}
// ... other fields (line_items, currency, etc.)
}
Ответ: Вы пересчитываете налоги и варианты доставки по мере необходимости и возвращаете полный объект оформления заказа.
{
"id": "gid://merchant.example.com/Checkout/session_abc123",
"totals": [
{ "type": "subtotal", "amount": 10000 },
{ "type": "shipping", "display_text": "Ground Shipping", "amount": 500 },
{ "type": "tax", "amount": 850 },
{ "type": "total", "amount": 11350 }
],
// ... other fields (line_items, currency, etc.)
"fulfillment": {
"methods": [
{
"id": "method_shipping",
"type": "shipping",
"line_item_ids": ["line_1"],
"selected_destination_id": "dest_1",
"destinations": [
{
"id": "dest_1",
"postal_code": "94043",
"country": "US",
"address_locality": "Mountain View",
"address_region": "CA"
}
],
"groups": [
{
"id": "group_1",
"line_item_ids": ["line_1"],
"selected_option_id": "ship_ground",
"options": [
{
"id": "ship_ground",
"title": "Ground (3-5 days)",
"total": 500
},
{
"id": "ship_express",
"title": "Express (1-2 days)",
"total": 1500
}
]
}
]
}
]
}
}
4. Завершите процедуру оформления заказа.
Этот конечный пункт позволяет завершить сессию оформления заказа и разместить его. Он должен возвращать завершенную сессию оформления заказа, включая информацию о заказе. Обработка платежа должна начаться после получения этого вызова.
- Конечная точка:
POST /checkout-sessions/{id}/complete - Триггер: Пользователь нажимает кнопку «Оформить заказ».
Запрос: Google отправляет платежный токен (зашифрованный объект) от поставщика услуг (например, Google Pay) и сигналы риска, касающиеся покупателя, чтобы вы могли самостоятельно провести обнаружение мошенничества.
{
"payment_data": {
"id": "pi_gpay_5678",
"handler_id": "gpay",
"type": "card",
"brand": "mastercard",
"last_digits": "5678",
"billing_address": {
"postal_code": "94043",
"address_country": "US"
},
"credential": {
"type": "PAYMENT_GATEWAY",
"token": "{\"signature\":\"...\",\"protocolVersion\":\"ECv2\"...}"
}
}
}
Ответ: Вы возвращаете полный объект оформления заказа, указывающий на его завершение, включая идентификатор заказа и постоянную ссылку на заказ.
{
"ucp": {
"version": "2026-01-11",
"capabilities": [...]
},
"id": "gid://merchant.example.com/Checkout/session_abc123",
"status": "completed",
// ... other fields (line_items, currency, etc.)
"order_id": "gid://merchant.example.com/Order/789",
"order_permalink_url": "https://merchant.example.com/orders/789"
}
5. Отменить сеанс оформления заказа
Этот конечный пункт отменяет сессию оформления заказа.
- Конечная точка:
POST /checkout-sessions/{id}/cancel
Запрос: Google отправляет идентификатор сессии оформления заказа.
Ответ: Вы возвращаете полный объект оформления заказа со статусом, измененным на canceled .