Agentic Commerce Protocol integration

Use this guide to build a custom ChatGPT app that accepts payments using the Agentic Commerce Protocol (ACP) and the ChatGPT Apps SDK. This guide walks you through configuring Braintree as your payment provider, processing delegated payment tokens, and testing your integration.

Prerequisites

Build your app using the ChatGPT Apps SDK.
Implement an MCP server with the complete_checkout tool to receive tokens.
Call requestCheckout() from the app to trigger Instant Checkout.
Follow the ACP agentic checkout specification to manage checkout sessions.
Specify braintree as your payment provider.
Process payment tokens using your existing Braintree integration.

Tips for building a ChatGPT app

This guide does not tell you how to build a ChatGPT app. The following tips and resources, however, could help.

Step 1: Specify Braintree as your payment provider

When your ChatGPT app widget calls requestCheckout(), you must construct a checkout session that specifies Braintree as the payment provider according to the ACP Agentic Checkout Specification.

const checkoutRequest = {
  id: checkoutSessionId,
  payment_provider: {
    provider: "braintree",
    merchant_id: "your_braintree_merchant_id",
    supported_payment_methods: ["card", "applepay", "googlepay"],
  },
  status: "ready_for_payment",
  currency: "USD",
  totals: [
    {
      type: "total",
      display_text: "Total",
      amount: 330, // Amount in cents
    },
  ],
  links: [
    { type: "terms_of_use", url: "https://yoursite.com/terms" },
    { type: "privacy_policy", url: "https://yoursite.com/privacy" },
  ],
  payment_mode: "live", // Use "test" for testing with test cards
};

// Open Instant Checkout UI in ChatGPT
const order = await window.openai.requestCheckout(checkoutRequest);

Parameter	Description
`id`	Unique checkout session identifier
`payment_provider.provider`	Identify Braintree as the payment provider (`braintree`).
`payment_provider.merchant_id`	Your Braintree public merchant ID
`payment_provider.supported_payment_methods`	An array of payment methods that your Braintree integration supports. Current supported values are: `card` `applepay` `googlepay`
`status`	Set to `ready_for_payment` to indicate that the checkout session is ready to accept payment.
`currency`	The ISO 4217 currency code for the transaction (for example, `USD`).
`totals`	An array of line items for the transaction, showing the amounts in cents.
`payment_mode`	Set to `live` for production environments or `test` for testing.

For more information, see the Apps SDK Monetization Guide.

Step 2: Complete checkout and process payments

To complete checkout, your MCP server must expose a complete_checkout tool that receives the token and processes it.

Note: Use the payment method nonce exactly as you would use any payment method nonce in Braintree’s transaction.sale method or chargePaymentMethod GraphQL mutation.

The following example uses Python.

@tool(description="Complete checkout and process payment")
async def complete_checkout(
    self,
    checkout_session_id: str,
    buyer: Buyer,
    payment_data: PaymentData,
) -> types.CallToolResult:
    
    # Extract the delegated payment token
    token = payment_data.token
    
    # Process payment using Braintree SDK
    result = gateway.transaction.sale({
        "amount": "10.00",
        "payment_method_nonce": token,
        "options": {
            "submit_for_settlement": True
        }
    })
    
    if result.is_success:
        return types.CallToolResult(
            content=[],
            structuredContent={
                "id": checkout_session_id,
                "status": "completed",
                "currency": "USD",
                "order": {
                    "id": result.transaction.id,
                    "checkout_session_id": checkout_session_id,
                    "permalink_url": f"https://yoursite.com/orders/{result.transaction.id}",
                },
            },
            isError=False,
        )
    else:
        # Return error response
        return types.CallToolResult(
            content=[{
                "type": "text",
                "text": f"Payment failed: {result.message}"
            }],
            isError=True,
        )

Note: The payment token in payment_data.token (for example, "tokencc_bf_abc123_456def_ghijkl_mno789_pqr") is a one-time-use token that you can process using your existing Braintree integration to complete the payment. In Braintree, this type of token is called a payment method nonce. It serves as a secure, single-use reference to the buyer’s payment information. It’s bound to your merchant ID and includes amount and time restrictions that you can configure.

Test your integration

To test Instant Checkout in a ChatGPT App, extend your MCP server to render a widget in the ChatGPT application by completing these steps.

1. Register a resource in your MCP server

This step depends on your implementation. For example, if you want your application to display a Buy Now product card when someone prompts ChatGPT with something like “I want to buy wireless headphones,” you would build a front-end application that reads ChatGPT’s input and renders the Buy Now product card. Then, you register that HTML as a resource for the complete_checkout tool in your MCP server, as shown in the following example.

const widgetHTML = loadWidgetHTML();
const buyProductTemplateUri = 'ui://widget/buy-product-template.html';

mcpServer.registerResource(
  'buy-product-widget',
  buyProductTemplateUri,
  {
    title: 'Buy Product',
    description: 'Buy Product Widget',
    mimeType: 'text/html+skybridge',
  },
  async uri => ({
    contents: [
      {
        uri: uri.href,
        mimeType: 'text/html+skybridge',
        text: widgetHTML,
      },
    ],
  })
);

Your widgetHTML variable references the result of reading an HTML file. This guide does not require you to use any specific coding language or framework. These choices are up to you or your selected integrator. After you register your tool, you must register the complete_checkout tool to use that resource. The following example is a tool that retrieves product information and returns it in the structuredContent field. ChatGPT attaches this response to window.openapi.toolOutput for your application to read and render.

