Skip to main content

​
Overview

Wallets provide a prepaid credit system for customers. Credits can be granted manually or automatically, and are consumed during invoice finalization to reduce the amount due.

​
Wallet lifecycle

  ACTIVE → TERMINATED
Active wallets accumulate and consume credits. Terminated wallets cannot process further transactions. Wallets can optionally expire at a set date.

​
Create a wallet

curl -X POST /v1/wallets \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "customer-uuid",
    "name": "Main Credits",
    "code": "main",
    "currency": "USD",
    "rate_amount": "1.0",
    "priority": 1,
    "initial_granted_credits": "100.00",
    "expiration_at": "2025-12-31T23:59:59Z"
  }'

​
Key fields

FieldDescription
rate_amountConversion rate: balance_cents = credits × rate_amount × 100. Default: 1.0 (1 credit = $1)
priorityConsumption order (1–50, lower = consumed first)
initial_granted_creditsCredits to grant immediately on creation
expiration_atOptional expiration date
codeOptional unique code per customer

​
Top up credits

curl -X POST /v1/wallets/{wallet_id}/top_up \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "credits": "50.00",
    "source": "manual"
  }'

​
Sources

SourceDescription
manualManually granted by admin
intervalAutomatically granted on a recurring schedule
thresholdGranted when usage crosses a threshold
Each top-up creates an inbound wallet transaction and increases the wallet balance.

​
Credit consumption

When an invoice is finalized, wallet credits are consumed automatically:
  1. Active, non-expired wallets are sorted by priority (ascending), then by creation date
  2. For each wallet, the consumable amount is min(wallet.balance, remaining_invoice_amount)
  3. An outbound wallet transaction is created
  4. An InvoiceSettlement record links the consumption to the invoice
  5. The process continues until the invoice is fully covered or no wallets remain

​
Example

A customer has two wallets:
WalletPriorityBalance
Promo Credits1$25.00
Main Credits2$100.00
For a $40.00 invoice:
  1. Promo Credits consumed: 25.00(balance→25.00 (balance → 0.00)
  2. Main Credits consumed: 15.00(balance→15.00 (balance → 85.00)
  3. Invoice prepaid_credit_amount: $40.00

​
Terminate a wallet

DELETE /v1/wallets/{wallet_id}
Sets the wallet status to terminated. Remaining balance is forfeited.

​
Expiration

Wallets with an expiration_at date are automatically terminated by a background task when the expiration date passes. The check_expired_wallets task handles this.

​
Wallet transactions

List all transactions for a wallet: 
curl /v1/wallets/{wallet_id}/transactions \
  -H "Authorization: Bearer $API_KEY"

​
Transaction types

TypeDirectionDescription
inboundCreditTop-up or grant
outboundDebitConsumption against invoice

​
Transaction statuses

StatusDescription
grantedCredits granted
purchasedCredits purchased
voidedTransaction voided
invoicedLinked to an invoice

​
API endpoints

MethodPathDescription
POST/v1/walletsCreate a wallet
GET/v1/walletsList wallets
GET/v1/wallets/{id}Get wallet details
PUT/v1/wallets/{id}Update wallet (name, expiration, priority)
DELETE/v1/wallets/{id}Terminate a wallet
POST/v1/wallets/{id}/top_upAdd credits
GET/v1/wallets/{id}/transactionsList transactions