Stripe Integration Guide

This guide covers integrating ACP with Stripe, from uploading your product catalog to processing payments with Shared Payment Tokens.

Overview

In an agentic checkout flow:

The AI agent presents the checkout interface and collects payment credentials. You keep your existing data model and payment processing.

Key Concepts

Sellers

Sellers are businesses or platforms that provide e-commerce goods, subscriptions, digital content, or API functions. You use the AI agent as a sales channel for your products.

AI Agents

Agents are LLM-powered applications that discover and recommend products for purchase. When a customer prompts the agent, it can display products through its interface.

The AI agent creates a Customer object for each customer and stores their payment information for reuse.

Shared Payment Tokens (SPTs)

SPTs are scoped grants of a payment method. Key properties:

You use SPTs directly in PaymentIntents flows.

Transaction Flow

┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   Customer  │     │  AI Agent   │     │   Seller    │     │   Stripe    │
└──────┬──────┘     └──────┬──────┘     └──────┬──────┘     └──────┬──────┘
       │                   │                   │                   │
       │ Payment method    │                   │                   │
       │──────────────────>│                   │                   │
       │                   │                   │                   │
       │                   │ Request SPT       │                   │
       │                   │───────────────────────────────────────>
       │                   │                   │                   │
       │                   │ SPT issued        │                   │
       │                   │<───────────────────────────────────────
       │                   │                   │                   │
       │                   │ Send SPT + amount │                   │
       │                   │──────────────────>│                   │
       │                   │                   │                   │
       │                   │                   │ Create PaymentIntent
       │                   │                   │──────────────────>│
       │                   │                   │                   │
       │                   │                   │ Payment processed │
       │                   │                   │<──────────────────│
       │                   │                   │                   │

1. Customer provides payment method to the agent
2. Agent requests SPT from Stripe (specifies seller, amount, payment method)
3. Agent sends SPT and transaction amount to seller
4. Seller creates PaymentIntent using the SPT
5. Stripe processes the transaction

Set Up Your Stripe Account

Upload Your Product Catalog

You can upload via the Dashboard or API.

curl https://files.stripe.com/v1/files \
  -u sk_test_YOUR_KEY: \
  -F purpose=data_management_manual_upload \
  -F file="@/path/to/your/file.csv;type=text/csv"

curl https://api.stripe.com/v1/data_management/import_sets \
  -H "Stripe-Version: 2025-09-30.clover;udap_beta=v1" \
  -u sk_test_YOUR_KEY: \
  -d file={{FILE_ID}} \
  --data-urlencode standard_data_format="product_catalog_feed"

curl https://api.stripe.com/v1/data_management/import_sets/{{IMPORT_SET_ID}} \
  -u sk_test_YOUR_KEY:

curl https://files.stripe.com/v1/files/{{ERROR_FILE_ID}}/contents \
  -u sk_test_YOUR_KEY:

Working with Shared Payment Tokens

Create a test SPT

Use test helpers to simulate receiving an SPT:

curl https://api.stripe.com/v1/test_helpers/shared_payment/granted_tokens \
  -u sk_test_YOUR_KEY: \
  -d payment_method=pm_card_visa \
  -d "usage_limits[currency]"=usd \
  -d "usage_limits[max_amount]"=10000 \
  -d "usage_limits[expires_at]"={{TIME_IN_FUTURE}} \
  -d "seller_details[network_id]"=internal \
  -d "seller_details[external_id]"={{ANY_STRING}}

Parameters:

Use an SPT to complete payment

Create a PaymentIntent with the granted token:

curl https://api.stripe.com/v1/payment_intents \
  -u sk_test_YOUR_KEY: \
  -d amount=10000 \
  -d currency=usd \
  -d shared_payment_granted_token=spt_123 \
  -d confirm=true

When confirmed, Stripe sets payment_method to a new PaymentMethod cloned from the customer’s original. Subsequent events (refunds, reporting) behave as if you provided the PaymentMethod directly.

Retrieve SPT details

curl https://api.stripe.com/v1/shared_payment/granted_tokens/{id} \
  -u sk_test_YOUR_KEY:

Response includes:

• Limited info about the underlying payment method (card brand, last four)
• Usage limits

{
  "id": "spt_1RgaZcFPC5QUO6ZCDVZuVA8q",
  "object": "shared_payment.granted_token",
  "created": 1751500820,
  "usage_limits": {
    "currency": "usd",
    "expires_at": 1751587220,
    "max_amount": 1000
  }
}

SPT Webhook Events

ACP Protocol Integration

The Agentic Commerce Protocol is a RESTful interface (or MCP server) with four endpoints.

Checkout Lifecycle

1. Customer expresses intent → Agent sends CreateCheckoutRequest
2. Seller generates cart → Responds with checkout state
3. Agent renders UI → Shows total, options to customer
4. Customer makes selections → Agent/seller exchange UpdateCheckoutRequest
5. Customer confirms → Agent provisions SPT, sends CompleteCheckoutRequest
6. Seller creates PaymentIntent → Sends confirmation to agent

Required Endpoints

Every response includes the current checkout state as a reference for the agent.

Events (Webhooks)

After checkout completes, notify the agent about order updates:

• Order created
• Order shipped
• Refund processed
• etc.

This enables the agent to communicate status changes to the customer.

Security Requirements

• All requests require HTTPS with Authorization: Bearer {token}
• Sign all webhook events with HMAC signature in request header
• The agent provides authorization and signing keys during onboarding

Enable Selling on AI Agents

When ready to go live:

1. Review agent terms in the Stripe Dashboard
2. Enable the agent
3. Stripe sends approval request to the agent
4. Agent accepts → You’re live

Pause or stop selling

Disable the agent in the Dashboard, or via API:

curl -X POST https://api.stripe.com/v2/agentic_commerce/agreements/{{AGREEMENT_ID}}/terminate \
  -u sk_test_YOUR_KEY:

Agreement webhooks

• agentic_commerce_agreement.confirmed — Agreement active
• agentic_commerce_agreement.terminated — Agreement ended

Optional Configuration

Manual capture

By default, payments capture immediately. To use manual capture:

1. Open Agentic Settings in Dashboard
2. Set capture mode to manual
3. Call capture when ready:

curl -X POST https://api.stripe.com/v1/payment_intents/pi_xxx/capture \
  -u sk_test_YOUR_KEY: \
  -H "Stripe-Version: 2025-09-30.preview"

Pre-confirmation approval hook

Add control over whether to complete a purchase. Before checkout completes, Stripe sends an approval request to your endpoint.

Setup:

1. Specify your endpoint in the Dashboard
2. Implement your logic

Request format:

{
  "type": "String",
  "id": "String",
  "data": {
    "amount_total": 10000,
    "currency": "usd",
    "line_items_details": [...],
    "payment_method_details": {...},
    "fulfillment_details": {...}
  }
}

Response format:

{
  "manual_approval_details": {
    "type": "approved" | "declined",
    "declined": {
      "reason": "Out of stock"
    }
  }
}

ChatGPT App Monetization

Two options for accepting payments in ChatGPT apps:

Redirect: Use Stripe’s prebuilt checkout page. Customers open a new tab to pay.

Instant Checkout: Build a custom integration. Customers complete checkout without leaving ChatGPT.

Next Steps

• Going Live Checklist — Production requirements
• API Reference — Full API documentation
• Agentic Commerce Suite — Stripe’s managed solution