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:
# 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
| Capability | Purpose |
|---|---|
card_payments | Accept card payments |
transfers | Platform payouts (if applicable) |
off_session | Charge without customer present (SPT) |
PayPal Setup
Connect PayPal as an alternative payment method:
# 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:
# 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:
# 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.