Implementação da troca HTTP do x402 v2: cabeçalhos, facilitadores e liquidação

O que é

Situação em 25 de outubro de 2026. Este artigo descreve a versão 2 do protocolo x402 e seu mapeamento para HTTP. Confira novamente ambas as especificações e o esquema escolhido antes de implantar; a versão do protocolo, por si só, não fixa todos os detalhes da implementação. A RFC 9110 reserva o HTTP 402 para uso futuro: o código de status, por si só, não oferece um procedimento de pagamento interoperável.

O x402 acrescenta esse procedimento. Um cliente solicita um recurso, o servidor de recursos informa os requisitos de pagamento e um facilitador pode realizar a verificação e a liquidação por meio de /verify e /settle. O próprio servidor pode executar essas funções. O suporte do facilitador precisa ser compatível com o esquema e a rede escolhidos.

Por que importa

O mapeamento para HTTP transporta JSON codificado em base64 em três cabeçalhos: PAYMENT-REQUIRED para o desafio enviado pelo servidor, PAYMENT-SIGNATURE para os dados de pagamento enviados pelo cliente e PAYMENT-RESPONSE para os resultados da liquidação. O cabeçalho do desafio é o local canônico dessas informações; o cliente não deve depender da conveniência de recebê-las em um corpo de resposta JSON.

A especificação principal separa a verificação da autorização da movimentação de fundos. No fluxo padrão, authorization, a verificação precede a execução do recurso e a liquidação ocorre depois. Outros fluxos definidos, como upfront e escrow, comprometem os fundos antes da execução. Portanto, uma verificação bem-sucedida não é evidência suficiente de que houve liquidação.

Como aplicar

• Implemente o cliente com critérios explícitos. Interprete PaymentRequired, selecione uma opção compatível de accepts e verifique se o valor, o ativo, a rede e o destinatário atendem à política de gastos antes de assinar. Envie os dados resultantes por PAYMENT-SIGNATURE. Rejeite fluxos de pagamento desconhecidos em vez de presumir seus efeitos.
• Implemente as verificações do servidor. Informe os requisitos e valide a autorização recebida em relação a eles. Siga a ordem de verificação e liquidação do fluxo selecionado. Retorne o resultado da liquidação em PAYMENT-RESPONSE; guarde o identificador da transação e a rede para conciliação.
• Verifique a infraestrutura para navegadores. Para clientes de outras origens, exponha PAYMENT-REQUIRED e PAYMENT-RESPONSE por meio de CORS e permita PAYMENT-SIGNATURE na requisição preflight. Um teste pela linha de comando não verifica essas restrições do navegador.
• Trate a incerteza. O resultado documentado settlement_pending significa que uma transação transmitida à rede ainda pode ser confirmada. Concilie seu identificador de transação antes de decidir se cabe outro pagamento.
• Use uma lista de verificação para a revisão. Como prática de integração, registre qual componente é responsável pela definição do preço, pela assinatura, pela verificação, pela liquidação e pela entrega. Teste pagamentos negados, facilitadores indisponíveis e respostas perdidas em um ambiente fora de produção antes de conceder a um agente autorização para gastar.

Armadilhas

Tratar qualquer resposta 402 como permissão para gastar confunde uma solicitação do vendedor com a autorização do usuário. Mantenha essa autorização separadamente. A especificação principal exclui explicitamente a gestão de orçamento do cliente.

Para a revisão operacional, mantenha registros separados do resultado do pagamento e da entrega do recurso. Investigue uma solicitação paga cujo recurso não foi entregue antes de emitir outra autorização. Essas recomendações de registro são práticas de implementação; não afirmam que o HTTP oferece reembolsos automáticos ou execução da aplicação exatamente uma vez.