> ## Documentation Index
> Fetch the complete documentation index at: https://alguna.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Wallets

> Set up and manage prepaid wallets for your customers

# 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

```bash theme={null}
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:**

```json theme={null}
{
  "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:

```bash theme={null}
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

### Top-Up via Payment Link

Generate a payment link for wallet top-up:

```bash theme={null}
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:**

```json theme={null}
{
  "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

```bash theme={null}
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:

| Priority | Description                          |
| -------- | ------------------------------------ |
| 1        | Used first (recommended for wallets) |
| 2        | Secondary 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

```bash theme={null}
curl https://api.alguna.io/wallets/wal_456def \
  -H "Authorization: Bearer YOUR_API_KEY"
```

**Response:**

```json theme={null}
{
  "id": "wal_456def",
  "balance": "750.00",
  "pendingCharges": "100.00",
  "availableBalance": "650.00",
  "currency": "USD"
}
```

### Balance Types

| Field              | Description                      |
| ------------------ | -------------------------------- |
| `balance`          | Total wallet balance             |
| `pendingCharges`   | Reserved for pending invoices    |
| `availableBalance` | Amount 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

```bash theme={null}
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:

```bash theme={null}
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

```mermaid theme={null}
graph LR
    A[Balance Check] --> B{Below Threshold?}
    B -->|Yes| C[Initiate Top-Up]
    C --> D[Charge Payment Method]
    D --> E{Success?}
    E -->|Yes| F[Credit Wallet]
    E -->|No| G[Send Alert]
    B -->|No| H[No Action]
```

***

## Wallet Transactions

### Transaction History

```bash theme={null}
curl https://api.alguna.io/wallets/wal_456def/transactions \
  -H "Authorization: Bearer YOUR_API_KEY"
```

**Response:**

```json theme={null}
{
  "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

| Type         | Description              |
| ------------ | ------------------------ |
| `credit`     | Funds added (top-up)     |
| `debit`      | Funds deducted (payment) |
| `refund`     | Funds returned           |
| `adjustment` | Manual 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:

```bash theme={null}
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:

```bash theme={null}
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

| Event                       | Description                  |
| --------------------------- | ---------------------------- |
| `wallet.created`            | New wallet created           |
| `wallet.topped_up`          | Funds added to wallet        |
| `wallet.balance_low`        | Balance below threshold      |
| `wallet.payment_made`       | Payment deducted from wallet |
| `wallet.auto_top_up_failed` | Auto top-up charge failed    |

### Example Webhook

```json theme={null}
{
  "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:

```bash theme={null}
# 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:

```bash theme={null}
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"
  }'
```

<Warning>
  Closing a wallet is irreversible. Ensure all pending charges are resolved first.
</Warning>

***

## Best Practices

<CardGroup cols={2}>
  <Card title="Enable Auto Top-Up" icon="repeat">
    Prevent payment failures by enabling automatic refills.
  </Card>

  <Card title="Set Appropriate Thresholds" icon="gauge">
    Balance thresholds should cover at least one billing cycle.
  </Card>

  <Card title="Clear Communication" icon="comments">
    Notify customers about wallet balance and upcoming charges.
  </Card>

  <Card title="Offer Incentives" icon="gift">
    Provide discounts for prepaid top-ups to encourage adoption.
  </Card>
</CardGroup>

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Credits Overview" icon="coins" href="/credits/overview">
    Learn about the credit system.
  </Card>

  <Card title="Payments" icon="credit-card" href="/payments/overview">
    Understand payment processing.
  </Card>
</CardGroup>