Referência da API de checkout

Visão geral

Os desenvolvedores de plug-ins são responsáveis por escolher como monetizar a experiência que oferecem. Hoje, a abordagem recomendada e disponível para todos é usar o checkout externo, em que os usuários concluem as compras no domínio do próprio desenvolvedor. Embora a aprovação atualmente se limite a plug-ins para compras de produtos físicos, estamos trabalhando ativamente para oferecer suporte a uma variedade maior de casos de uso de comércio.

Também estamos habilitando o checkout integrado com a tela de pagamento do ChatGPT para parceiros selecionados de marketplaces (beta), com planos de ampliar o acesso a mais marketplaces e varejistas de produtos físicos ao longo do tempo. Até lá, recomendamos direcionar os fluxos de compra para seu checkout externo padrão.

Abordagem recomendada de monetização

✅ Checkout externo (recomendado)

Checkout externo significa direcionar os usuários do ChatGPT para um fluxo de checkout hospedado pelo lojista no seu próprio site ou aplicativo, onde você gerencia preços, pagamentos, envio e processamento dos pedidos de produtos físicos elegíveis.

Essa é a abordagem recomendada para a maioria dos desenvolvedores de plug-ins.

Como funciona

1. Um usuário interage com a interface do seu plug-in no ChatGPT.
2. A interface do seu plug-in apresenta produtos físicos elegíveis (por exemplo, com uma ação “Comprar agora”).
3. Quando o usuário decide comprar, a interface do seu plug-in oferece um link ou o redireciona para fora do ChatGPT, levando-o ao seu fluxo de checkout externo.
4. Pagamento, faturamento, impostos, reembolsos e conformidade são gerenciados inteiramente no seu domínio.
5. Após a compra, o usuário pode voltar ao ChatGPT com a confirmação do pedido ou os detalhes de rastreamento.

Checkout com formas de pagamento salvas

Os desenvolvedores de plug-ins podem criar um fluxo de checkout em uma interface opcional que permita aos clientes usar formas de pagamento já salvas com o lojista. Esse fluxo só pode exibir formas de pagamento salvas e não pode coletar dos clientes credenciais de novas formas de pagamento.

Nessa abordagem, o cliente não precisa ser redirecionado para outra interface fora do ChatGPT para concluir a compra.

Como funciona

1. Um usuário interage com a interface do seu plug-in no ChatGPT.
2. A interface do seu plug-in apresenta produtos físicos elegíveis com os respectivos totais.
3. A interface do seu plug-in exibe as formas de pagamento elegíveis que o cliente já salvou com você.
4. O cliente seleciona uma forma de pagamento salva e confirma a compra no ChatGPT.
5. Seu servidor processa a compra com a forma de pagamento salva e retorna a confirmação ao plug-in.

Checkout com a tela de pagamento do ChatGPT (beta privado)

Para coletar novas formas de pagamento no fluxo de checkout, os desenvolvedores de plug-ins devem usar a tela de pagamento do ChatGPT. Chame requestCheckout com os dados da sessão de checkout (itens, totais e formas de pagamento salvas) para abrir a tela. Quando o usuário seleciona comprar, o ChatGPT envia um token que representa a forma de pagamento selecionada ao seu servidor MCP por meio da chamada da ferramenta complete_checkout. Use sua integração com o PSP para receber o pagamento com esse token e, em seguida, retorne os detalhes do pedido finalizado por meio de complete_checkout.

Visão geral do fluxo

1. O servidor prepara a sessão: uma ferramenta MCP retorna os dados da sessão de checkout (ID da sessão, itens, totais e provedor de pagamento) em structuredContent.
2. O widget exibe uma prévia do carrinho: o widget renderiza os itens e os totais para que o usuário possa confirmar.
3. O widget chama requestCheckout: o widget invoca requestCheckout(session_data). O ChatGPT abre a tela de pagamento, exibe o valor a ser cobrado e apresenta várias formas de pagamento.
4. O servidor finaliza: assim que o usuário clica no botão de pagar, o widget faz uma chamada de volta ao seu MCP por meio da ferramenta complete_checkout. A ferramenta MCP retorna o pedido concluído, que será devolvido ao widget como resposta a requestCheckout.

Sessão de checkout

