ACP Checkout Session

ACP Checkout Session

ACP (Agent Commerce Protocol) provides a Stripe-backed checkout flow for AI agent commerce. This example demonstrates creating a checkout session, completing payment, and handling the response.

Step 1: Create Checkout Session

const sessionPayload = {
  items: [
    {
      name: 'Premium AI Agent Subscription',
      amount: 49.99,
      currency: 'USD',
      quantity: 1,
    },
  ],
  success_url: 'https://yourapp.com/success',
  cancel_url: 'https://yourapp.com/cancel',
  metadata: {
    agent_id: 'agent_456',
    platform: 'phantoid',
  },
};

const response = await fetch('https://api.soft.house/acp/checkout-sessions', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': `checkout_${Date.now()}`,
  },
  body: JSON.stringify(sessionPayload),
});

const session = await response.json();
console.log(`Session ID: ${session.id}`);
console.log(`Checkout URL: ${session.checkout_url}`);

Step 2: Complete the Checkout

// After the user completes payment on the Stripe checkout page
const completeResponse = await fetch(
  `https://api.soft.house/acp/checkout-sessions/${session.id}/complete`,
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${apiKey}`,
      'Content-Type': 'application/json',
    },
  }
);

const result = await completeResponse.json();
console.log(`Payment status: ${result.payment_status}`);
console.log(`Amount charged: ${result.amount_paid}`);

Step 3: Handle Webhooks

// Set up a webhook endpoint to receive payment events
// POST /webhooks/soft-house
app.post('/webhooks/soft-house', async (req, res) => {
  const signature = req.headers['x-webhook-signature'];

  // Verify HMAC signature (classical layer)
  const isValid = verifyWebhookSignature(
    req.body,
    signature,
    process.env.WEBHOOK_SECRET
  );

  if (!isValid) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  const event = req.body;

  switch (event.type) {
    case 'checkout.completed':
      console.log(`Payment received: ${event.data.amount_paid}`);
      break;
    case 'checkout.failed':
      console.log(`Payment failed: ${event.data.failure_reason}`);
      break;
  }

  res.status(200).json({ received: true });
});

Response

{
  "id": "cs_live_abc123",
  "status": "complete",
  "payment_status": "paid",
  "amount_paid": 49.99,
  "currency": "USD",
  "items": [
    {
      "name": "Premium AI Agent Subscription",
      "amount": 49.99,
      "quantity": 1
    }
  ],
  "created_at": "2026-03-03T12:00:00Z",
  "completed_at": "2026-03-03T12:02:30Z"
}

Key Concepts

• Idempotency Keys: Always include an idempotency key to prevent duplicate charges
• Webhook Verification: Both HMAC (classical) and ML-DSA-65 (quantum) signatures are verified
• Session Expiration: Checkout sessions expire after 30 minutes by default
• Stripe Connect: Platform commissions are calculated server-side (never trust client data)