Hyperfold AI

Payment Configuration

Connect payment providers and configure transaction routing.

Overview

The hyperfold pay configure command connects payment providers like Stripe and PayPal to your Hyperfold project. Once connected, agents can process payments using Shared Payment Tokens (SPT).

Stripe is the recommended provider for SPT transactions. It provides the best support for tokenized, agent-initiated payments.

Stripe Setup

Connect your Stripe account for payment processing:

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
# Connect Stripe account
$ hyperfold pay configure stripe
 
> [OAuth] Opening Stripe Connect authorization...
> [Verify] Validating account permissions...
 
✓ Stripe connected!
 
  Account ID:    acct_abc123
  Business:      Acme Sports Inc.
  Country:       US
  Capabilities:  card_payments, transfers, spt
 
# Or configure with API keys directly
$ hyperfold pay configure stripe \
  --secret-key="sk_live_xxx" \
  --publishable-key="pk_live_xxx"
 
> [Validate] Verifying API keys...
> [Store] Saving to Secret Manager...
✓ Stripe configured
 
# View current Stripe configuration
$ hyperfold pay status stripe
 
STRIPE CONFIGURATION
  Account:        acct_abc123
  Mode:           live
  Connected:      2025-12-01T10:00:00Z
 
  CAPABILITIES:
    ✓ Card payments
    ✓ Transfers
    ✓ SPT (Shared Payment Tokens)
 
  WEBHOOKS:
    ✓ payment_intent.succeeded
    ✓ payment_intent.failed
    ✓ charge.refunded

Required Stripe Capabilities

CapabilityPurpose
card_paymentsAccept card payments
transfersPlatform payouts (if applicable)
off_sessionCharge without customer present (SPT)

PayPal Setup

Connect PayPal as an alternative payment method:

bash
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
# Connect PayPal account
$ hyperfold pay configure paypal
 
> [OAuth] Opening PayPal authorization...
> [Verify] Validating merchant account...
 
✓ PayPal connected!
 
  Merchant ID:   MERCHANT_XYZ
  Business:      Acme Sports Inc.
  Environment:   production
 
# Configure with client credentials
$ hyperfold pay configure paypal \
  --client-id="xxx" \
  --client-secret="yyy"
 
> [Validate] Verifying credentials...
> [Store] Saving to Secret Manager...
✓ PayPal configured

Payment Configuration

Configure payment routing and policies:

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
53
54
55
56
57
58
59
# View all payment configuration
$ hyperfold pay status
 
PAYMENT PROVIDERS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
STRIPE                    ✓ Connected
  Account:                acct_abc123
  Mode:                   live
  SPT Enabled:            yes
  Webhook Status:         healthy
 
PAYPAL                    ✓ Connected
  Merchant ID:            MERCHANT_XYZ
  Environment:            production
 
APPLE PAY                 ○ Not configured
GOOGLE PAY                ○ Not configured
 
# Configure payment policy
$ cat > payment-policy.yaml << 'EOF'
default_provider: stripe
 
providers:
  stripe:
    enabled: true
    spt_enabled: true
    currencies: [USD, EUR, GBP]
 
  paypal:
    enabled: true
    currencies: [USD, EUR]
 
rules:
  # Route high-value transactions to Stripe
  - condition: "amount > 500"
    provider: stripe
    reason: "Lower fees for high value"
 
  # Route recurring to PayPal if customer prefers
  - condition: "customer.preferred_provider == 'paypal'"
    provider: paypal
 
spt_settings:
  default_expiry: 24h
  max_amount: 1000.00
  require_confirmation_above: 100.00
 
fraud_prevention:
  enabled: true
  block_high_risk: true
  review_threshold: 0.7
EOF
 
$ hyperfold pay configure --policy=./payment-policy.yaml
 
> [Validate] Checking policy syntax... OK
> [Apply] Updating payment configuration...
✓ Payment policy applied

Testing Payments

Verify payment integration before going live:

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
# Test payment flow with test credentials
$ hyperfold pay test --provider=stripe
 
> [Test] Creating test PaymentIntent...
> [Test] Simulating successful charge...
> [Test] Verifying webhook delivery...
 
✓ Stripe payment test passed
 
  PaymentIntent: pi_test_xyz
  Amount: $10.00 USD
  Status: succeeded
  Webhook: delivered (142ms)
 
# Test SPT flow
$ hyperfold pay test-spt
 
> [Test] Creating test SPT...
> [Test] Simulating agent purchase...
> [Test] Processing payment...
> [Test] Verifying completion...
 
✓ SPT flow test passed
 
  Token: spt_test_abc123
  Charge: $50.00 USD
  Customer: test_customer
  Agent: test_buyer_agent
 
# Simulate payment scenarios
$ hyperfold pay simulate --scenario=declined
 
> [Sim] Simulating declined card...
> [Verify] Agent handled decline correctly
✓ Decline handling verified
 
$ hyperfold pay simulate --scenario=insufficient_funds
$ hyperfold pay simulate --scenario=expired_card
$ hyperfold pay simulate --scenario=fraud_suspected
Always test in sandbox/test mode before enabling live payments. Use --env=development for test transactions.
Learn about payment delegation with payment tokenization.