Overview The WalletsClient provides methods for managing customer wallet balances. It supports granting credits (bonuses, top-ups) and revoking them (refunds, penalties).
Methods getBalance() Retrieve a customer’s balance for a specific currency.
const balance = await revstack . wallets . getBalance ( customerId , currency );
The customer whose balance to query. Example: "usr_abc123"
ISO 4217 currency code. Example: "USD", "EUR", "GBP"
Example: const { amount , currency } = await revstack . wallets . getBalance ( "usr_abc123" , "USD" ); console . log ( `Balance: ${ amount } ${ currency } ` );
listBalances() List all balances across all currencies for a customer.
const balances = await revstack . wallets . listBalances ( customerId );
The customer whose balances to list. Example: "usr_abc123"
Array of balance responses (one per currency).
Example: const balances = await revstack . wallets . listBalances ( "usr_abc123" ); for ( const balance of balances ) { console . log ( ` ${ balance . currency } : ${ balance . amount } ` ); }
grantBalance() Grant (add) credit to a customer’s wallet.
const balance = await revstack . wallets . grantBalance ( params );
params
GrantBalanceParams
required
Grant parameters. The customer to grant balance to.
Amount to grant (positive number). Example: 10.00
Optional description for the transaction. Example: "Welcome bonus", "Referral credit"
The updated balance after the grant.
Example: // Grant a welcome bonus const balance = await revstack . wallets . grantBalance ({ customerId: "usr_abc123" , currency: "USD" , amount: 10.00 , description: "Welcome bonus" , }); console . log ( `New balance: ${ balance . amount } ` );
revokeBalance() Revoke (deduct) credit from a customer’s wallet. Used for manual deductions, penalties, or credit refunds.
const balance = await revstack . wallets . revokeBalance ( params );
params
RevokeBalanceParams
required
Revoke parameters. The customer to deduct balance from.
Amount to deduct (positive number).
Audit reason for the deduction. Example: "refund", "penalty", "adjustment"
The updated balance after the deduction.
Example: // Deduct credits for a refund const balance = await revstack . wallets . revokeBalance ({ customerId: "usr_abc123" , currency: "USD" , amount: 5.00 , reason: "refund" , }); console . log ( `Remaining balance: ${ balance . amount } ` );
Common Use Cases Welcome Bonus // Grant credits to new customers async function grantWelcomeBonus ( customerId : string ) { await revstack . wallets . grantBalance ({ customerId , currency: "USD" , amount: 10.00 , description: "Welcome bonus - $10 credit" , }); }
Referral Program // Grant credits for successful referrals async function grantReferralCredit ( referrerId : string , referredId : string ) { // Credit the referrer await revstack . wallets . grantBalance ({ customerId: referrerId , currency: "USD" , amount: 15.00 , description: "Referral bonus" , }); // Credit the referred user await revstack . wallets . grantBalance ({ customerId: referredId , currency: "USD" , amount: 10.00 , description: "Referral welcome credit" , }); }
Manual Top-Up // Allow customers to purchase credits async function purchaseCredits ( customerId : string , amount : number , paymentIntentId : string ) { // After successful payment processing await revstack . wallets . grantBalance ({ customerId , currency: "USD" , amount , description: `Credit purchase ( ${ paymentIntentId } )` , }); }
Credit Refunds // Process credit refunds async function refundCredits ( customerId : string , amount : number , orderId : string ) { await revstack . wallets . revokeBalance ({ customerId , currency: "USD" , amount , reason: `Refund for order ${ orderId } ` , }); }
Display Balance in UI // Show customer's available credits async function getCustomerCredits ( customerId : string ) { const balances = await revstack . wallets . listBalances ( customerId ); return balances . map ( b => ({ currency: b . currency , amount: b . amount , formatted: ` ${ b . currency } ${ b . amount . toFixed ( 2 ) } ` , })); }
Credit Expiration // Revoke expired credits async function expireOldCredits ( customerId : string , amount : number ) { await revstack . wallets . revokeBalance ({ customerId , currency: "USD" , amount , reason: "credit_expiration" , }); }
