Guides
Building a Credit Wallet
Building an AI tool or consumption-based platform requires keeping track of virtual credits. Here's the complete recipe for a killer flow:
Phase 1: The "Welcome Wagon" (New Users)#
When a user registers, give them a small bucket of free credits to try your product.
typescript
// Inside your registration logic
await settle.users.sync({ externalUserId: user.id, email: user.email })
await settle.wallet.credit(user.id, {
amount: 20,
description: 'Welcome free trial credits!'
})Phase 2: The "Gatekeeper" (Guarding Features)#
Deduct credits before executing the high-cost API (like Midjourney or GPT4).
typescript
try {
await settle.wallet.debit(userId, { amount: 5, description: 'Generation cost' })
// If it succeeds, execute the AI code!
return await executeAiTask()
} catch (err) {
if (err instanceof InsufficientCreditsError) {
return { error: 'TOPUP_REQUIRED', message: 'Zero credits remaining!' }
}
}Phase 3: The "Refill" (Customizable Dashboard Packages)#
Instead of hardcoding price points inside your code, you should manage and customize Credit Packages directly from your SettleSettle Dashboard (under the *Billing Config* tab).
This gives you instant control to tweak pricing, add promotional tiers, or adjust credit counts without deploying a single line of code!
1. Configure Packages in Your Dashboard#
Create tiers like:
- Starter Pack: 500 Credits for ₦1,500.00
- Pro Growth: 2,500 Credits for ₦5,000.00
- Enterprise Lift: 10,000 Credits for ₦15,000.00
2. Render Dynamic Refills & Open Checkout#
Hydrate your pricing cards instantly using the SDK Bootstrap payload:
typescript
// 1. Grab your dynamic packages configured in the dashboard
const { availablePackages } = await settle.billing.bootstrap(userId)
// 2. Display the grid to the user, and when they click 'Buy':
async function onPurchaseClick(selectedPkg) {
const { checkoutUrl } = await settle.payments.initialize({
endUserId: userId,
amountKobo: selectedPkg.priceKobo,
email: user.email,
metadata: {
packageId: selectedPkg.id,
creditedAmount: selectedPkg.credits
}
})
// Redirect the user to the secure checkout session!
window.location.href = checkoutUrl
}When the payment clears, SettleSettle automatically fires a webhook payload to your API. Catch the
charge.success event, parse your metadata.creditedAmount, and execute settle.wallet.credit() to instantly restore the user's ledger balance!