Credit Wallets
Credit Wallets
Issue and manage prepaid credit balances for your customers.
Overview
Xtopay Credit Wallets let you issue prepaid balances to your customers — inside your platform. Customers top up their wallet once and spend from it across your product without re-entering payment details for every transaction.
Common use cases:
- SaaS platforms that sell compute credits or API credits
- Marketplaces that hold buyer funds before a seller fulfils
- Delivery apps that let riders or drivers hold earnings before payout
- Loyalty programmes where purchases earn redeemable credit
- Prepaid access to services (SMS, data, AI tokens)
How it works
Customer tops up wallet ──→ Wallet balance increases
↓
Your app deducts from wallet ──→ Balance decreases
↓
Xtopay records the transaction
↓
Webhook fires on every balance changeEach customer gets one wallet per currency. Balances never expire unless you configure an expiry policy.
Wallet object
{
"id": "wal_a1b2c3",
"customer_id": "cus_abc123",
"currency": "GHS",
"balance": 15000,
"balance_formatted": "GH₵150.00",
"status": "active",
"created_at": "2026-01-15T09:00:00Z"
}Quick start
// 1. Create a wallet for a customer
const wallet = await xtopay.wallets.create({
customer_id: "cus_abc123",
currency: "GHS",
});
// 2. Customer tops up (generates a payment for them to complete)
const topup = await xtopay.wallets.createTopup({
wallet_id: wallet.id,
amount: 10000, // GHS 100.00
redirect_url: "https://yourapp.com/wallet",
});
redirect(topup.checkout_url);
// 3. Deduct from wallet when customer uses your product
const debit = await xtopay.wallets.debit({
wallet_id: wallet.id,
amount: 500, // GHS 5.00
description: "10 SMS messages sent",
reference: "sms_batch_xyz",
});