Hyperfold AI

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:

bash
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
# 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:

bash
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
# 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

ConstraintDescription
Amount LimitMaximum total spend across all transactions
Single UseToken valid for one transaction only
Merchant AllowlistRestrict to specific verified merchants
Category RestrictionLimit to specific merchant categories (MCC)
Confirmation RequiredRequire customer approval for each purchase
Time ExpiryToken expires after specified duration

Manage Tokens

List, inspect, and manage existing tokens:

bash
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
48
49
50
51
52
# 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:

bash
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
# 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.