Ir para o conteúdo principal
Português— Escolher um idioma
Menu

Venda de produtos físicos: fluxos de pagamento

Aula 7 de 14 Atualizada a 3 de novembro de 2026 Programador
Nesta página
  1. O que pode vender
  2. Fluxo 1: Pagamento externo, o caminho padrão
  3. Fluxo 2: Métodos de pagamento previamente guardados
  4. Fluxo 3: A folha de checkout do ChatGPT (beta privado)
  5. O servidor é a fonte da verdade
  6. Mantenha ferramentas úteis disponíveis sem interface
  7. Pontos-chave

Lição reescrita em 3 de novembro de 2026 com base na referência da API de Checkout, na página Adicionar interface ao seu servidor MCP e nas diretrizes de Plugins da OpenAI. A versão anterior abordava a venda de subscrições e produtos digitais utilizando funções inventadas (defineProduct, commerceFlow) e uma estrutura de comissões de 30%/15% sem fontes. As regras atuais de plugins restringem o comércio apenas a produtos físicos, e a documentação não menciona comissões. Fontes: Referência da API de Checkout · Diretrizes de Plugins.

O que pode vender

Comece pela regra, pois ela governa todo o resto. As regras de publicação da OpenAI são claras: um plugin só pode realizar comércio de produtos físicos. A venda de produtos digitais ou serviços — subscrições, conteúdo digital, tokens, créditos — é proibida, seja diretamente ou indiretamente (por exemplo, através de um upsell freemium). Aplica-se também uma lista de bens e serviços proibidos (conteúdo para adultos, jogos de azar, medicamentos sujeitos a receita médica, armas, tabaco e nicotina, software pirateado, serviços financeiros enganosos, entre outros). A Lição 13 retoma o que um serviço de subscrição ainda pode fazer dentro destes limites.

Neste enquadramento, a OpenAI documenta três fluxos de pagamento.

Fluxo 1: Pagamento externo, o caminho padrão

O pagamento externo é a abordagem recomendada e está disponível para todos. A interface do plugin apresenta produtos elegíveis, por exemplo com um botão “Comprar”. Quando o utilizador decide efetuar a compra, a interface redireciona-o para um túnel de checkout alojado no seu próprio domínio. A definição de preços, cobrança, impostos, descontos, envio, reembolsos, suporte e conformidade permanecem inteiramente da sua responsabilidade. Após a compra, o utilizador pode regressar ao ChatGPT com a confirmação do pedido ou o rastreio da entrega.

Para abrir esta ligação, o ChatGPT disponibiliza a extensão window.openai.openExternal({ href }), que abre uma ligação controlada no navegador do utilizador. Deve declarar os destinos de redirecionamento permitidos em _meta["openai/widgetCSP"].redirect_domains: a política padrão _meta.ui.csp não cobre este caso. Para um destino aprovado, o ChatGPT adiciona um parâmetro ?redirectUrl=… ao endereço por predefinição; definir redirectUrl: false impede isto.

function openPayment(cartUrl) {
  if (window.openai?.openExternal) {
    window.openai.openExternal({ href: cartUrl });
  } else {
    // O anfitrião não tem esta extensão: permita ao utilizador copiar a ligação
    document.querySelector("#payment-link").textContent = cartUrl;
  }
}

As regras são específicas: enquanto o pagamento integrado não estiver aberto ao seu plugin, o pagamento externo é o caminho obrigatório. Nenhuma outra solução de pagamento de terceiros pode ser integrada ou alojada na interface do plugin.

Fluxo 2: Métodos de pagamento previamente guardados

Para compras elegíveis de produtos físicos, a interface pode oferecer ao cliente um método de pagamento que já tenha guardado consigo. O utilizador seleciona este método e confirma a compra dentro do ChatGPT, sem sair da conversa. O seu servidor MCP processa o pedido e devolve a confirmação vinculativa. Este fluxo pode apresentar métodos de pagamento guardados, mas não pode recolher novos detalhes de pagamento.

Fluxo 3: A folha de checkout do ChatGPT (beta privado)

Para recolher um novo método de pagamento dentro do fluxo, necessita da folha de checkout do ChatGPT. Esta funcionalidade de pagamento integrado está em beta privado, reservada a mercados específicos, e não está acessível a todos os programadores ou utilizadores. O seu funcionamento vale a pena ser compreendido porque ilustra a divisão de papéis entre o anfitrião e o seu servidor:

  1. Uma ferramenta MCP devolve uma sessão de pagamento em structuredContent.
  2. O componente apresenta itens, totais, termos e opções de envio.
  3. Quando o utilizador escolhe pagar, o componente chama window.openai.requestCheckout(session); o ChatGPT abre a sua folha de checkout.
  4. Após validação, o ChatGPT envia um token que representa o método de pagamento escolhido para a ferramenta complete_checkout do seu servidor. Esta ferramenta cobra através do seu fornecedor de pagamentos e devolve o pedido finalizado — o resultado que o componente recebe em resposta a requestCheckout.

A sessão deve conter um identificador único, itens e as suas quantidades, totais em unidades monetárias menores (cêntimos, não euros decimais), fornecedor de pagamento e metadados do comerciante, e ligações obrigatórias: termos, privacidade, reembolsos e suporte. O ChatGPT adiciona os seus próprios campos, como merchant ou conversation_id.

O servidor é a fonte da verdade

Independentemente do fluxo, aplica-se a mesma disciplina:

  • Os preços e o estado do pedido provêm do servidor, nunca de um total calculado no componente.
  • O token de pagamento é verificado, a operação é idempotente — um duplo clique não deve cobrar duas vezes —, o pedido é registado e é devolvido um recibo de referência.
  • O cancelamento, a recusa de pagamento e os erros do fornecedor são tratados no componente. Para a folha de checkout, os erros payment_declined e requires_3ds devolvidos por complete_checkout são apresentados diretamente na folha do ChatGPT.

Para a folha de checkout, payment_mode: "test" permite testar o fluxo de ponta a ponta com cartões de teste sem mover fundos reais.

Mantenha ferramentas úteis disponíveis sem interface

Tal como no resto do plugin, o catálogo e as capacidades de encomenda devem permanecer acessíveis através de ferramentas utilizáveis sem um componente. A interface serve para apresentar produtos, preços, termos e escolhas de pagamento antes da confirmação. Não substitui ferramentas de dados robustas e nunca decide sobre um preço.

Pontos-chave

  • Um plugin vende apenas produtos físicos: subscrições, conteúdo digital, créditos e upsells freemium são proibidos
  • O pagamento externo no seu domínio é o caminho recomendado disponível para todos; openExternal abre a ligação
  • Métodos de pagamento guardados podem ser oferecidos, não recolhidos
  • A folha de checkout do ChatGPT (requestCheckout + complete_checkout) está em beta privado, reservada a mercados específicos
  • O servidor é a fonte da verdade: cálculos de preço no lado do servidor, operações idempotentes, valores em unidades menores