Referencia de la API de pago

Descripción general

Los desarrolladores de complementos son responsables de elegir cómo monetizar su experiencia. Actualmente, la opción recomendada y disponible de forma general es usar un proceso de pago externo, en el que los usuarios completan sus compras en el dominio del desarrollador. Aunque por ahora solo se aprueban complementos para la compra de productos físicos, estamos trabajando activamente para admitir una mayor variedad de casos de uso comerciales.

También estamos habilitando el proceso de pago integrado con el formulario de pago de ChatGPT para determinados socios de marketplaces (beta), con planes de ampliar el acceso a más marketplaces y comercios minoristas de productos físicos con el tiempo. Hasta entonces, recomendamos dirigir los flujos de compra a tu proceso de pago externo habitual.

Enfoque de monetización recomendado

✅ Proceso de pago externo (recomendado)

El proceso de pago externo consiste en dirigir a los usuarios desde ChatGPT a un flujo de pago alojado por el comercio en tu propio sitio web o aplicación, donde gestionas los precios, los pagos, los envíos y el procesamiento de pedidos de productos físicos elegibles.

Este es el enfoque recomendado para la mayoría de los desarrolladores de complementos.

Cómo funciona

1. Un usuario interactúa con la interfaz de tu complemento en ChatGPT.
2. La interfaz de tu complemento presenta productos físicos elegibles (por ejemplo, con una acción “Comprar ahora”).
3. Cuando el usuario decide comprar, la interfaz de tu complemento lo lleva, mediante un enlace o una redirección, fuera de ChatGPT y hacia tu flujo de pago externo.
4. El pago, la facturación, los impuestos, los reembolsos y el cumplimiento normativo se gestionan íntegramente en tu dominio.
5. Después de la compra, el usuario puede volver a ChatGPT con la confirmación del pedido o los detalles de seguimiento.

Proceso de pago con métodos de pago guardados

Los desarrolladores de complementos pueden crear un flujo de pago en una interfaz opcional que permita a los clientes usar métodos de pago que ya tengan guardados en el comercio. Este flujo solo puede mostrar métodos de pago guardados y no puede recopilar credenciales de nuevos métodos de pago de los clientes.

Con este enfoque, no es necesario redirigir al cliente a otra interfaz fuera de ChatGPT para completar la compra.

Cómo funciona

1. Un usuario interactúa con la interfaz de tu complemento en ChatGPT.
2. La interfaz de tu complemento presenta productos físicos elegibles con los totales correspondientes.
3. La interfaz de tu complemento muestra los métodos de pago elegibles que el cliente ya tiene guardados contigo.
4. El cliente selecciona un método de pago guardado y confirma la compra en ChatGPT.
5. Tu servidor procesa la compra con el método de pago guardado y devuelve la confirmación al complemento.

Proceso de pago con el formulario de pago de ChatGPT (beta privada)

Para recopilar nuevos métodos de pago dentro del flujo de pago, los desarrolladores de complementos deben usar el formulario de pago de ChatGPT. Llama a requestCheckout con los datos de la sesión de pago (artículos, totales y métodos de pago guardados) para abrir el formulario. Cuando el usuario selecciona comprar, ChatGPT envía un token que representa el método de pago seleccionado a tu servidor MCP mediante la llamada a la herramienta complete_checkout. Usa tu integración con el PSP para cobrar con este token y luego devuelve los detalles definitivos del pedido desde complete_checkout.

Resumen del flujo

1. El servidor prepara la sesión: una herramienta MCP devuelve los datos de la sesión de pago (ID de sesión, artículos, totales y proveedor de pagos) en structuredContent.
2. El widget muestra una vista previa del carrito: el widget muestra los artículos y los totales para que el usuario pueda confirmarlos.
3. El widget llama a requestCheckout: el widget invoca requestCheckout(session_data). ChatGPT abre el formulario de pago y muestra el importe que se cobrará y varios métodos de pago.
4. El servidor finaliza el proceso: cuando el usuario hace clic en el botón de pago, el widget vuelve a llamar a tu MCP mediante la llamada a la herramienta complete_checkout. La herramienta MCP devuelve el pedido completado, que se devuelve al widget como respuesta a requestCheckout.

Sesión de pago

Eres responsable de crear la carga útil de la sesión de pago que mostrará el host. Los valores exactos de ciertos campos, como id y payment_provider, dependen de tu proveedor de servicios de pago y de tu sistema de comercio. En la práctica, tu herramienta MCP debe devolver:

• Los artículos y las cantidades que el usuario está comprando.
• Los totales (subtotal, impuestos, descuentos, cargos y total) que coincidan con los cálculos de tu servidor.
• Los metadatos del proveedor que requiere tu integración con el PSP.
• Los enlaces a información legal y políticas (términos, política de reembolsos, etc.).

