Purchase Plans

Learn how users can purchase Payment Plans to access AI services

With the Payments Library it’s easy for users and AI agents to buy Payment Plans. The user only needs to hold sufficient balance in the plan currency (set on plan creation). With Nevermined, Plan creators can set payments currency to any valid ERC-20 or native token.

Payment Plans can also be purchased in fiat (via Stripe). The Stripe Checkout flow requires the use of credit cards and is fully integrated into the Nevermined Web App. Nevermined likes to recommend stablecoin payments. That way, the payment and fetching of credits associated with the Payment Plan can be done in a single step.

Buying a Plan

TypeScript

// Here we are ordering the plan created in the previous steps
const orderResult = await payments.plans.orderPlan(planId)
// OUTPUT: orderResult:
// {
//   txHash: '0x5b95ebaec594b6d87e688faddf85eec3d708e6a06e61864699e5a366af1343f6',
//   success: true
// }

Python

# Here we are ordering the Plan created in the previous steps
order_result = payments.plans.order_plan(plan_id)
# OUTPUT: orderResult:
# { success: True, agreementId: '0xaabbcc' }

Buying Plans with Fiat via Stripe

When the Payment Plan requires a payment in fiat, the payment can be initiated with the libraries, but the final step needs to be done in the Nevermined App. The app will handle the payment in fiat (via Stripe Checkout) and will return the user to the application that initiated the purchase flow.

For fiat payments, the process involves redirecting users to a Stripe Checkout session:

TypeScript

// Get fiat payment configuration
const fiatConfig = await payments.plans.getFiatPriceConfig(planId)

// Order plan with fiat payment
const { sessionId, url } = await payments.plans.orderFiatPlan(planId)

// Redirect user to Stripe checkout
window.location.href = url

// After successful payment, user will be redirected back with the plan active

Python

# Get fiat payment configuration
fiat_config = payments.plans.get_fiat_price_config(plan_id)

# Order plan with fiat payment
fiat_result = payments.plans.order_fiat_plan(plan_id)

# Redirect user to Stripe checkout
print(f'Stripe checkout URL: {fiat_result["url"]}')
# User completes payment on Stripe and returns to your application

Checking the Credit Balance of a Payment Plan

After a user purchases a plan, they can check their balance for that plan. The balance represents the number of credits the user has available to use within the plan.

Time-based plans provide a balance of 1 credit for subscribers. When the plan expires, this balance will be zero.

TypeScript

const balanceResult = await payments.plans.getPlanBalance(planId)
// OUTPUT: balanceResult:
// {
//   planId: '84262690312400469275420649384078993542777341811308941725027729655403981619104',
//   planType: 'credits',
//   holderAddress: '0x8924803472bb453b7c27a3C982A08f7515D7aA72',
//   creditsContract: '0x17FaFabF74312EdaBEB1DB9f0CaAccd44aAFDE39',
//   balance: '100',
//   isSubscriber: true
// }

Python

balance_result = payments.plans.get_plan_balance(plan_id)
# OUTPUT: balanceResult:
# {
#   "planType": "credits",
#   "isSubscriptor": True,
#   "isOwner": False,
#   "balance": 10000000
# }  

Understanding Plan Types and Balances

Credits-Based Plans

Users receive a specific number of credits upon purchase. Each API call consumes credits based on your pricing configuration.

Time-Based Plans

Users receive 1 credit that grants unlimited access for the specified duration. Balance becomes 0 when expired.

Payment Flow Examples

Complete Purchase Flow

1. Discover Plans

   Users browse available payment plans and select one that fits their needs

2. Initiate Purchase

   Call payments.plans.orderPlan() or payments.plans.orderFiatPlan() depending on payment method

3. Complete Payment

   For crypto: transaction is processed on-chain and happens in one transaction. For fiat: user completes Stripe checkout, and the credits will be distributed automatically after the payment.

4. Verify Purchase

   Check balance to confirm the plan was successfully purchased and get the balance. Call payments.plans.getPlanBalance().

5. Access Services

   Use the plan to access AI agents and services. Call payments.x402.getX402AccessToken().

Error Handling

TypeScript

try {
  const orderResult = await payments.plans.orderPlan(planId)
  
  if (orderResult.success) {
    console.log('Plan purchased successfully!')
    console.log('Transaction hash:', orderResult.txHash)
    
    // Check balance to confirm
    const balance = await payments.plans.getPlanBalance(planId)
    console.log('Available credits:', balance.balance)
  }
} catch (error) {
  console.error('Purchase failed:', error.message)
}

Python

try:
    order_result = payments.plans.order_plan(plan_id)
    
    if order_result.get('success'):
        print('Plan purchased successfully!')
        print(f'Agreement ID: {order_result.get("agreementId")}')
        
        # Check balance to confirm
        balance = payments.plans.get_plan_balance(plan_id)
        print(f'Available credits: {balance.get("balance")}')
        
except Exception as error:
    print(f'Purchase failed: {error}')
    

Best Practices for Plan Purchasing

User Experience

• Always show clear pricing and what users get for their purchase
• Create different plans for crypto and fiat payments if you want to support both
• Show plan benefits and limitations clearly

Error Handling

• Handle network failures gracefully with retry mechanisms
• Provide clear error messages for common issues
• Allow users to check their balance before making additional purchases
• Implement transaction status checking for pending purchases

Security

• Never store private keys or sensitive wallet information
• Validate plan purchases on the backend before granting access
• Implement rate limiting to prevent abuse
• Log purchase events for audit trails

Next Steps

After users purchase plans, they can:

Query AI Agents

Learn how to access AI services with purchased plans

Handle Requests

Learn how to process requests and manage responses