{"title":"In-Chat App Integration","category":"default","creationDate":1778252957,"content":"

Build an ecommerce experience that is native to ChatGPT, where your shoppers can make transactions directly inside of the chat interface. Using the OpenAI Apps SDK<\/a>, you can create custom, interactive ecommerce interfaces where users can browse, select, and pay without leaving the AI chat. Adyen securely processes payments initiated by these interactions with AI agents, ensuring a seamless flow from chat to checkout.<\/p>\n

Requirements<\/h2>\n\n\n\n\n\n\n\n
Requirement<\/th>\nDescription<\/th>\n<\/tr>\n<\/thead>\n
Integration type<\/strong><\/td>\nAn online payments<\/a> integration.<\/td>\n<\/tr>\n
Setup steps<\/strong><\/td>\nBefore you begin:
Limitations<\/strong><\/td>\nInstant Checkout<\/a> availability is limited. If it is not available to you, you can instead redirect shoppers to your own checkout page. By redirecting shoppers to your own checkout page, you have full control over the checkout experience and can use any online payments integration<\/a>, like Drop-in\/Components or Hosted Checkout.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n

How it works<\/h2>\n

To accept payments in your ChatGPT app with Adyen, you need to implement the following components:<\/p>\n\n\n\n\n\n\n\n
Component<\/th>\nDescription<\/th>\n<\/tr>\n<\/thead>\n
Checkout session creation tool<\/strong><\/td>\nAn MCP tool that creates a checkout session with line items, totals, and Adyen as the payment provider.<\/td>\n<\/tr>\n
Widget<\/strong><\/td>\nYour ChatGPT app UI component that displays the cart and calls window.openai.requestCheckout<\/code> to initiate payment.<\/td>\n<\/tr>\n
complete_checkout tool<\/strong><\/td>\nAn MCP tool that receives the ACP token from OpenAI and calls Adyen to authorize the payment.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n

Create MCP tools that correspond to the Agentic Checkout Spec (ACS)<\/a> REST endpoints:<\/p>\n\n\n\n\n\n\n
MCP tool<\/th>\nACS endpoint<\/th>\n<\/tr>\n<\/thead>\n
Checkout session tool<\/strong><\/td>\n\n POST \/checkout_sessions<\/code>\n<\/a><\/td>\n<\/tr>\n
complete_checkout<\/strong><\/td>\n\n POST \/checkout_sessions\/{id}\/complete<\/code>\n<\/a><\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n

Transaction flow<\/h3>\n

When a shopper initiates a transaction in the chat interface, the following flow occurs:<\/p>\n

    \n
  1. Shopper initiates transaction<\/strong>: The shopper prompts the AI agent to buy something from you, and the checkout session tool from your MCP server is invoked.<\/li>\n
  2. Server prepares session<\/strong>: Your MCP tool returns checkout session data (session ID, line items, totals, Adyen as the payment provider) in structuredContent<\/code>.<\/li>\n
  3. Widget previews cart<\/strong>: Your widget renders the line items and totals so that the shopper can review and confirm.<\/li>\n
  4. Widget calls requestCheckout<\/strong>: When the shopper selects the button to continue with checkout, your widget calls window.openai.requestCheckout(session_data)<\/code>. ChatGPT opens the Instant Checkout UI and shows available payment methods.<\/li>\n
  5. Shopper selects payment method and pays<\/strong>: The shopper selects their payment method and clicks Pay<\/strong>. ChatGPT communicates with Adyen to register the Agentic Commerce Protocol (ACP) token, then calls the complete_checkout<\/code> tool from your MCP server with the ACP token in payment_data.token<\/code>.<\/li>\n
  6. Server authorizes payment<\/strong>: Your complete_checkout<\/code> tool uses the ACP token to make a payment request to Adyen. Adyen authorizes the payment and returns the result.<\/li>\n
  7. Order confirmation<\/strong>: Your MCP tool returns payment result to ChatGPT, which passes it to your widget. Your widget displays the payment result to the shopper.<\/li>\n<\/ol>\n

    The following diagram shows the interaction between the shopper in the chat interface, your app widget, the Apps SDK, your MCP server, and Adyen's server.<\/p>\n

    CnNlcXVlbmNlRGlhZ3JhbQoKcGFydGljaXBhbnQgU2hvcHBlciBhcyBTaG9wcGVyCnBhcnRpY2lwYW50IFdpZGdldCBhcyBXaWRnZXQKcGFydGljaXBhbnQgU0RLIGFzIEFwcHMgU0RLCnBhcnRpY2lwYW50IE1DUCBhcyBZb3VyIE1DUCBTZXJ2ZXIKcGFydGljaXBhbnQgQWR5ZW4gYXMgQWR5ZW4KClNob3BwZXItPj5XaWRnZXQ6IFByb21wdCB0byBzdGFydCB0cmFuc2FjdGlvbgpXaWRnZXQtPj5TREs6IEludm9rZSBjaGVja291dCB0b29sClNESy0+Pk1DUDogQ2FsbCBjaGVja291dCB0b29sCk1DUC0tPj5TREs6IFJldHVybiBjaGVja291dCBzZXNzaW9uIGRhdGEgKHByb3ZpZGVyOiBhZHllbikKU0RLLS0+PldpZGdldDogUmV0dXJuIHN0cnVjdHVyZWQgY29udGVudApXaWRnZXQtLT4+U2hvcHBlcjogU2hvdyBwcm9kdWN0IHBhZ2UKU2hvcHBlci0+PldpZGdldDogU2VsZWN0IGJ1dHRvbiB0byBjb250aW51ZSB3aXRoIGNoZWNrb3V0CldpZGdldC0+PlNESzogQ2FsbCB3aW5kb3cub3BlbmFpLnJlcXVlc3RDaGVja291dApTREstLT4+U2hvcHBlcjogU2hvdyBwYXltZW50IHBhZ2UKU2hvcHBlci0+PlNESzogU2VsZWN0IHBheW1lbnQgbWV0aG9kClNESy0+Pk1DUDogQ2FsbCBjb21wbGV0ZV9jaGVja291dApNQ1AtPj5BZHllbjogTWFrZSBQT1NUIC9wYXltZW50cyByZXF1ZXN0CkFkeWVuLS0+Pk1DUDogUmV0dXJuIHBheW1lbnQgcmVzdWx0Ck1DUC0tPj5TREs6IFJldHVybiBvcmRlciBpbmZvcm1hdGlvbgpTREstLT4+V2lkZ2V0OiBSZXR1cm4gb3JkZXIgY29uZmlybWF0aW9uCldpZGdldC0tPj5TaG9wcGVyOiBTaG93IHBheW1lbnQgcmVzdWx0Cg==<\/div><\/div>\n

    Build your checkout session tool<\/h2>\n

    Create an MCP tool that returns the checkout session data in the payment_provider<\/code> object in structuredContent<\/code>. Include in the merchant_id<\/code> field:<\/p>\n

    It must include the following:<\/p>\n\n\n\n\n\n\n\n
    Field<\/th>\nDescription<\/th>\n<\/tr>\n<\/thead>\n
    provider<\/code><\/td>\nadyen<\/strong><\/td>\n<\/tr>\n
    merchant_id<\/code><\/td>\nYour Adyen merchant account<\/a>.<\/td>\n<\/tr>\n
    supported_payment_methods<\/code><\/td>\nAn array of supported payment methods.
    Example: [scheme]<\/strong><\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
    \n <\/code-sample>\n<\/div>\n

    For the full checkout session payload structure, go to the Agentic Checkout Spec<\/a>.<\/p>\n

    Build your widget<\/h2>\n

    Create a widget that handles the checkout UI and initiates the payment flow. Your widget must:<\/p>\n

      \n
    1. Receive the checkout session data from your MCP tool via structuredContent<\/code>.<\/li>\n
    2. Render the cart (line items, totals, terms) so the shopper can review before paying.<\/li>\n
    3. Call window.openai.requestCheckout(session_data)<\/code> when the shopper clicks to proceed.<\/li>\n<\/ol>\n

      Call requestCheckout<\/code><\/h3>\n

      When the shopper indicates that they are ready to pay, call window.openai.requestCheckout<\/code> with your checkout session data. This opens the Instant Checkout UI where the shopper selects their payment method.<\/p>\n

      \n <\/code-sample>\n<\/div>\n

      The function returns a promise that resolves with the order result or rejects on error or cancellation.<\/p>\n

      For further details on building widgets, go to the OpenAI Apps SDK monetization guide<\/a>.<\/p>\n

      Build your complete_checkout<\/code> tool<\/h2>\n

      When the shopper selects a payment method and selects the pay button, OpenAI calls the complete_checkout<\/code> tool from your MCP server with the ACP token in payment_data.token<\/code>. Use this token to authorize the payment with Adyen.<\/p>\n

      For the Adyen API request details, go to Authorize a payment with the ACP token<\/a>.<\/p>\n

      Handle errors<\/h3>\n

      Your complete_checkout<\/code> tool can return error messages to handle payment failures. The following error codes are displayed on the Instant Checkout UI:<\/p>\n\n\n\n\n\n\n
      Error code<\/th>\nDescription<\/th>\n<\/tr>\n<\/thead>\n
      payment_declined<\/code><\/td>\nThe payment was declined by Adyen.<\/td>\n<\/tr>\n
      requires_3ds<\/code><\/td>\nThe payment requires 3D Secure authentication.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n

      All other error messages are returned to your widget as a response to requestCheckout<\/code>, where you can show them.<\/p>\n

      For the full list of error codes, go to the ACP error messages specification<\/a>.<\/p>\n

      Testing<\/h2>\n

      Use ChatGPT's test payment mode with the Adyen test environment to test your integration without processing real payments.<\/p>\n

        \n
      1. \n

        Use your test Adyen merchant account and your test API credentials<\/a>.<\/p>\n<\/li>\n

      2. \n

        Set payment_mode: test<\/code> in your requestCheckout<\/code> call.<\/p>\n

        \n<\/code-sample>\n<\/div>\n<\/li>\n
      3. \n

        Use Adyen test card numbers<\/a>, for example: 4111 1111 1111 1111<\/strong>.<\/p>\n<\/li>\n

      4. \n

        Verify that you receive test payments:<\/p>\n