Widget: llama a requestCheckout

El host proporciona window.openai.requestCheckout. Úsalo para abrir el formulario de pago de ChatGPT cuando el usuario inicie una compra:

Ejemplo:

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.
}

En tu componente, podrías iniciar este proceso al hacer clic en un botón:

<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>

Aquí tienes un ejemplo completo de una sesión de pago que tu widget puede pasar al host. Tu complemento proporciona los campos de la sesión de pago que se muestran a continuación. ChatGPT agrega campos que gestiona el host, como merchant, logo_url, conversation_id, connector_id y ecosystem_app_uri. Completa el campo merchant_id con el valor especificado por tu 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);

Puntos clave:

• window.openai.requestCheckout(session) abre la interfaz de pago del host.
• La promesa se resuelve con el resultado del pedido o se rechaza si se produce un error o una cancelación.
• Renderiza el JSON de la sesión para que los usuarios puedan revisar lo que están pagando.
• Usa números enteros expresados en unidades monetarias menores para todos los campos de importe.
• Usa payment_provider.managed_payment_methods para los métodos de pago que el cliente ya tiene guardados en tu comercio.
• Mantén los valores de metadata como cadenas de texto.
• Usa el slug del PSP que requiere tu integración para provider y consulta a tu PSP para obtener su valor de merchant_id.

Servidor MCP: expón la herramienta complete_checkout

Puedes seguir este patrón y sustituir la lógica por la tuya:

Para devolver CallToolResult directamente, el SDK de MCP para Python usa el tipo de retorno Annotated que se muestra a continuación para declarar el outputSchema de la herramienta 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,
    )

Adapta este ejemplo para lo siguiente:

• Integra tu proveedor de servicios de pago para cobrar con el método de pago incluido en payment_data.
• Guarda el pedido de forma persistente en tu sistema.
• Devuelve los datos definitivos del pedido o recibo.
• Incluye _meta.ui.resourceUri si quieres mostrar un widget de confirmación (ChatGPT admite _meta["openai/outputTemplate"] como alias opcional de compatibilidad).

Los siguientes proveedores de servicios de pago admiten el procesamiento de pagos mediante el formulario de pago de ChatGPT:

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

Opcional: recibir métodos de pago sin procesar

Si eres un comerciante con una certificación PCI DSS de nivel 1, puedes recibir métodos de pago sin procesar directamente al implementar el punto de acceso Delegate Payment de Agentic Commerce Protocol. La solicitud de pago delegado incluirá todos los datos del método de pago que requiera tu flujo de pago, incluidos el número de tarjeta sin procesar, la fecha de vencimiento, el CVC, la dirección de facturación, las restricciones de gasto, las señales de riesgo y los metadatos.

Por ejemplo, una solicitud de método de pago con datos de tarjeta sin procesar es la siguiente:

{
  "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"
  }
}

La respuesta correspondiente debe devolver un identificador que represente el método de pago. Este identificador se pasará a 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"
  }
}

Manejo de errores

La llamada a la herramienta complete_checkout puede devolver mensajes de tipo error. Los mensajes de error con code establecido en payment_declined o requires_3ds se mostrarán en el formulario de pago de ChatGPT. Todos los demás mensajes de error se devolverán al widget como respuesta a requestCheckout. El widget puede mostrar el error de la manera que prefieras.

Modo de pago de prueba

Puedes establecer el valor del campo payment_mode en test en la llamada a requestCheckout. Esto mostrará un formulario de pago de ChatGPT que acepta tarjetas de prueba (como la tarjeta de prueba 4242). El token resultante, incluido en payment_data y enviado a la herramienta complete_checkout, se puede procesar en el entorno de preproducción de tu PSP. Esto te permite probar flujos de principio a fin sin mover fondos reales.

Ten en cuenta que, en el modo de pago de prueba, es posible que debas establecer un valor diferente para merchant_id. Consulta la guía de monetización de tu proveedor de pagos para obtener más detalles.

Lista de verificación de la implementación

1. Define el modelo de tu sesión de pago: incluye los identificadores, el objeto del proveedor de pagos, las partidas, los totales y los enlaces legales.
2. Devuelve la sesión desde tu herramienta MCP en structuredContent junto con la plantilla de tu widget.
3. Muestra la sesión en el widget para que los usuarios puedan revisar los artículos, los totales y los términos.
4. Llama a requestCheckout(session_data) cuando el usuario realice una acción; maneja el pedido o el error devuelto.
5. Cobra al usuario implementando la herramienta MCP complete_checkout, que devuelve una respuesta conforme a la especificación del proceso de pago.
6. Realiza pruebas de principio a fin con importes, impuestos y descuentos realistas para asegurarte de que el host muestre los totales esperados.