mcpServer.registerTool(
  'show-buy-product-widget',
  {
    title: 'Buy Product',
    description: 'Shows the Buy Now Product Widget',
    inputSchema: {
      // Your integration should use a library like Zod or JSON Schema here.
      product_title: string 
    },
    _meta: { 'openai/outputTemplate': buyProductTemplateUri },
    annotations: { readOnlyHint: true },
  },
  async (input) => {
    //This is just an example, your application can retrieve product information in anyway you see fit
    const product = await productService.findByTitle(input.product_title) 
    return {
      content: [],
      structuredContent: {
       ...product
      },
      _meta: {
        'openai/outputTemplate': widgetHTML,
      },
    };
  }
);

3. Initiate checkout from your ChatGPT app

To initiate checkout from your ChatGPT app, call window.openai.requestCheckout, typically using a button. When ChatGPT initiates checkout, your server’s /checkout_sessions response must specify Braintree as the payment provider according to the ACP agentic checkout specification, as shown in the following example.

{
  "payment_provider": {
    "provider": "braintree",
    "supported_payment_methods": ["card"],
    "merchant_id": "your_braintree_merchant_id"
  }
}

Parameter	Description
`payment_provider.provider`	Payment provider. Set to `braintree`.
`payment_provider.supported_payment_methods`	An array of payment methods that your Braintree integration supports. Available values are: `card` `applepay` `googlepay` Other options, including these, are coming soon: `paypal_wallet` `venmo_wallet`
`merchant_id`	Your Braintree merchant ID, which identifies your Braintree account.

Note: OpenAI uses the merchant_id that you provide here in the allowance.merchant_id field when it requests delegated payment tokens.

4. Register your app in ChatGPT

After you host your MCP server with a publicly available URL, test your application in ChatGPT’s developer mode.

Enable developer mode by navigating to ChatGPT → Settings → Apps → Advanced Settings, and use the toggle to turn on developer mode.
Register your application by navigating to ChatGPT → Settings → Apps → Create App and entering your application URL.

Now you can go to the ChatGPT prompt screen, click the plus (+) symbol, select your application, and enter the prompt to display your widget.

Allowance validation

Braintree validates the following fields in the allowance when issuing a delegated payment token.

`merchant_id`

The merchant_id must match the Braintree public merchant ID that processes the transaction.

{
    "message": "Unknown or expired single-use payment method.",
    "path": ["chargePaymentMethod"],
    "extensions": {
      "errorClass": "VALIDATION",
      "errorType": "user_error",
      "inputPath": ["input", "paymentMethodId"],
      "legacyCode": "91565"
    }
  }

`max_amount`

The max_amount must be greater than or equal to the transaction amount.

{
    "message": "Transaction amount exceeds the payment method maximum amount.",
    "path": ["chargePaymentMethod"],
    "extensions": {
      "errorClass": "VALIDATION",
      "errorType": "user_error",
      "inputPath": ["input", "transaction", "amount"],
      "legacyCode": "915266"
    }
  }

`currency`

The currency on the transaction must match the configured currency for the transacting merchant.

{
    "message": "Transaction currency does not match the payment method currency.",
    "path": ["chargePaymentMethod"],
    "extensions": {
      "errorClass": "VALIDATION",
      "errorType": "user_error",
      "inputPath": ["input", "transaction", "merchantAccountId"],
      "legacyCode": "915267"
    }
  }

`expires_at`

{
    "message": "Unknown or expired single-use payment method.",
    "path": ["chargePaymentMethod"],
    "extensions": {
      "errorClass": "VALIDATION",
      "errorType": "user_error",
      "inputPath": ["input", "paymentMethodId"],
      "legacyCode": "91565"
    }
  }

Track AI-initiated transactions

PayPal and Braintree provide the following ways to track AI-initiated transactions.

Transaction facilitator details

When you process a transaction with a delegated payment token, it includes the following fields in the transaction response.

transaction.facilitator_details.oauth_application_client_id
transaction.facilitator_details.oauth_application_name # "ChatGPT"

For example, your transaction response might look similar to this one.

result = gateway.transaction.find("transaction_id")
puts result.transaction.facilitator_details.oauth_application_name
# => "ChatGPT"
puts result.transaction.facilitator_details.oauth_application_client_id
# => "oauth_client_abc123"

Search for AI-initiated transactions

You can search for transactions by AI platform using the Braintree Control Panel or API.

Braintree Control Panel

Navigate to the Braintree Control Panel.
Use the search filter for facilitator_details.oauth_application_name.
Select ChatGPT to view all ChatGPT-initiated transactions.

API

  query($input: TransactionSearchInput!) {
    search {
      transactions(input: $input) {
        edges {
          node {
            id
            amount { value }
          }
        }
      }
    }
  }

{
  "input": {
    "facilitatorOAuthApplicationClientId": {
      "is": "ChatGPT"
    }
  }
}

{
  "data": {
    "search": {
      "transactions": {
        "edges": [
          {
            "node": {
              "id": "dHJhbnNhY3Rpb25fN3gybWJlcHg",
              "amount": {
                "value": "7.50"
              }
            }
          },
          {
            "node": {
              "id": "dHJhbnNhY3Rpb25fMjlxMXYwNjQ",
              "amount": {
                "value": "10.00"
              }
            }
          }
        ]
      }
    }
  },
  "extensions": {
    "requestId": "f9773cbb-5994-4c04-a55b-ccb20d496a18"
  }
}

Grow your business

Send payouts

Manage disputes

Analyze reports