Customer Wallets
Store funds for your customers. Wallets let customers add money once and pay faster without entering card details each time.
What Are Customer Wallets?
A wallet is a stored balance for your customer. They add money to their wallet, then use it to pay for things on your platform.
Good for:
- Faster checkout (no entering card details)
- Prepaid accounts or credits
- Gift cards and store credit
- Subscription credits
- Refunds as store credit
Create a Wallet
Create a wallet for each customer who needs one:
POST /v1/wallets
{
"customer_id": "cus_abc123",
"currency": "USD",
"name": "Store Credit"
}
// Response
{
"id": "wal_xyz789",
"customer_id": "cus_abc123",
"currency": "USD",
"balance": 0,
"name": "Store Credit",
"created_at": "2024-01-15T10:00:00Z"
}Add Funds to a Wallet
Add money to a customer's wallet. They can pay with a card, or you can add credit directly.
Customer pays with card
// Customer wants to add $50 to their wallet
POST /v1/wallets/wal_xyz789/top_up
{
"amount": 5000,
"payment_method": "pm_card_abc"
}
// Card is charged, wallet balance increasesAdd credit (no charge)
// Give customer $20 credit (promotion, refund, etc.)
POST /v1/wallets/wal_xyz789/credit
{
"amount": 2000,
"description": "Welcome bonus"
}Pay with Wallet Balance
When a customer wants to pay, deduct from their wallet:
// Charge $15 from wallet for a purchase
POST /v1/wallets/wal_xyz789/debit
{
"amount": 1500,
"description": "Order #12345"
}
// Response shows new balance
{
"transaction_id": "wtx_abc123",
"amount": 1500,
"new_balance": 3500,
"description": "Order #12345"
}Tip
Check the balance first! If the wallet doesn't have enough, you can split the payment between wallet and card.
Check Wallet Balance
GET /v1/wallets/wal_xyz789
{
"id": "wal_xyz789",
"customer_id": "cus_abc123",
"currency": "USD",
"balance": 3500,
"name": "Store Credit"
}Balance is in cents. So 3500 = $35.00
Transaction History
See all transactions for a wallet:
GET /v1/wallets/wal_xyz789/transactions
{
"data": [
{
"id": "wtx_001",
"type": "credit",
"amount": 5000,
"description": "Top-up via card",
"created_at": "2024-01-15T10:00:00Z"
},
{
"id": "wtx_002",
"type": "debit",
"amount": 1500,
"description": "Order #12345",
"created_at": "2024-01-16T14:30:00Z"
}
]
}Refund to Wallet
Instead of refunding to a card, add the money to the customer's wallet as store credit:
// Refund order as store credit
POST /v1/wallets/wal_xyz789/credit
{
"amount": 2500,
"description": "Refund for order #12345",
"metadata": {
"original_payment": "pi_xyz",
"refund_reason": "Customer request"
}
}Benefits of wallet refunds:
- Instant - no waiting for bank processing
- Customer is more likely to spend it with you again
- No card processing fees
Split Payments
If the wallet doesn't have enough, charge the rest to a card:
// Order is $50, wallet has $20
// Step 1: Debit wallet
POST /v1/wallets/wal_xyz789/debit
{
"amount": 2000,
"description": "Order #12346 (partial)"
}
// Step 2: Charge card for remaining $30
POST /v1/payments
{
"amount": 3000,
"currency": "USD",
"payment_method": "pm_card_abc",
"description": "Order #12346 (remaining)"
}Best Practices
- Always check balance first - Don't try to debit more than what's available.
- Show balance clearly - Display the customer's wallet balance in your app so they know what they have.
- Keep transaction records - Log all wallet activity with clear descriptions.
- Handle expiry - If credits expire, notify customers before they lose value.
- Offer bonuses - "Add $100, get $110" encourages prepayment.