Hyperfold AI

Stripe Integration

Process payments securely with Stripe and Shared Payment Tokens.

Overview

The Stripe integration enables secure payment processing for agent-mediated transactions. Using Shared Payment Tokens (SPT), buyer agents can complete purchases without exposing sensitive payment credentials.

Stripe is the recommended payment provider for Hyperfold due to its comprehensive API and native SPT support.

Setup

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
# Connect Stripe
$ hyperfold integrate add stripe
 
Opening Stripe Connect authorization...
 
✓ Connected to Stripe
  Account:       acct_xxx
  Mode:          live
  Capabilities:  card_payments, transfers
 
# View connection details
$ hyperfold integrate show stripe
 
INTEGRATION: Stripe
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
Account ID:         acct_1234567890
Business:           Acme Sports Inc.
Mode:               live
Status:             active
 
CAPABILITIES
  ✓ Card Payments
  ✓ Bank Transfers
  ✓ Subscriptions
  ✓ Refunds
 
WEBHOOKS
  Endpoint:         https://api.hyperfold.io/webhooks/stripe/xxx
  Events:           payment_intent.*, charge.*, refund.*
  Status:           active
 
METRICS (30 days)
  Transactions:     4,521
  Volume:           $792,450.00
  Success Rate:     98.7%

Prerequisites

  • Stripe account with business verification complete
  • Live mode enabled (sandbox available for testing)
  • API keys with appropriate permissions

Shared Payment Tokens

SPT enables secure agent-to-agent payment without exposing card details:

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
# Configure Shared Payment Tokens
$ hyperfold pay configure stripe \
  --enable-spt \
  --token-lifetime=3600 \
  --max-amount=1000
 
SPT CONFIGURATION
  Provider:         Stripe
  Token Lifetime:   1 hour
  Max Amount:       $1,000.00
  Requires CVV:     For amounts > $100
 
# How SPT works in agent transactions:
 
# 1. Buyer agent generates SPT from saved payment method
# 2. SPT is passed during ACP checkout
# 3. Hyperfold validates and charges via Stripe
# 4. Buyer never exposes full card details
 
POST /acp/checkout/finalize
{
  "checkout_id": "chk_xyz789",
  "payment": {
    "method": "stripe_spt",
    "token": "spt_live_abc123..."  // Shared Payment Token
  }
}
 
# SPT token structure (decoded for reference):
{
  "version": 1,
  "provider": "stripe",
  "customer_id": "cus_xxx",
  "payment_method": "pm_xxx",
  "max_amount": 1000,
  "currency": "USD",
  "expires_at": 1705750800,
  "signature": "..."
}

SPT Security

FeatureDescription
Time-limitedTokens expire after configured lifetime
Amount-cappedCannot exceed pre-authorized maximum
Single-useToken invalidated after successful charge
Cryptographically signedTamper-proof with merchant verification

Agent Payments

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
# Configure agent payment delegation
$ hyperfold pay delegate \
  --agent=sales-negotiator \
  --provider=stripe \
  --max-transaction=500 \
  --daily-limit=10000
 
# Agent processes payment during checkout:
@OnACPEvent("checkout.finalize")
async handleCheckout(event: CheckoutEvent) {
  // Validate SPT token
  const spt = await this.tools.payments.validateSPT(event.payment.token);
 
  if (!spt.valid) {
    return { status: "payment_failed", error: "Invalid payment token" };
  }
 
  // Process payment through Stripe
  const payment = await this.tools.payments.charge({
    provider: "stripe",
    amount: event.total,
    currency: "USD",
    spt_token: event.payment.token,
    metadata: {
      order_id: event.order_id,
      session_id: event.session_id
    }
  });
 
  if (payment.status === "succeeded") {
    await this.createOrder(event, payment);
    return { status: "success", order_id: event.order_id };
  }
 
  return { status: "payment_failed", error: payment.error };
}

Payment Flow

1. Token Generation

Buyer agent generates SPT from user's saved payment method with amount limits and expiration.

2. Token Validation

Seller agent validates SPT signature, expiration, and amount cap before processing.

3. Payment Processing

Hyperfold charges the underlying payment method via Stripe and returns confirmation.

4. Token Invalidation

Used token is invalidated. Any retry requires a new SPT from the buyer.

Webhooks

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
# Stripe webhook events handled automatically:
 
WEBHOOK EVENTS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
payment_intent.succeeded    → Update order status
payment_intent.failed       → Mark order as payment_failed
charge.refunded             → Process refund in order
charge.dispute.created      → Alert + pause agent
charge.dispute.closed       → Resume agent if won
 
# Configure additional webhook handling
$ hyperfold integrate config stripe \
  --webhook-events="customer.subscription.*" \
  --on-event="subscription.canceled:cancel_agent_access"
 
# View webhook delivery logs
$ hyperfold integrate webhook-logs stripe --since=24h
 
WEBHOOK LOGS: Stripe
 
TIMESTAMP            EVENT                      STATUS    LATENCY
Jan 20, 10:15        payment_intent.succeeded   ✓ 200     45ms
Jan 20, 10:14        charge.succeeded           ✓ 200     38ms
Jan 20, 09:45        payment_intent.succeeded   ✓ 200     52ms
Jan 20, 09:30        refund.created             ✓ 200     61ms
Never log or store full SPT tokens in plain text. They contain cryptographic signatures that should remain confidential.
For other payment providers, see PayPal or Checkout.com.