Payment Methods - ChaosChain Documentation

Overview

ChaosChain SDK supports 5 W3C-compliant payment methods for comprehensive payment processing. From traditional cards to crypto payments, handle all payment types with a unified API.

Live Crypto Payments

A2A-x402 with real USDC transfers on Base Sepolia

Traditional Methods

Cards, Google Pay, Apple Pay, PayPal with real API integrations

Supported Payment Methods

✅ LIVE & WORKING (Out-of-the-Box)

Method	W3C Identifier	Status	Settlement
A2A-x402 Crypto	`https://a2a.org/x402`	✅ LIVE	Real USDC Transfers on Base Sepolia

🔧 REAL API INTEGRATIONS (Add Your Credentials)

Method	W3C Identifier	Status	What You Need
Basic Cards	`basic-card`	✅ REAL Stripe API	Add `STRIPE_SECRET_KEY`
PayPal	`https://paypal.com`	✅ REAL PayPal API	Add `PAYPAL_CLIENT_ID` + `PAYPAL_CLIENT_SECRET`
Google Pay	`https://google.com/pay`	✅ REAL Token Validation	Add `GOOGLE_PAY_MERCHANT_ID`
Apple Pay	`https://apple.com/apple-pay`	✅ REAL Token Validation	Add `APPLE_PAY_MERCHANT_ID`

A2A-x402 Crypto Payments

The A2A-x402 protocol enables real USDC transfers between agents with automatic protocol fees.

Features

✅ Real USDC Transfers on Base Sepolia
✅ Automatic Protocol Fees (2.5% to ChaosChain treasury)
✅ Multi-Network Support (Base, Ethereum, Optimism Sepolia)
✅ Instant Settlement with transaction proofs

Usage Example

# Create A2A-x402 payment request
payment_request = sdk.create_x402_payment_request(
    cart_id="service_001",
    total_amount=10.0,
    currency="USDC",
    items=[
        {"name": "AI Analysis Service", "price": 8.0},
        {"name": "Data Processing", "price": 2.0}
    ],
    settlement_address=sdk.wallet_address  # Optional, defaults to agent wallet
)

print(f"💰 Payment Request ID: {payment_request['id']}")
print(f"🏦 Settlement Address: {payment_request['settlement_address']}")

Payment Flow

Create Request

Agent creates A2A-x402 payment request with items and total amount

Generate Settlement

SDK generates settlement address and calculates protocol fees

Execute Transfer

USDC is transferred from payer to settlement address

Fee Collection

Protocol fee (2.5%) is automatically sent to ChaosChain treasury

Traditional Payment Methods

All traditional payment methods use real API integrations with production payment processors.

Basic Card Payments (Stripe)

Process credit and debit cards through Stripe’s API:

import os

# Add your Stripe credentials
os.environ['STRIPE_SECRET_KEY'] = 'sk_live_your_stripe_secret_key'
os.environ['STRIPE_PUBLISHABLE_KEY'] = 'pk_live_your_stripe_publishable_key'

Google Pay Integration

Process Google Pay payments with token validation:

import os

# Add your Google Pay merchant ID
os.environ['GOOGLE_PAY_MERCHANT_ID'] = 'merchant.your-domain.com'
os.environ['GOOGLE_PAY_ENVIRONMENT'] = 'PRODUCTION'  # or 'TEST'

Apple Pay Integration

Process Apple Pay payments with certificate validation:

import os

# Add your Apple Pay credentials
os.environ['APPLE_PAY_MERCHANT_ID'] = 'merchant.your-domain.com'
os.environ['APPLE_PAY_CERTIFICATE_PATH'] = '/path/to/apple-pay-cert.pem'

PayPal Integration

Process PayPal payments through their REST API:

import os

# Add your PayPal credentials
os.environ['PAYPAL_CLIENT_ID'] = 'your_paypal_client_id'
os.environ['PAYPAL_CLIENT_SECRET'] = 'your_paypal_client_secret'
os.environ['PAYPAL_ENVIRONMENT'] = 'live'  # or 'sandbox'

Multi-Payment Example

Handle multiple payment methods in a single application:

multi_payment_agent.py

import os
from chaoschain_sdk import ChaosChainAgentSDK

# Setup environment variables for all payment methods
os.environ.update({
    'BASE_SEPOLIA_RPC_URL': 'https://sepolia.base.org',
    'STRIPE_SECRET_KEY': 'sk_live_your_stripe_key',
    'GOOGLE_PAY_MERCHANT_ID': 'merchant.your-domain.com',
    'APPLE_PAY_MERCHANT_ID': 'merchant.your-domain.com',
    'PAYPAL_CLIENT_ID': 'your_paypal_client_id',
    'PAYPAL_CLIENT_SECRET': 'your_paypal_client_secret'
})

# Initialize SDK with all payment methods
sdk = ChaosChainAgentSDK(
    agent_name="PaymentAgent",
    agent_domain="payments.example.com",
    agent_role="server",
    network="base-sepolia",
    enable_payments=True
)

# Get all supported payment methods
methods = sdk.get_supported_payment_methods()
print(f"💳 Supported Methods: {methods}")

# Process different payment types based on user preference
def process_payment(method: str, amount: float, payment_data: dict):
    if method == "https://a2a.org/x402":
        # Crypto payment
        payment_request = sdk.create_x402_payment_request(
            cart_id=f"order_{int(time.time())}",
            total_amount=amount,
            currency="USDC",
            items=[{"name": "Service", "price": amount}]
        )
        return sdk.execute_x402_crypto_payment(
            payment_request=payment_request,
            payer_agent="ClientAgent"
        )
    else:
        # Traditional payment
        return sdk.execute_traditional_payment(
            payment_method=method,
            amount=amount,
            currency="USD",
            payment_data=payment_data
        )

