Visão geral da finalização de compra nativa

Para permitir que os usuários façam o checkout, implemente a integração de checkout nativo. Isso envolve a criação de uma API REST padrão que permite ao Google gerenciar de maneira programática o processo de finalização da compra com seus servidores. Esse método oferece a experiência mais integrada para os usuários. Inicialmente, o Google vai renderizar a interface do usuário para o comprador, com planos futuros de oferecer suporte a mais experiências de agente.

Observação: se você é um prestador de serviços terceirizado ou uma plataforma de e-commerce que gerencia o checkout da UCP em nome de comerciantes, consulte o guia Configuração do serviço de checkout da UCP.

Processo de finalização da compra

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:

1. Criar sessão de finalização da compra:o usuário e, opcionalmente, um agente estão em um loop adicionando itens à sessão.
2. Transferência para uma interface do Google:quando o usuário decide conferir o agente (se estiver envolvido), o controle é transferido para uma interface do Google (transmitindo os dados da sessão de finalização da compra).
3. Finalização de compra manual:agora o usuário 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.
4. Conclusão e retorno:a interface do Google mostra uma página de agradecimento para confirmar o pedido. Opcionalmente, o usuário pode ser redirecionado de volta para o agente, que talvez já tenha sido notificado da compra concluída.

Ciclo de vida do status da sessão de finalização da compra

À medida que o usuário avança no fluxo de finalização da compra, você precisa atualizar a sessão status para refletir o estado atual. A sessão passa pelo seguinte ciclo de vida:

• incomplete:o status inicial quando uma sessão é criada. Isso indica que informações obrigatórias (como métodos de envio, tributos ou detalhes do usuário) estão ausentes ou não foram calculadas.
• ready_for_payment:o status a ser usado depois que o usuário atualiza o endereço de entrega e você calcula as opções e os totais de frete, mas antes que o instrumento de pagamento seja finalizado.
• ready_for_complete:o status a ser usado durante a hidratação completa do objeto de finalização da compra, depois que o instrumento de pagamento é selecionado e todos os detalhes do pedido são validados.
• completed:o status final retornado depois que você processa o pagamento e faz o pedido.
• canceled:o status retornado se a sessão de finalização de compra for cancelada.
• error:o status retornado se um erro irrecuperável de lógica de negócios impedir o pagamento. Esse status está disponível na versão 2026-04-08 e mais recentes do UCP.

Fluxo de finalização da compra de vários itens:

Agora, o Google aceita vários itens de linha distintos em uma única sessão de finalização de compra. O fluxo geral é o seguinte:

1. O usuário inicia a finalização da compra em uma interface ativada para UCP (por exemplo, clicando em "Comprar agora" em um produto).
2. A chamada POST /checkout-sessions é feita, incluindo todos os itens distintos na matriz line_items. A matriz line_items vai conter um objeto separado para cada item exclusivo sendo finalizado.
3. O usuário pode atualizar o instrumento de pagamento, os detalhes de atendimento ou aplicar descontos usando chamadas PUT /checkout-sessions/{id}.
4. Quando o usuário clica no botão "Pagar com o GPay", a chamada POST /checkout-sessions/{id}/complete é feita.

Observação: o suporte para ajustes de quantidade nas plataformas do Google será lançado em breve.

Autenticação

Para detalhes sobre como proteger os endpoints da API Native Checkout, incluindo métodos de autenticação aceitos, como chaves de API e OAuth 2.0, consulte o guia Autenticação e segurança.

Ferramentas para desenvolvedores

Para ajudar na implementação da API Native Checkout, confira os seguintes recursos no repositório do Protocolo de Comércio Universal no GitHub:

• Repositório do UCP no GitHub:confira o repositório principal para acessar documentação, especificações e recursos da comunidade abrangentes.
• SDKs:use os kits de desenvolvimento de software para acelerar sua integração. SDKs específicos de linguagem estão disponíveis, incluindo:
  • SDK do Python
  • SDK para JavaScript

• Testes de conformidade:valide os endpoints da API com a especificação do UCP usando o conjunto de testes de conformidade.

  Isso ajuda a garantir que sua implementação atenda aos padrões e comportamentos necessários.

Recomendamos usar essas ferramentas para simplificar seu processo de desenvolvimento e teste.

Objetivos de nível de serviço

Os seguintes objetivos de nível de serviço (SLOs) se aplicam aos endpoints da API REST do Native Checkout. As empresas que fazem integração com o Google precisam atender a essas metas de performance e disponibilidade de API.

Endpoint	Disponibilidade	Latência (50º percentil)	Latência (95º percentil)
POST /checkout-sessions (Criar)	>= 95%	<= 1 segundo	<= 4 segundos
PUT /checkout-sessions/{id} (Atualizar)	>= 95%	<= 1 segundo	<= 5 segundos
POST /checkout-sessions/{id}/complete (concluído)	>= 95%	<= 6 segundos	<= 10 segundos

A latência do 50º percentil indica que pelo menos 50% das solicitações devem ser concluídas dentro desse período. A latência do 95º percentil indica que pelo menos 95% das solicitações devem ser concluídas dentro desse período.

Próximas etapas

Confira os payloads da API Checkout e os detalhes técnicos de implementação da sua versão da UCP:

• API REST de checkout nativo da versão 2026-04-08
• API REST de checkout nativo da versão 2026-01-23

Se você estiver fazendo a integração como um provedor de serviços terceirizado, acesse Configuração do serviço de finalização de compra da UCP para hospedar perfis de comerciantes e configurar handshakes de relacionamento de contas.