The Native integration requires you to build a RESTful API that Google can call to create and manage checkout sessions.
The overall flow is as follows:
- Build checkout session: The user and optionally an Agent are in a loop adding items to the session.
- Handoff to a Google UI: Once the user decides to checkout the Agent (if engaged) passes the control to a Google UI (passing the checkout session data)
- Manual checkout: The user now interacts only with the Google UI to fill in sensitive fulfillment and payment details and submit the order. The Agent is not involved in this part, ensuring determinism.
- 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.
The following steps describe the API endpoints you will need to implement and their behaviors.
1. Create checkout session
This endpoint allows creation of a checkout session containing the products that a user is interested in buying.
- Endpoint:
POST /checkout-sessions - Trigger: User clicks "Buy" on a product.
Request: Google sends the line items and currency.
{
"line_items": [
{
"item": {
"id": "product_12345", // Must match Product Feed ID
"title": "Running Shoes"
},
"quantity": 1
}
],
"currency": "USD"
}
Response: You return the initialized session with totals, taxes (initially estimated), and payment capabilities. You must include links to your terms of service and privacy policy, which will be linked below the payment button.
{
"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 session
This endpoint allows retrieval of a checkout session.
- Endpoint:
GET /checkout-sessions/{id}
Request: Google sends the ID of the checkout session. If you use Global IDs
(e.g., gid://merchant.example.com/Checkout/session_abc123), note that the ID
in the request path will only be the last component of this ID (e.g.,
session_abc123).
Response: You return the full checkout object.
3. Update checkout session
This endpoint allows updates to a checkout session. When the shipping address is updated, it must recalculate and return taxes and shipping options.
- Endpoint:
PUT /checkout-sessions/{id} - Trigger: User selects or changes their shipping address, updates their shipping selection, or updates their payment information.
Request: Google sends the full checkout object with the updated information.
{
"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.)
}
Response: You recalculate taxes and shipping options as necessary and return the full checkout object.
{
"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)",
"totals": [ {"type": "total", "amount": 500} ]
},
{
"id": "ship_express",
"title": "Express (1-2 days)",
"totals": [ {"type": "total", "amount": 1500} ]
}
]
}
]
}
]
}
}
4. Complete checkout session
This endpoint allows completing a checkout session and placing an order. It should return the completed checkout session and include the order information. Payment processing should begin after this call is received.
- Endpoint:
POST /checkout-sessions/{id}/complete - Trigger: User clicks "Place Order".
Request: Google sends the payment token (encrypted blob) from the provider (e.g., Google Pay), and risk signals about the buyer for you to perform your own fraud detection.
{
"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\"...}"
}
}
}
Response: You return the full checkout object indicating the order is complete, including the order ID and a permalink URL to the order.
{
"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",
"permalink_url": "https://merchant.example.com/orders/789"
}
}
5. Cancel checkout session
This endpoint cancels a checkout session.
- Endpoint:
POST /checkout-sessions/{id}/cancel
Request: Google sends the ID of the checkout session.
Response: You return the full checkout object with the status updated to
canceled.