Você é responsável por construir o payload da sessão de checkout que o host renderizará. Os valores exatos de determinados campos, como id e payment_provider, dependem do seu provedor de serviços de pagamento e do seu sistema de comércio. Na prática, sua ferramenta MCP deve retornar:

• Os itens e as quantidades que o usuário está comprando.
• Totais (subtotal, impostos, descontos, taxas e total) que correspondam aos cálculos do seu servidor.
• Metadados do provedor exigidos pela sua integração com o PSP.
• Links para informações legais e políticas (termos, política de reembolso etc.).

Widget: chame requestCheckout

O host fornece window.openai.requestCheckout. Use essa função para abrir a tela de pagamento do ChatGPT quando o usuário iniciar uma compra:

Exemplo:

async function handleCheckout(sessionJson: string) {
  const session = JSON.parse(sessionJson);

  if (!window.openai?.requestCheckout) {
    throw new Error("requestCheckout is not available in this host");
  }

  // Host opens the ChatGPT payment sheet.
  const order = await window.openai.requestCheckout({
    ...session,
    id: String(checkout_session_id), // Use a unique ID for every checkout session.
  });

  return order; // Host returns the order payload.
}

No seu componente, você pode iniciar esse processo com um clique em um botão:

<Button
  onClick={async () => {
    setIsLoading(true);
    try {
      const orderResponse = await handleCheckout(checkoutSessionJson);
      setOrder(orderResponse);
    } catch (error) {
      console.error(error);
    } finally {
      setIsLoading(false);
    }
  }}
>
  {isLoading ? "Loading..." : "Checkout"}
</Button>

Veja um exemplo completo de sessão de checkout que seu widget pode passar ao host. Seu plug-in fornece os campos da sessão de checkout abaixo. O ChatGPT adiciona campos gerenciados pelo host, como merchant, logo_url, conversation_id, connector_id e ecosystem_app_uri. Preencha o campo merchant_id com o valor especificado pelo seu PSP:

const checkoutRequest = {
  id: "checkout_session_123",
  payment_provider: {
    provider: "stripe",
    merchant_id: "merchant_123",
    supported_payment_methods: [
      {
        type: "card",
        allowed_card_brands: ["visa", "mastercard"],
      },
      { type: "apple_pay" },
      { type: "google_pay" },
    ],
    managed_payment_methods: [
      {
        type: "card",
        id: "pm_123",
        display_name: "Visa ending in 4242",
        display_last4: "4242",
        display_brand: "visa",
      },
    ],
  },
  payment_mode: "live",
  status: "ready_for_payment",
  currency: "USD",
  metadata: {
    cart_id: "cart_123",
    merchant_order_reference: "order_ref_123",
  },
  line_items: [
    {
      id: "line_item_123",
      item: {
        id: "item_123",
        quantity: 1,
      },
      name: "Canvas backpack",
      description: "A weather-resistant everyday backpack.",
      images: ["https://merchant.example.com/images/canvas-backpack.png"],
      base_amount: 3000,
      discount: 0,
      subtotal: 3000,
      tax: 300,
      total: 3300,
    },
  ],
  totals: [
    {
      type: "items_base_amount",
      display_text: "Items subtotal",
      amount: 3000,
    },
    {
      type: "subtotal",
      display_text: "Subtotal",
      amount: 3000,
    },
    {
      type: "fulfillment",
      display_text: "Shipping",
      amount: 550,
    },
    {
      type: "tax",
      display_text: "Tax",
      amount: 300,
    },
    {
      type: "total",
      display_text: "Total",
      amount: 3850,
    },
  ],
  fulfillment_options: [
    {
      id: "standard_shipping",
      type: "shipping",
      title: "Standard shipping",
      subtitle: "Arrives in 3-5 business days",
      carrier: "USPS",
      earliest_delivery_time: "2027-01-15T15:00:00Z",
      latest_delivery_time: "2027-01-19T18:00:00Z",
      subtotal: 500,
      tax: 50,
      total: 550,
    },
  ],
  fulfillment_option_id: "standard_shipping",
  fulfillment_address: {
    name: "Jane Customer",
    line_one: "123 Main St",
    line_two: "Apt 4B",
    city: "San Francisco",
    state: "CA",
    country: "US",
    postal_code: "94107",
    phone_number: "+14155550123",
  },
  messages: [
    {
      type: "info",
      param: "fulfillment_address",
      content_type: "plain",
      content: "Free returns within 30 days.",
    },
  ],
  links: [
    { type: "terms_of_use", url: "https://merchant.example.com/terms" },
    { type: "privacy_policy", url: "https://merchant.example.com/privacy" },
    { type: "support_url", url: "https://merchant.example.com/support" },
  ],
};

