Wallets

A wallet holds prepaid credit for one customer in one currency. When an invoice is created, credit in the customer's wallets is used first (after coupons, add-ons and taxes), and the invoice shows it as Prepaid credits applied. If the invoice is later voided, the credit goes back.

Create a wallet

curl -X POST https://api.pimabill.com/api/wallets \
  -H "Authorization: Bearer sk_live_a1b2c3d4..." \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "cust_abc123",
    "name": "Main wallet",
    "currency": "UGX",
    "rateAmount": 1,
    "paidCredits": 50000,
    "grantedCredits": 5000
  }'

• Paid credits are credit the customer bought; granted credits are free credit you give (a welcome bonus or compensation). Both are spent the same way; they are recorded separately for your accounts.
• rateAmount is what one credit is worth in the wallet's currency (1 credit = 1 UGX above).
• expirationAt (ISO 8601) ends the wallet on that date; remaining credit is voided.

Top up, grant or void

curl -X POST https://api.pimabill.com/api/wallets/transactions \
  -H "Authorization: Bearer sk_live_a1b2c3d4..." \
  -H "Content-Type: application/json" \
  -d '{ "walletId": "wal_123", "paidCredits": 20000 }'

Pass grantedCredits to give free credit, or voidedCredits to remove credit. GET /api/wallets/{id}/transactions lists every movement, and DELETE /api/wallets/{id} terminates a wallet and voids what is left.

Moving money between wallets

Transfers move value between two customers' wallets in the same currency, and a payout can be paid from a wallet with walletId.