End-User Custodial Wallet + On-Ramp Checkout

Detailed implementation example of custodial wallets with on-ramp checkout for a digital media platform

Scenario: Digital Media Platform

Business Context

A digital media platform wants to enable users to purchase premium content using cryptocurrency while maintaining a simple user experience similar to traditional payment methods.

Requirements

Users should have wallets created automatically upon registration
Seamless funding through credit card to USDC conversion
Real-time balance display for purchasing decisions
One-click content purchases using wallet balance

Implementation Example

1. User Registration & Wallet Creation

// When user completes registration
const handleUserRegistration = async (userData) => {
  // Create platform user account
  const user = await createPlatformUser(userData);
  
  // Automatically create embedded crypto account
  const customer = await createCustomer({
    externalCustomerId: user.id,
    email: user.email,
    metadata: {
      platformUserId: user.id,
      registrationDate: new Date().toISOString(),
      accountType: 'premium_user'
    }
  });
  
  // Link customer ID to user profile
  await updateUserProfile(user.id, {
    embeddedAccountId: customer.id
  });
  
  return { user, customer };
};

2. Wallet Funding Flow

// When user wants to add funds
const initiateWalletFunding = async (userId, amount) => {
  const user = await getUserProfile(userId);
  
  // Create checkout session
  const checkoutUrl = await createHostedCheckout({
    customerId: user.embeddedAccountId,
    amount: amount,
    currency: 'USD',
    targetCurrency: 'USDC',
    successUrl: `${platformUrl}/wallet/success`,
    cancelUrl: `${platformUrl}/wallet/cancel`
  });
  
  return checkoutUrl;
};

3. Real-time Balance Integration

// Display user's USDC balance in platform UI
const getUserWalletBalance = async (userId) => {
  const user = await getUserProfile(userId);
  
  const balance = await getCustomerBalance(user.embeddedAccountId);
  
  return {
    amount: balance.amount,
    currency: balance.currency,
    formattedAmount: formatCurrency(balance.amount, 'USDC')
  };
};
 
// Real-time balance updates via webhooks
const handleBalanceUpdate = async (webhookEvent) => {
  if (webhookEvent.type === 'customer.balance.updated') {
    const customerId = webhookEvent.data.customerId;
    const user = await getUserByEmbeddedAccountId(customerId);
    
    // Push real-time update to user's browser
    await sendRealtimeUpdate(user.id, 'balance_updated', {
      newBalance: webhookEvent.data.balance
    });
  }
};

4. Content Purchase Implementation

// Purchase premium content using wallet balance
const purchaseContent = async (userId, contentId) => {
  const user = await getUserProfile(userId);
  const content = await getContent(contentId);
  
  // Check wallet balance
  const balance = await getCustomerBalance(user.embeddedAccountId);
  
  if (balance.amount < content.price) {
    throw new Error('Insufficient wallet balance');
  }
  
  // Create internal transfer to merchant account
  const transfer = await createTransfer({
    fromCustomerId: user.embeddedAccountId,
    toCustomerId: platformMerchantAccountId,
    amount: content.price,
    currency: 'USDC',
    description: `Purchase: ${content.title}`
  });
  
  // Grant content access
  await grantContentAccess(userId, contentId);
  
  return {
    success: true,
    transferId: transfer.id,
    contentAccess: true
  };
};