const response = await window.openai.requestCheckout(checkoutRequest);

Pontos principais:

• window.openai.requestCheckout(session) abre a interface de checkout do host.
• A promise é resolvida com o resultado do pedido ou rejeitada em caso de erro ou cancelamento.
• Renderize o JSON da sessão para que os usuários possam conferir pelo que estão pagando.
• Use números inteiros na menor unidade da moeda em todos os campos de valor.
• Use payment_provider.managed_payment_methods para as formas de pagamento que o cliente já salvou com seu lojista.
• Mantenha os valores de metadata como strings.
• Use o slug do PSP exigido pela sua integração em provider e consulte seu PSP para obter o valor de merchant_id.

Servidor MCP: exponha a ferramenta complete_checkout

Você pode seguir este padrão e inserir sua própria lógica:

Para retornos diretos de CallToolResult, o SDK MCP para Python usa o tipo de retorno Annotated abaixo para declarar o outputSchema da ferramenta para structuredContent.

from typing import Annotated, Any

from pydantic import BaseModel


class CompleteCheckoutOutput(BaseModel):
    id: str
    status: str
    currency: str
    line_items: list[dict[str, Any]]
    fulfillment_address: dict[str, Any]
    fulfillment_options: list[dict[str, Any]]
    fulfillment_option_id: str
    totals: list[dict[str, Any]]
    order: dict[str, Any]


@tool(description="")
async def complete_checkout(
    self,
    checkout_session_id: str,
    buyer: Buyer,
    payment_data: PaymentData,
) -> Annotated[types.CallToolResult, CompleteCheckoutOutput]:
    return types.CallToolResult(
        content=[],
        structuredContent={
            "id": checkout_session_id,
            "status": "completed",
            "currency": "USD",
            "line_items": [
                {
                    "id": "line_item_1",
                    "item": {
                        "id": "item_1",
                        "quantity": 1,
                    },
                    "base_amount": 3000,
                    "discount": 0,
                    "subtotal": 3000,
                    "tax": 300,
                    "total": 3300,
                },
            ],
            "fulfillment_address": {
                "name": "Jane Customer",
                "line_one": "123 Main St",
                "line_two": "Apt 4B",
                "city": "San Francisco",
                "state": "CA",
                "country": "US",
                "postal_code": "94107",
                "phone_number": "+1 (555) 555-5555",
            },
            "fulfillment_options": [
                {
                    "id": "fulfillment_option_1",
                    "type": "shipping",
                    "title": "Standard shipping",
                    "subtitle": "3-5 business days",
                    "carrier": "USPS",
                    "earliest_delivery_time": "2026-02-24T15:00:00Z",
                    "latest_delivery_time": "2026-02-28T18:00:00Z",
                    "subtotal": 0,
                    "tax": 0,
                    "total": 0,
                },
            ],
            "fulfillment_option_id": "fulfillment_option_1",
            "totals": [
                {
                    "type": "items_base_amount",
                    "display_text": "Items subtotal",
                    "amount": 3000,
                },
                {
                    "type": "subtotal",
                    "display_text": "Subtotal",
                    "amount": 3000,
                },
                {
                    "type": "tax",
                    "display_text": "Tax",
                    "amount": 300,
                },
                {
                    "type": "total",
                    "display_text": "Total",
                    "amount": 3300,
                },
            ],
            "order": {
                "id": "order_id_123",
                "checkout_session_id": checkout_session_id,
                "permalink_url": "",
            },
        },
        _meta={META_SESSION_ID: "checkout-flow"},
        isError=False,
    )

Adapte este exemplo para:

• Integrar com seu provedor de serviços de pagamento para efetuar a cobrança usando a forma de pagamento contida em payment_data.
• Persistir o pedido no seu sistema.
• Retornar dados oficiais do pedido e do recibo.
• Inclua _meta.ui.resourceUri se quiser renderizar um widget de confirmação (o ChatGPT aceita _meta["openai/outputTemplate"] como um alias opcional de compatibilidade).

