ACP: Agentic Commerce Protocol

Overview

ACP (Agentic Commerce Protocol) is OpenAI and Stripe’s standard for AI agent commerce. It uses checkout sessions and bearer tokens for payment processing, built on top of Stripe’s infrastructure.

ACP sits in the Execution Layer of our three-layer architecture, answering: “Process the transaction.”

Key Concepts

Checkout Sessions

Checkout sessions are the core primitive. They represent a single purchase flow:

const session = await soft.acp.sessions.create({
  line_items: [
    {
      name: 'Laptop Stand',
      amount: 4999,  // $49.99 in cents
      currency: 'usd',
      quantity: 1,
    },
  ],
  payment_method: 'card',
  success_url: 'https://your-app.com/success',
  cancel_url: 'https://your-app.com/cancel',
});

Payment Delegation

SharedPaymentTokens allow agents to make purchases on behalf of users with scoped permissions:

const token = await soft.acp.delegation.create({
  user_id: 'user_123',
  scope: {
    merchant_id: 'merchant_456',
    max_amount: 10000,  // $100.00
    currency: 'usd',
    expires_at: '2026-02-01T00:00:00Z',
  },
});

Bearer Token Authentication

ACP uses bearer tokens for authentication, matching OpenAI’s agent authentication pattern:

// Agent authenticates with bearer token
const response = await fetch('https://api.soft.house/acp/sessions', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${agentToken}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ /* session data */ }),
});

Session Lifecycle

1. Create — Agent creates a checkout session with line items
2. Authorize — User reviews and authorizes the payment
3. Process — Stripe Payment Intent is created and charged
4. Complete — Webhook confirms successful payment
5. Fulfill — Order is fulfilled to the user

Implementation

Create Checkout Session

const session = await soft.acp.sessions.create({
  line_items: [
    { name: 'Wireless Mouse', amount: 2999, currency: 'usd', quantity: 1 },
    { name: 'USB-C Hub', amount: 3499, currency: 'usd', quantity: 1 },
  ],
  metadata: {
    order_id: 'order_789',
    agent_id: 'agent_gpt4',
  },
});

Complete Checkout

const result = await soft.acp.sessions.complete(session.id, {
  payment_method_id: 'pm_card_visa',
  idempotency_key: 'checkout_unique_123',
});

Handle Webhooks

// Verify Stripe webhook signature
const event = stripe.webhooks.constructEvent(
  body,
  signature,
  webhookSecret,
);

switch (event.type) {
  case 'checkout.session.completed':
    await handleSessionCompleted(event.data.object);
    break;
  case 'payment_intent.succeeded':
    await handlePaymentSuccess(event.data.object);
    break;
}

API Endpoints

Method	Path	Description
POST	/acp/sessions	Create checkout session
GET	/acp/sessions/:id	Retrieve session
PUT	/acp/sessions/:id	Update session
POST	/acp/sessions/:id/complete	Complete checkout
POST	/acp/sessions/:id/cancel	Cancel session
POST	/acp/delegation	Create payment delegation
GET	/acp/delegation/:id	Get delegation details

Security

• HMAC Webhook Verification — All Stripe webhooks are signature-verified
• Idempotency Keys — 24-hour KV cache prevents duplicate charges
• Bearer Token Scoping — Tokens are scoped to specific merchants and amounts
• Session Expiration — Checkout sessions expire after configurable TTLs
• CSRF Protection — All state-changing operations require CSRF tokens