Integração de comerciantes com o ACP: sessões de checkout, tokens delegados e novas tentativas seguras

O que é

Situação em 25 de outubro de 2026. Este artigo usa a versão datada 2026-04-17 da especificação do ACP e seu registro de alterações. Confira novamente a versão de API acordada, os esquemas dos handlers de pagamento e as notas da versão antes de integrar. Não os substitua silenciosamente por exemplos de uma página antiga do site ou do diretório do repositório destinado a versões ainda não publicadas.

A Agentic Checkout API oferece ao comerciante uma interface programática de checkout: criar uma sessão, atualizá-la ou consultá-la, concluí-la ou cancelá-la. O comerciante retorna o estado oficial do carrinho. Um agente pode solicitar alterações e apresentar o resultado ao comprador, enquanto o backend do comerciante é responsável pelo cálculo do checkout e pelo processamento do pedido.

Por que importa

O acordo sobre o checkout e a delegação de credenciais de pagamento são operações separadas. A Delegate Payment API tokeniza uma credencial para uso restrito pelo provedor de serviços de pagamento do comerciante. Sua resposta contém um identificador de token de cofre. A permissão de uso inclui valor máximo, moeda, identificador da sessão de checkout, identificador do comerciante e validade; a finalidade de uso documentada é one_time.

Esse token não é uma permissão geral para o agente fazer compras. O comerciante e o provedor de pagamentos precisam integrar o handler acordado e aplicar suas restrições. Como prática de implementação defensiva, mantenha a coleta de credenciais e a emissão de tokens em componentes de pagamento dedicados, fora dos prompts do modelo e dos logs comuns de requisições.

Como aplicar

• Exponha as operações de sessão. Implemente a criação em /checkout_sessions, a consulta e as atualizações no recurso da sessão e as operações /complete e /cancel. Retorne os totais atuais, as informações sobre o atendimento do pedido, as mensagens e o status. Preserve a distinção entre ready_for_payment, authentication_required, complete_in_progress e completed.
• Negocie o processamento do pagamento. Use o handler anunciado pelo checkout e envie os dados de pagamento para conclusão usando o handler_id e o esquema de instrumento desse handler. Um token de cofre, por si só, não constitui uma requisição completa de checkout. Confirme que o provedor reconhece o token antes de habilitar essa forma de pagamento.
• Autentique a integração. A documentação de segurança especifica HTTPS e autenticação por token bearer. Forneça o cabeçalho obrigatório API-Version conforme o contrato escolhido; autorize o acesso à sessão dentro da relação autenticada entre comerciante e agente.
• Implemente novas tentativas seguras. Esta versão exige Idempotency-Key nas requisições POST. Reutilize uma chave apenas para a mesma operação e o mesmo corpo. A ausência de chave produz idempotency_key_required; uma duplicata de uma operação em andamento produz idempotency_in_flight; um corpo alterado com a mesma chave produz idempotency_conflict.
• Verifique as notificações de pedidos. A versão define a autenticação de webhooks por Merchant-Signature, calculada sobre o timestamp e o corpo bruto, com verificação da janela de tempo para impedir ataques de repetição. Vincule as atualizações autenticadas ao checkout e ao pedido antes de alterar o estado local de atendimento do pedido.

Armadilhas

Uma resposta HTTP de sucesso não implica que a sessão esteja concluída. Após interrupções, um processo operacional de conciliação deve comparar os estados do checkout, do pagamento e do pedido, em vez de iniciar outra compra imediatamente.

A versão datada torna a idempotência obrigatória, embora a documentação mais antiga a descreva como opcional. Fixe os esquemas e teste essa regra explicitamente. Tokenização, confirmação do comprador, autorização de pagamento e atendimento do pedido precisam, cada um, de evidências próprias; nenhum deles deve ser presumido apenas com base em uma mensagem de sucesso na conversa.