Skip to main content

​
Wallets

Wallets provide a prepaid balance system where customers can deposit funds and use them for future purchases. Wallets are ideal for customers who prefer prepaying or for businesses that want to offer prepaid packages.

​
Overview

A wallet is a prepaid account balance that:
  • Holds funds in a specific currency
  • Can be topped up by customers or merchants
  • Is automatically used for invoice payments
  • Supports balance thresholds and notifications

​
Creating a Wallet

​
From the Dashboard

  1. Navigate to Customers > [Customer] > Wallet
  2. Click Create Wallet
  3. Select the currency
  4. Optionally add initial balance
  5. Click Create

​
Via API

curl -X POST https://api.alguna.io/wallets \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "acc_123abc",
    "currency": "USD",
    "initialBalance": "1000.00"
  }'
Response: 
{
  "id": "wal_456def",
  "accountId": "acc_123abc",
  "currency": "USD",
  "balance": "1000.00",
  "status": "active",
  "createdAt": "2024-01-15T10:30:00Z"
}

​
Topping Up Wallets

​
Merchant-Initiated Top-Up

Add funds to a customer’s wallet: 
curl -X POST https://api.alguna.io/wallets/wal_456def/top-up \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "amount": "500.00",
    "description": "Manual top-up"
  }'

​
Customer Self-Service Top-Up

Customers can top up through the portal:
  1. Customer logs into portal
  2. Navigates to Wallet
  3. Clicks Add Funds
  4. Enters amount and payment method
  5. Confirms payment
Generate a payment link for wallet top-up: 
curl -X POST https://api.alguna.io/wallets/wal_456def/top-up-link \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "amount": "500.00",
    "expiresIn": "7d"
  }'
Response: 
{
  "url": "https://pay.alguna.io/wallet/top-up/abc123",
  "expiresAt": "2024-01-22T10:30:00Z"
}

​
Automatic Payment

When auto-pay is enabled, wallet balance is automatically used for invoices:

​
Configuration

curl -X PATCH https://api.alguna.io/wallets/wal_456def \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "settings": {
      "autoPayEnabled": true,
      "autoPayPriority": 1
    }
  }'

​
Payment Priority

When multiple payment methods exist:
PriorityDescription
1Used first (recommended for wallets)
2Secondary payment method
3+Fallback options

​
Partial Payment

If wallet balance is insufficient:
  1. Wallet balance is fully applied
  2. Remaining amount charged to backup payment method
  3. If no backup, invoice remains partially paid

​
Balance Management

​
Checking Balance

curl https://api.alguna.io/wallets/wal_456def \
  -H "Authorization: Bearer YOUR_API_KEY"
Response: 
{
  "id": "wal_456def",
  "balance": "750.00",
  "pendingCharges": "100.00",
  "availableBalance": "650.00",
  "currency": "USD"
}

​
Balance Types

FieldDescription
balanceTotal wallet balance
pendingChargesReserved for pending invoices
availableBalanceAmount available for new charges

​
Low Balance Alerts

Configure notifications when balance falls below a threshold:

​
Dashboard Setup

  1. Go to Customers > [Customer] > Wallet
  2. Click Settings
  3. Enable Low Balance Alert
  4. Set threshold amount
  5. Configure notification channels

​
API Configuration

curl -X PATCH https://api.alguna.io/wallets/wal_456def \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "settings": {
      "lowBalanceThreshold": "100.00",
      "lowBalanceNotification": {
        "enabled": true,
        "channels": ["email", "webhook"]
      }
    }
  }'

​
Auto Top-Up

Enable automatic refills when balance is low: 
curl -X PATCH https://api.alguna.io/wallets/wal_456def \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "settings": {
      "autoTopUp": {
        "enabled": true,
        "threshold": "50.00",
        "amount": "500.00",
        "paymentMethodId": "pm_789"
      }
    }
  }'

​
Auto Top-Up Flow

​
Wallet Transactions

​
Transaction History

curl https://api.alguna.io/wallets/wal_456def/transactions \
  -H "Authorization: Bearer YOUR_API_KEY"
Response: 
{
  "transactions": [
    {
      "id": "wtx_001",
      "type": "credit",
      "amount": "500.00",
      "balanceAfter": "750.00",
      "description": "Top-up via Stripe",
      "reference": {
        "type": "payment",
        "id": "pay_123"
      },
      "createdAt": "2024-01-20T14:30:00Z"
    },
    {
      "id": "wtx_002",
      "type": "debit",
      "amount": "-200.00",
      "balanceAfter": "250.00",
      "description": "Invoice payment",
      "reference": {
        "type": "invoice",
        "id": "inv_456"
      },
      "createdAt": "2024-01-18T10:00:00Z"
    }
  ]
}

​
Transaction Types

TypeDescription
creditFunds added (top-up)
debitFunds deducted (payment)
refundFunds returned
adjustmentManual correction

​
Refunds to Wallet

When refunding an invoice paid via wallet:

​
Automatic Refund

If the original payment was from wallet, refund goes back to wallet: 
curl -X POST https://api.alguna.io/refunds \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "invoiceId": "inv_456",
    "amount": "100.00",
    "destination": "wallet"
  }'

​
Manual Refund Destination

Choose where to send the refund: 
curl -X POST https://api.alguna.io/refunds \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "invoiceId": "inv_456",
    "amount": "100.00",
    "destination": "original_payment_method"
  }'

​
Webhooks

EventDescription
wallet.createdNew wallet created
wallet.topped_upFunds added to wallet
wallet.balance_lowBalance below threshold
wallet.payment_madePayment deducted from wallet
wallet.auto_top_up_failedAuto top-up charge failed

​
Example Webhook

{
  "type": "wallet.balance_low",
  "timestamp": "2024-01-20T10:00:00Z",
  "data": {
    "walletId": "wal_456def",
    "accountId": "acc_123abc",
    "balance": "45.00",
    "threshold": "50.00",
    "currency": "USD"
  }
}

​
Multi-Currency Wallets

Customers can have multiple wallets in different currencies: 
# Create USD wallet
curl -X POST https://api.alguna.io/wallets \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"accountId": "acc_123", "currency": "USD"}'

# Create EUR wallet
curl -X POST https://api.alguna.io/wallets \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"accountId": "acc_123", "currency": "EUR"}'

​
Currency Matching

Invoices are paid from the wallet matching the invoice currency. A USD invoice uses the USD wallet, not EUR.

​
Closing a Wallet

To close a wallet and refund remaining balance: 
curl -X POST https://api.alguna.io/wallets/wal_456def/close \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "refundTo": "original_payment_method",
    "reason": "Account closure"
  }'
Closing a wallet is irreversible. Ensure all pending charges are resolved first.

​
Best Practices

Enable Auto Top-Up

Prevent payment failures by enabling automatic refills.

Set Appropriate Thresholds

Balance thresholds should cover at least one billing cycle.

Clear Communication

Notify customers about wallet balance and upcoming charges.

Offer Incentives

Provide discounts for prepaid top-ups to encourage adoption.

​
Next Steps

Credits Overview

Learn about the credit system.

Payments

Understand payment processing.