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

# 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

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:

# 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..."
  }
}

SPT Security

Feature	Description
Time-limited	Tokens expire after configured lifetime
Amount-capped	Cannot exceed pre-authorized maximum
Single-use	Token invalidated after successful charge
Cryptographically signed	Tamper-proof with merchant verification

Agent Payments

# 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) {
  const spt = await this.tools.payments.validateSPT(event.payment.token);
  if (!spt.valid) {
    return { status: "payment_failed", error: "Invalid payment token" };
  }
  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

# Stripe webhook events handled automatically:
# 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

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.

Search Documentation