Payment Tokenization

Create and manage Shared Payment Tokens (SPT) for agent commerce.

Overview

The hyperfold pay tokenise command creates Shared Payment Tokens that buyer agents use to make purchases. SPTs delegate payment authority with configurable spending limits and merchant restrictions.

SPTs are test tokens for development. In production, customers create tokens through your application's checkout flow using the Stripe SDK.

Create Token

Generate a test token for development and simulation:

# Create a Shared Payment Token for testing
$ hyperfold pay tokenise --amount=100 --currency=usd

> [Stripe] Creating test payment token...
> [Config] Max charge: $100.00 USD
> [Config] Expires: 24 hours
> [SUCCESS] Token created

  Token:       spt_test_abc123xyz
  Max Amount:  $100.00 USD
  Expires:     2025-12-20T14:30:00Z
  Scopes:      retail, apparel

⚠ Store this token securely. It will not be shown again.

# Create token with specific constraints
$ hyperfold pay tokenise \
  --amount=500 \
  --currency=usd \
  --expires="7d" \
  --merchant-categories="retail,apparel" \
  --require-confirmation

> [Stripe] Creating constrained payment token...
✓ Token created: spt_test_xyz789

  Constraints:
    Max charge:     $500.00
    Categories:     retail, apparel
    Confirmation:   Required for all purchases
    Expires:        Dec 26, 2025

Token Constraints

Configure spending limits and restrictions on tokens:

# View token constraint options
$ hyperfold pay tokenise --help

OPTIONS:
  --amount          Maximum charge amount (required)
  --currency        Currency code (default: USD)
  --expires         Expiration time (default: 24h)
                    Examples: 1h, 24h, 7d, 30d

CONSTRAINTS:
  --single-use              Token valid for one charge only
  --require-confirmation    Require customer approval for each charge
  --merchant-categories     Comma-separated MCC codes or names
  --max-daily              Daily spending limit
  --max-transactions       Maximum number of transactions

MERCHANT RESTRICTIONS:
  --merchants              Comma-separated merchant IDs
  --merchant-allowlist     Only allow specific merchants
  --merchant-blocklist     Block specific merchants

# Example: Create a restrictive token
$ hyperfold pay tokenise \
  --amount=200 \
  --single-use \
  --merchant-allowlist="merchant_hyperfold_acme" \
  --expires="1h"

> Token: spt_test_restrictive123
> Single-use, 1 hour expiry, Acme Sports only

Constraint Types

Constraint	Description
Amount Limit	Maximum total spend across all transactions
Single Use	Token valid for one transaction only
Merchant Allowlist	Restrict to specific verified merchants
Category Restriction	Limit to specific merchant categories (MCC)
Confirmation Required	Require customer approval for each purchase
Time Expiry	Token expires after specified duration

Manage Tokens

List, inspect, and manage existing tokens:

# List active tokens
$ hyperfold pay tokens list

ACTIVE TOKENS

TOKEN                     AMOUNT    USED      EXPIRES         STATUS
spt_test_abc123           $100      $0        Dec 20, 14:30   active
spt_test_xyz789           $500      $162      Dec 26, 00:00   active
spt_live_premium          $1000     $450      Jan 15, 2026    active

# Get token details
$ hyperfold pay tokens get spt_test_abc123

TOKEN: spt_test_abc123
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

LIMITS:
  Max Amount:       $100.00 USD
  Remaining:        $100.00
  Used:             $0.00

CONSTRAINTS:
  Single Use:       No
  Confirmation:     Not required under $100
  Categories:       retail, apparel

STATUS:
  Created:          2025-12-19T14:30:00Z
  Expires:          2025-12-20T14:30:00Z
  Transactions:     0

# Revoke a token
$ hyperfold pay tokens revoke spt_test_abc123

> [Stripe] Revoking token...
✓ Token revoked

# Extend token expiration
$ hyperfold pay tokens extend spt_test_xyz789 --expires="14d"

> [Stripe] Extending token expiration...
✓ Token extended to Jan 2, 2026

# View token transaction history
$ hyperfold pay tokens history spt_test_xyz789

TRANSACTION HISTORY

DATE                AMOUNT    MERCHANT          STATUS
Dec 19, 14:35       $162.00   Acme Sports       succeeded
Dec 19, 15:20       $45.00    Acme Sports       succeeded
Dec 19, 16:10       $89.00    Acme Sports       declined (limit)

Customers can revoke tokens at any time from their dashboard. Always handle revocation gracefully in your agent code.

Simulation Tokens

Use test tokens in agent simulations:

# Create tokens for simulation testing
$ hyperfold pay tokenise --test --amount=1000

> [Test Mode] Creating simulation token...
✓ Test token: spt_test_simulation_abc

# Use test token in simulation
$ hyperfold sim chat --persona="premium_buyer" --token="spt_test_simulation_abc"

> [Sim] Starting simulation with test payment token
> [Sim] Token limit: $1000.00

Customer: I want to buy running shoes
Agent: I'd recommend the AeroRun X2. It's $180, or $162 with your Gold discount.
Customer: I'll take it
Agent: [Processing payment via SPT...]
Agent: Order confirmed! Your AeroRun X2 will arrive in 2-3 days.

> [Sim] Payment processed: $162.00
> [Sim] Remaining token balance: $838.00

# Simulate token scenarios
$ hyperfold sim chat --persona="budget_buyer" --token="spt_test_low_limit" --scenario="exceed_limit"

> [Sim] Testing token limit exceeded scenario...
Customer: I want to buy the $500 jacket
Agent: I'd love to help, but your payment authorization is limited to $100.
       Would you like to see some options within that budget?

Learn more about SPT in the SPT Concepts guide.