Hyperfold AI

Shared Payment Tokens (SPT)

Secure, delegated payment tokens that enable agent-to-agent commerce without exposing customer card details.

What is SPT?

Shared Payment Tokens (SPT) are Stripe-powered payment credentials that allow buyer agents to make purchases on behalf of customers. Unlike traditional payment methods, SPTs are designed for autonomous commerce with built-in spending limits and merchant restrictions.

Key features of SPT:

  • Delegated authority: Customers authorize agents to spend within defined limits
  • No card exposure: Actual payment credentials never leave Stripe's vault
  • Merchant restrictions: Tokens can be limited to verified merchants or categories
  • Audit trail: Every charge is logged with agent metadata for accountability

How It Works

The SPT flow involves three parties: the customer, the buyer agent, and the seller agent:

     Customer              Buyer Agent            Seller Agent
      (Human)               (OpenAI)              (Hyperfold)
         │                      │                      │
         │  1. "Buy me shoes"   │                      │
         │─────────────────────▶│                      │
         │                      │                      │
         │                      │  2. Search + Quote   │
         │                      │─────────────────────▶│
         │                      │                      │
         │                      │  3. Counter: $162    │
         │                      │◀─────────────────────│
         │                      │                      │
         │  4. "Accept $162?"   │                      │
         │◀─────────────────────│                      │
         │                      │                      │
         │  5. "Yes, buy it"    │                      │
         │─────────────────────▶│                      │
         │                      │                      │
         │                      │  6. Checkout + SPT   │
         │                      │─────────────────────▶│
         │                      │                      │
         │                      │  7. Charge via SPT   │
         │                      │        ┌─────────────┤
         │                      │        │   Stripe    │
         │                      │        └─────────────┤
         │                      │                      │
         │  8. Order #12345     │◀─────────────────────│
         │◀─────────────────────│                      │
         │                      │                      │

Steps 1-3: Discovery & Negotiation

The buyer agent searches for products and negotiates price. No payment credentials are involved yet—just ACP protocol messages.

Steps 4-5: Customer Confirmation

For purchases above a threshold, the agent seeks customer approval. Below-threshold purchases can be auto-approved based on SPT settings.

Steps 6-7: SPT Payment

The buyer agent sends its SPT to the seller. The seller charges via Stripe without ever seeing the underlying card number.

Security Model

SPT implements multiple layers of security to protect customers:

ProtectionDescription
Spending LimitsPer-transaction and daily/monthly caps defined by customer
Merchant AllowlistTokens can be restricted to verified Hyperfold merchants only
Category RestrictionsLimit purchases to specific MCC codes (retail, travel, etc.)
Time ExpiryTokens automatically expire after configurable period (default 24h)
Confirmation ThresholdPurchases above threshold require explicit customer approval
RevocationCustomers can instantly revoke tokens from their dashboard

Creating Tokens

Customers create SPTs through your application's checkout flow:

import Stripe from 'stripe';
const stripe = new Stripe(process.env.STRIPE_SECRET_KEY);
// Customer creates a reusable payment method token
// that can be shared with authorized agents
async function createSharedPaymentToken(customerId: string) {
  // Create a SetupIntent for the customer
  const setupIntent = await stripe.setupIntents.create({
    customer: customerId,
    usage: 'off_session',
    metadata: {
      purpose: 'agentic_commerce',
      max_amount: '500.00',
      valid_merchants: 'hyperfold_verified'
    }
  });
  // After customer confirms, create the shareable token
  const paymentMethod = await stripe.paymentMethods.retrieve(
    setupIntent.payment_method as string
  );
  // Generate SPT for agent use
  const spt = await stripe.tokens.create({
    customer: customerId,
    // SPT includes spending limits and merchant restrictions
  });
  return {
    token: spt.id,  // spt_live_abc123...
    expires_at: new Date(Date.now() + 24 * 60 * 60 * 1000),
    constraints: {
      max_single_charge: 500.00,
      allowed_categories: ['retail', 'apparel'],
      requires_confirmation: false  // for amounts < $100
    }
  };
}

CLI Testing

For development, use the CLI to create test tokens:

# Generate a test SPT for development
$ hyperfold tokenise --amount=100 --currency=usd
> [Stripe] Creating test payment token...
> [Config] Max charge: $100.00 USD
> [Config] Expires: 24 hours
> [SUCCESS] Token created: spt_test_abc123xyz
# Use in simulation
$ hyperfold sim chat --persona="premium_buyer" --token="spt_test_abc123xyz"

Using Tokens

Seller agents receive SPTs during checkout and process them via Stripe:

// Seller agent receives SPT and processes payment
async function processAgentPayment(
  sptToken: string,
  amount: number,
  orderId: string
) {
  const stripe = new Stripe(process.env.STRIPE_SECRET_KEY);
  // Create PaymentIntent using the SPT
  const paymentIntent = await stripe.paymentIntents.create({
    amount: Math.round(amount * 100), // cents
    currency: 'usd',
    payment_method: sptToken,
    confirm: true,
    off_session: true,  // No customer present
    metadata: {
      order_id: orderId,
      channel: 'agentic_commerce',
      buyer_agent: 'openai_gpt4',
      seller_agent: 'hyperfold_negotiator'
    }
  });
  if (paymentIntent.status === 'succeeded') {
    return {
      success: true,
      charge_id: paymentIntent.latest_charge,
      receipt_url: paymentIntent.charges?.data[0]?.receipt_url
    };
  }
  throw new Error(`Payment failed: ${paymentIntent.status}`);
}