A integração nativa exige que você crie uma API RESTful que o Google possa chamar para criar e gerenciar sessões de finalização de compra.
O fluxo geral é o seguinte:
- Criar sessão de finalização da compra:o usuário e, opcionalmente, um agente estão em um loop adicionando itens à sessão.
- Transferência para uma interface do Google:quando o usuário decide finalizar a compra, o agente (se estiver envolvido) transfere o controle para uma interface do Google (transmitindo os dados da sessão de finalização da compra).
- Finalização de compra manual:o usuário agora interage apenas com a interface do Google para preencher detalhes sensíveis de atendimento e pagamento e enviar o pedido. O agente não está envolvido nessa parte, garantindo o determinismo.
- Conclusão e devolução:a interface do Google mostra uma página de agradecimento para confirmar o pedido. Opcionalmente, o usuário pode ser redirecionado de volta ao agente, que já pode ter sido notificado da compra concluída.
As etapas a seguir descrevem os endpoints da API que você precisa implementar e os comportamentos deles.
1. Criar sessão de finalização de compra
Esse endpoint permite a criação de uma sessão de finalização da compra com os produtos que um usuário tem interesse em comprar.
- Endpoint:
POST /checkout-sessions - Gatilho:o usuário clica em "Comprar" em um produto.
Solicitação:o Google envia os itens de linha e a moeda.
{
"line_items": [
{
"item": {
"id": "product_12345", // Must match Product Feed ID
"title": "Running Shoes"
},
"quantity": 1
}
],
"currency": "USD"
}
Resposta:você retorna a sessão inicializada com totais, tributos (inicialmente estimados) e recursos de pagamento. Você precisa incluir links para seus Termos de Serviço e Política de Privacidade, que serão vinculados abaixo do botão de pagamento.
{
"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. Receber sessão de finalização da compra
Esse endpoint permite a recuperação de uma sessão de finalização da compra.
- Endpoint:
GET /checkout-sessions/{id}
Solicitação:o Google envia o ID da sessão de finalização da compra. Se você usa IDs globais (por exemplo, gid://merchant.example.com/Checkout/session_abc123), observe que o ID no caminho da solicitação será apenas o último componente desse ID (por exemplo,
session_abc123).
Resposta:você retorna o objeto de finalização de compra completo.
3. Atualizar sessão de finalização de compra
Esse endpoint permite atualizações em uma sessão de finalização de compra. Quando o endereço de entrega é atualizado, ele precisa recalcular e retornar os impostos e as opções de envio.
- Endpoint:
PUT /checkout-sessions/{id} - Acionador:o usuário seleciona ou muda o endereço de entrega, atualiza a seleção de envio ou as informações de pagamento.
Solicitação:o Google envia o objeto de finalização de compra completo com as informações atualizadas.
{
"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.)
}
Resposta:recalcule os tributos e as opções de frete conforme necessário e retorne o objeto de finalização de compra completo.
{
"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. Concluir sessão de finalização de compra
Esse endpoint permite concluir uma sessão de finalização da compra e fazer um pedido. Ele precisa retornar a sessão de finalização de compra concluída e incluir as informações do pedido. O processamento do pagamento deve começar depois que essa chamada for recebida.
- Endpoint:
POST /checkout-sessions/{id}/complete - Gatilho:o usuário clica em "Fazer pedido".
Solicitação:o Google envia o token de pagamento (blob criptografado) do provedor (por exemplo, Google Pay) e indicadores de risco sobre o comprador para que você faça sua própria detecção de fraude.
{
"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\"...}"
}
}
}
Resposta:você retorna o objeto de finalização de compra completo indicando que o pedido está concluído, incluindo o ID do pedido e um URL de link permanente para ele.
{
"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. Cancelar sessão de finalização da compra
Esse endpoint cancela uma sessão de finalização de compra.
- Endpoint:
POST /checkout-sessions/{id}/cancel
Solicitação:o Google envia o ID da sessão de finalização da compra.
Resposta:você retorna o objeto de finalização de compra completo com o status atualizado para
canceled.