Dec 8, 2025

Payment Token Management

Hyperfold Team

Payments

SPT Overview

Shared Payment Tokens (SPT) enable secure agent-to-agent payment delegation. When a buyer agent wants to purchase, it provides a payment token that the seller agent can use to capture payment within defined constraints.

Key benefits:

No PCI data touches your systems
Tokens are constrained by amount and time
Single-use prevents replay attacks
Full audit trail for compliance

Stripe Setup

Configure Stripe for SPT payments:

# Configure Stripe for SPT
$ hyperfold payments configure stripe

> [Config] Enter your Stripe secret key: sk_live_...
> [Config] Enter your Stripe webhook secret: whsec_...
> [Setup] Enabling Shared Payment Tokens...
> [Verify] Testing API connection...

✓ Stripe configured!

Mode:           Live
SPT Enabled:    Yes
Webhook URL:    https://your-agent.run.app/webhooks/stripe

# Create webhook endpoint in Stripe Dashboard:
# Events: payment_intent.succeeded, payment_intent.failed

Token Creation

Create tokens during checkout initialization:

// Token creation and usage
import { createPaymentToken, capturePayment } from '@hyperfold/payments';

// Create SPT for agent delegation
async function createCheckoutToken(checkoutId: string, amount: number) {
const token = await createPaymentToken({
  provider: 'stripe',
  amount,
  currency: 'USD',
  checkout_id: checkoutId,
  // Token constraints
  max_amount: amount * 1.1, // Allow 10% buffer for tax
  valid_for: '30m',         // 30 minute expiration
  single_use: true,
});

return {
  token: token.id,           // spt_live_abc123...
  expires_at: token.expires_at,
  constraints: token.constraints,
};
}

// Capture payment with token
@OnACPEvent('checkout.finalize')
async handleFinalize(request: FinalizeRequest) {
const { checkout_id, payment_token } = request;

// Validate and capture
const result = await capturePayment({
  token: payment_token,
  checkout_id,
});

if (result.status === 'succeeded') {
  return {
    status: 'success',
    order_id: result.order_id,
    receipt_url: result.receipt_url,
  };
}

return {
  status: 'failed',
  error: result.error_message,
};
}

Secure Checkout

The checkout flow with SPT:

Buyer agent initiates checkout with POST /acp/checkout/init
Your agent returns checkout summary and payment instructions
Buyer agent obtains SPT from their payment provider
Buyer agent finalizes with POST /acp/checkout/finalize including token
Your agent captures payment using the token

Always validate token constraints before capture. Check amount matches, token hasn't expired, and checkout_id is correct.

Token Lifecycle

Manage token states:

# View recent tokens
$ hyperfold payments tokens list --last=24h

TOKEN ID              AMOUNT    STATUS      CREATED           USED
spt_live_abc123       $162.00   captured    Dec 19, 14:30    Dec 19, 14:32
spt_live_def456       $89.99    expired     Dec 19, 13:15    -
spt_live_ghi789       $245.00   captured    Dec 19, 12:00    Dec 19, 12:01

# Token states: pending, captured, expired, failed