Hyperfold AI
Back

Dec 8, 2025

Payment Token Management

H
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:

bash
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
# 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:

typescript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
// 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:

  1. Buyer agent initiates checkout with POST /acp/checkout/init
  2. Your agent returns checkout summary and payment instructions
  3. Buyer agent obtains SPT from their payment provider
  4. Buyer agent finalizes with POST /acp/checkout/finalize including token
  5. 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:

bash
1
2
3
4
5
6
7
8
9
# 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