Finalização de compra integrada

Com a integração da finalização de compra incorporada, é possível incorporar a finalização de compra baseada na Web em plataformas do Google. Use esse caminho se o produto exigir uma lógica complexa (por exemplo, personalizações) que a API nativa não pode oferecer suporte. Você vai implementar uma interface de usuário de finalização de compra que será incorporada ao fluxo de finalização de compra por um iframe.

O que é a finalização de compra integrada?

O pagamento incorporado (EC, na sigla em inglês) permite que um host (como a Pesquisa Google ou um agente de IA) mostre seu pagamento atual baseado na Web no aplicativo dele (usando um iframe ou uma visualização da Web). Ao contrário de um redirecionamento da Web padrão, isso permite a comunicação bidirecional. O host pode "delegar" tarefas específicas, como selecionar um endereço salvo ou pagar com uma credencial armazenada para oferecer uma experiência mais rápida e nativa, enquanto você continua sendo o comerciante registrado e cuida da criação do pedido.

Lista de verificação da implementação para comerciantes

Para oferecer suporte à finalização da compra incorporada, implemente os seguintes requisitos na API UCP e no aplicativo de finalização da compra de front-end.

1. Ativar a descoberta (API UCP)

Você precisa declarar que seu pagamento é compatível com a extensão incorporada nas respostas da API UCP.

  • Ação: adicione o objeto de capacidade dev.ucp.shopping.embedded_checkout à matriz de recursos de resposta da UCP.
  • Requisito: inclua os URLs de especificação e esquema.
  • Opcional: se você precisar de autenticação (por exemplo, um token JWT) para carregar o fluxo de pagamento, defina auth.required como "true".
"capabilities": [
  {
    "name": "dev.ucp.shopping.embedded_checkout",
    "version": "2026-01-11",
    "spec": "https://ucp.dev/specs/shopping/embedded_checkout",
    "config": {
        "auth": { "required": true }
    }
  }
]

2. Processar a inicialização do URL (front-end)

Quando o host carregar seu continue_url, ele vai adicionar parâmetros de consulta específicos. Seu front-end precisa analisar esses dados imediatamente após o carregamento.

  • Ação: analise os seguintes parâmetros de consulta do URL:
    • ec_version: a versão do protocolo (por exemplo, 2026-01-11).
    • ec_auth: (se aplicável) valide o token de autenticação fornecido pelo host, se você definir auth.required: true.
    • ec_delegate: uma lista separada por vírgulas de ações que o host quer processar de forma nativa (por exemplo, payment.credential, fulfillment.address_change, payment.instruments_change).

3. Estabelecer comunicação (front-end)

A comunicação ocorre usando postMessage no formato JSON-RPC 2.0.

  • Ação: implemente um listener para eventos message.
  • Requisito: valide a origem de todas as mensagens para garantir que ela corresponda ao host.
  • Suporte nativo: para hosts de apps nativos, verifique e use globais injetados (por exemplo, window.EmbeddedCheckoutProtocolConsumer) se postMessage não estiver disponível.

4. Realizar o handshake (front-end)

Assim que o pagamento for renderizado, informe ao host que você está pronto e confirme quais delegações aceita.

  • Ação: envie a solicitação ec.ready imediatamente após o carregamento.
  • Payload: inclua uma matriz delegate listando os recursos que você concorda em deixar o host processar.
  • Exemplo: se o URL solicitado for ec_delegate=payment.credential e você aceitar, inclua "payment.credential" no payload ec.ready.
// Example: Sending the ec.ready message
const hostWindow = window.parent;
hostWindow.postMessage(JSON.stringify({
  "jsonrpc": "2.0",
  "id": "ready_1",
  "method": "ec.ready",
  "params": {
    "delegate": ["payment.credential"] // List capabilities you accept to delegate
  }
}), "*");

5. Implementar a lógica de delegação (front-end)

Se você aceitou uma delegação no handshake, modifique o comportamento da interface do usuário para evitar conflitos.

  • Ação: oculte os elementos relevantes da interface para tarefas delegadas.
  • Exemplo: se fulfillment.address_change for delegado, oculte o formulário de endereço e mostre um botão "Mudar endereço".
  • Ação: quando o usuário clicar nesse botão, envie uma mensagem _request (por exemplo, ec.fulfillment.address_change_request) ao organizador.
  • Ação: aguarde a resposta do organizador. A resposta vai conter os novos dados (por exemplo, o endereço selecionado).
  • Requisito: atualize o estado de finalização da compra usando uma substituição no estilo PUT (substitua toda a seção de objetos) com base nos dados retornados pelo host.
// Example: requesting payment credential
hostWindow.postMessage(JSON.stringify({
  "jsonrpc": "2.0",
  "id": "req_1",
  "method": "ec.payment.credential_request",
  "params": {
      "checkout": currentCheckoutState // Pass the full current checkout object
  }
}), "*");

6. Enviar atualizações de ciclo de vida e estado (front-end)

Você precisa manter o host informado sobre o status do pagamento para que ele possa atualizar a interface ou lidar com erros.

  • Ação: enviar notificações (mensagens sem um ID) quando o estado mudar:
    • ec.start: quando o pagamento está totalmente visível.
    • ec.line_items.change: se o conteúdo ou os totais do carrinho forem atualizados.
    • ec.buyer.change: se os detalhes do comprador forem atualizados.
    • ec.complete: quando o pedido é feito.
    • ec.error: se ocorrer um erro crítico.

7. Aplicar segurança (servidor/cabeçalhos)

Você precisa garantir que seu processo de finalização de compra não possa ser incorporado por pessoas mal-intencionadas.

  • Ação: implemente cabeçalhos de Política de Segurança de Conteúdo (CSP).
  • Requisito: defina frame-ancestors <host_origin>; para permitir a incorporação apenas por hosts confiáveis.
  • Navegação: bloqueie a lógica que tira o usuário do fluxo de finalização da compra (por exemplo, remova os links "Continuar comprando" que levam à sua página inicial). Exceções são permitidas para verificação 3DS ou redirecionamentos de pagamento de terceiros.