# Example usage
crypto_result = process_payment(
    "https://a2a.org/x402", 
    10.0, 
    {}
)

card_result = process_payment(
    "basic-card",
    25.99,
    {
        "cardNumber": "4111111111111111",
        "cardType": "visa",
        "expiryMonth": "12",
        "expiryYear": "2025",
        "cvv": "123"
    }
)

print(f"🚀 Crypto: {crypto_result['status']}")
print(f"💳 Card: {card_result['status']}")

Payment Configuration

Environment Variables

Set up your payment processor credentials:

.env

# Network Configuration
BASE_SEPOLIA_RPC_URL=https://sepolia.base.org

# Stripe (for basic-card payments)
STRIPE_SECRET_KEY=sk_live_your_stripe_secret_key
STRIPE_PUBLISHABLE_KEY=pk_live_your_stripe_publishable_key

# Google Pay
GOOGLE_PAY_MERCHANT_ID=merchant.your-domain.com
GOOGLE_PAY_ENVIRONMENT=PRODUCTION

# Apple Pay
APPLE_PAY_MERCHANT_ID=merchant.your-domain.com
APPLE_PAY_CERTIFICATE_PATH=/path/to/apple-pay-cert.pem

# PayPal
PAYPAL_CLIENT_ID=your_paypal_client_id
PAYPAL_CLIENT_SECRET=your_paypal_client_secret
PAYPAL_ENVIRONMENT=live

Demo Mode Fallback

If credentials aren’t provided, the SDK automatically falls back to demo mode:

# Without credentials - uses demo mode
sdk = ChaosChainAgentSDK(
    agent_name="DemoAgent",
    agent_domain="demo.example.com",
    agent_role="server"
)

# This will work in demo mode
demo_result = sdk.execute_traditional_payment(
    payment_method="basic-card",
    amount=10.0,
    currency="USD",
    payment_data={"demo": True}
)

print(f"🎭 Demo Payment: {demo_result['status']}")
# Output: Demo Payment: demo_success

Protocol Fees

ChaosChain automatically collects protocol fees on crypto payments:

Fee Rate: 2.5% of transaction amount
Collection: Automatic on A2A-x402 payments
Destination: ChaosChain treasury address
Traditional Payments: No protocol fees (handled by payment processors)

Fee Calculation Example

# For a $10 USDC payment:
total_amount = 10.0
protocol_fee = total_amount * 0.025  # 2.5%
agent_receives = total_amount - protocol_fee

print(f"💰 Total: ${total_amount} USDC")
print(f"🏛️ Protocol Fee: ${protocol_fee} USDC")
print(f"👤 Agent Receives: ${agent_receives} USDC")

# Output:
# 💰 Total: $10.0 USDC
# 🏛️ Protocol Fee: $0.25 USDC  
# 👤 Agent Receives: $9.75 USDC

Error Handling

Handle payment errors gracefully:

from chaoschain_sdk.exceptions import PaymentError

try:
    result = sdk.execute_traditional_payment(
        payment_method="basic-card",
        amount=100.0,
        currency="USD",
        payment_data={"invalid": "data"}
    )
except PaymentError as e:
    print(f"💥 Payment failed: {e}")
    # Handle specific error cases
    if "insufficient funds" in str(e).lower():
        print("💳 Card declined - insufficient funds")
    elif "invalid card" in str(e).lower():
        print("🚫 Invalid card details")
    else:
        print("⚠️ General payment error")

Best Practices

Security

Never log payment credentials or sensitive data
Use HTTPS for all payment communications
Validate payment data before processing
Store credentials in environment variables, not code

Error Handling

Implement retries for network failures
Provide clear feedback to users on payment status
Log errors for debugging (without sensitive data)
Handle timeouts gracefully

User Experience

Show supported methods to users
Provide payment status updates
Handle demo mode transparently
Offer multiple options for payment flexibility

Next Steps

Payment Integration Guide

Step-by-step setup for production payment processors

SDK Configuration

Complete configuration options and environment variables

SDK Documentation

​Overview

Live Crypto Payments

Traditional Methods

​Supported Payment Methods

​✅ LIVE & WORKING (Out-of-the-Box)

​🔧 REAL API INTEGRATIONS (Add Your Credentials)

​A2A-x402 Crypto Payments

​Features

​Usage Example

​Payment Flow

​Traditional Payment Methods

​Basic Card Payments (Stripe)

​Google Pay Integration

​Apple Pay Integration

​PayPal Integration

​Multi-Payment Example

​Payment Configuration

​Environment Variables

​Demo Mode Fallback

​Protocol Fees

​Fee Calculation Example

​Error Handling

​Best Practices

​Next Steps

Payment Integration Guide

SDK Configuration

Overview

Supported Payment Methods

✅ LIVE & WORKING (Out-of-the-Box)

🔧 REAL API INTEGRATIONS (Add Your Credentials)

A2A-x402 Crypto Payments

Features

Usage Example

Payment Flow

Traditional Payment Methods

Basic Card Payments (Stripe)

Google Pay Integration

Apple Pay Integration

PayPal Integration

Multi-Payment Example

Payment Configuration

Environment Variables

Demo Mode Fallback

Protocol Fees

Fee Calculation Example

Error Handling

Best Practices

Next Steps