Os seguintes provedores de serviços de pagamento oferecem suporte ao processamento de pagamentos pela tela de pagamento do ChatGPT:

• Adyen
• Checkout.com
• Fiserv
• PayPal
• Stripe
• Worldpay

Opcional: receber dados brutos de formas de pagamento

Se você é um comerciante com certificação PCI DSS Nível 1, pode receber dados brutos de formas de pagamento diretamente ao implementar o endpoint Delegate Payment do Agentic Commerce Protocol. A solicitação de pagamento delegado incluirá todos os detalhes da forma de pagamento necessários ao seu fluxo de pagamento, incluindo o número do cartão sem tokenização, a data de validade, o CVC, o endereço de cobrança, as restrições de autorização de gastos, os sinais de risco e os metadados.

Por exemplo, uma solicitação com dados brutos de uma forma de pagamento com cartão tem o seguinte formato:

{
  "payment_method": {
    "type": "card",
    "card_number_type": "fpan",
    "number": "4242424242424242",
    "exp_month": "11",
    "exp_year": "2026",
    "name": "Jane Doe",
    "cvc": "223",
    "checks_performed": ["avs", "cvv"],
    "iin": "424242",
    "display_card_funding_type": "credit",
    "display_brand": "visa",
    "display_last4": "4242",
    "metadata": {}
  },
  "allowance": {
    "reason": "one_time",
    "max_amount": 5000,
    "currency": "usd",
    "checkout_session_id": "cs_01HV3P3ABC123",
    "merchant_id": "acme_corp",
    "expires_at": "2026-02-13T12:00:00Z"
  },
  "billing_address": {
    "name": "Jane Doe",
    "line_one": "185 Berry Street",
    "line_two": "Suite 550",
    "city": "San Francisco",
    "state": "CA",
    "country": "US",
    "postal_code": "94107"
  },
  "risk_signals": [
    {
      "type": "card_testing",
      "score": 5,
      "action": "authorized"
    }
  ],
  "metadata": {
    "session_id": "sess_abc123",
    "user_agent": "ChatGPT/2.0"
  }
}

A resposta correspondente deve retornar um ID que represente a forma de pagamento. Esse ID será passado para complete_checkout como parte de payment_data.

{
  "id": "vt_01J8Z3WXYZ9ABC123",
  "created": "2026-02-12T14:30:00Z",
  "metadata": {
    "source": "agent_checkout",
    "merchant_id": "acme_corp",
    "idempotency_key": "idem_xyz789"
  }
}

Tratamento de erros

A chamada da ferramenta complete_checkout pode retornar mensagens do tipo error. Mensagens de erro com code definido como payment_declined ou requires_3ds serão exibidas na tela de pagamento do ChatGPT. Todas as outras mensagens de erro serão enviadas de volta ao widget como resposta a requestCheckout. O widget pode exibir o erro da maneira desejada.

Modo de teste de pagamento

Você pode definir o valor do campo payment_mode como test na chamada a requestCheckout. Isso exibirá uma tela de pagamento do ChatGPT que aceita cartões de teste (como o cartão de teste 4242). O token resultante, contido em payment_data e passado à ferramenta complete_checkout, pode ser processado no ambiente de homologação do seu PSP. Isso permite testar fluxos de ponta a ponta sem movimentar dinheiro real.

Observe que, no modo de teste de pagamento, talvez seja necessário definir um valor diferente para merchant_id. Consulte o guia de monetização do seu provedor de pagamentos para obter mais detalhes.

Lista de verificação da implementação

1. Defina o modelo da sua sessão de checkout: inclua IDs, o objeto do provedor de pagamentos, os itens, os totais e os links para informações legais.
2. Retorne a sessão pela sua ferramenta MCP em structuredContent, junto com o template do seu widget.
3. Renderize a sessão no widget para que os usuários possam conferir os itens, os totais e os termos.
4. Chame requestCheckout(session_data) em resposta a uma ação do usuário; trate o pedido retornado ou o erro.
5. Cobre do usuário implementando a ferramenta MCP complete_checkout, que retorna uma resposta conforme a especificação de checkout.
6. Teste de ponta a ponta com valores, impostos e descontos realistas para garantir que o host renderize os totais esperados.