Wallets

Set up and manage prepaid wallets for your customers

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 balance that:

• Holds funds in a single currency
• Is credited and debited through the API, with every movement recorded on the wallet ledger
• Can pay an invoice in the same currency
• Can be restricted to a set of products

A wallet belongs to one customer, and a customer can hold several wallets. Wallet ids are prefixed wlt_ and customer ids cust_.

Wallets and credits are separate systems. A wallet holds money the customer has paid in; a credit grant is a balance you allocate. See Credit Grants.

---

Creating a Wallet

From the Dashboard

1. Navigate to Customers → [Customer] → Profile
2. In the Wallets card, add a wallet
3. Give the wallet a name and select the currency
4. Optionally restrict the wallet to specific products
5. Save

A wallet is always created empty — there is no opening balance. Add funds afterwards, as described in Adding Funds.

Via API

name, customer_id and currency are required. product_ids is optional and, when set, restricts what the wallet may pay for.

curl -X POST https://api.alguna.io/wallets \
  -H "Authorization: Bearer $ALGUNA_API_KEY" \
  -H "Alguna-Version: 2026-04-01" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "cust_01H2ABC",
    "name": "Main Wallet",
    "currency": "USD"
  }'

Response:

{
  "id": "wlt_01H1VECT",
  "customer_id": "cust_01H2ABC",
  "name": "Main Wallet",
  "currency": "USD",
  "current_balance": "0.00",
  "active": true,
  "product_ids": [],
  "created_at": "2026-04-01T10:00:00Z",
  "updated_at": "2026-04-01T10:00:00Z"
}

A wallet has no status field. active is a boolean, and an inactive wallet cannot pay invoices.

---

Adding Funds

Credit a wallet with the amount, the transaction type it represents, and a reference id that points back to whatever caused the movement.

curl -X POST https://api.alguna.io/wallets/wlt_01H1VECT/credit \
  -H "Authorization: Bearer $ALGUNA_API_KEY" \
  -H "Alguna-Version: 2026-04-01" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "500.00",
    "transaction_type": "payment",
    "reference_id": "pay_01H3DEF",
    "description": "Wallet top-up"
  }'

The response is the updated wallet, with its new current_balance.

Transaction Types

transaction_type	Used for
credit_grant	Funds added by a wallet grant
payment	Funds added by a customer payment
refund	Funds returned to the wallet
manual_debit	An operator-initiated deduction

Debiting a Wallet

curl -X POST https://api.alguna.io/wallets/wlt_01H1VECT/debit \
  -H "Authorization: Bearer $ALGUNA_API_KEY" \
  -H "Alguna-Version: 2026-04-01" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "200.00",
    "transaction_type": "manual_debit",
    "reference_id": "adj_01H4GHI",
    "description": "Correction"
  }'

A debit larger than the wallet balance is rejected with 422.

---

Wallet Grants

A wallet grant records an amount added to a wallet, optionally tied to the payment or invoice that funded it and to an expiry date. Grants are how a prepaid package is represented on a wallet.

curl -X POST https://api.alguna.io/wallet-grants \
  -H "Authorization: Bearer $ALGUNA_API_KEY" \
  -H "Alguna-Version: 2026-04-01" \
  -H "Content-Type: application/json" \
  -d '{
    "wallet_id": "wlt_01H1VECT",
    "amount": "500.00",
    "description": "Prepaid package",
    "expires_at": "2027-03-24T10:00:00Z"
  }'

Response:

{
  "id": "wgr_01H1VECT",
  "wallet_id": "wlt_01H1VECT",
  "amount": "500.00",
  "description": "Prepaid package",
  "expires_at": "2027-03-24T10:00:00Z",
  "status": "pending",
  "payment_id": null,
  "invoice_id": null,
  "created_at": "2026-04-01T10:00:00Z",
  "updated_at": "2026-04-01T10:00:00Z"
}

Grant Status

Status	Description
pending	Created, not yet funded
approved	Funded and applied to the wallet
voided	Cancelled
expired	Passed its expiry date unused

Listing Grants

# Every grant on one wallet
curl https://api.alguna.io/wallets/wlt_01H1VECT/grants \
  -H "Authorization: Bearer $ALGUNA_API_KEY" \
  -H "Alguna-Version: 2026-04-01"

# Across the organization, filtered by status
curl "https://api.alguna.io/wallet-grants?limit=50&offset=0&status=approved" \
  -H "Authorization: Bearer $ALGUNA_API_KEY" \
  -H "Alguna-Version: 2026-04-01"

---

Balance Management

Checking Balance

curl https://api.alguna.io/wallets/wlt_01H1VECT/balance \
  -H "Authorization: Bearer $ALGUNA_API_KEY" \
  -H "Alguna-Version: 2026-04-01"

Response:

{
  "balance": "750.00"
}

The wallet itself also carries current_balance, so GET /wallets/{id} answers the same question alongside the rest of the wallet.

---

Paying Invoices from a Wallet

A wallet is offered as a payment method on an invoice when all of the following hold:

• The wallet is active
• The wallet currency matches the invoice currency — Alguna does not convert between them
• At least one invoice line is for a product the wallet is allowed to pay for
• The wallet has not already been used on that invoice
• The invoice is not itself the invoice that funds a wallet grant

The amount charged is capped at the lowest of the wallet balance, the amount still payable on the invoice, and the total of the eligible lines. If that does not cover the invoice, the rest stays payable by another method.

---

Multi-Currency Wallets

A wallet holds one currency, so a customer who pays in more than one needs a wallet per currency.

curl -X POST https://api.alguna.io/wallets \
  -H "Authorization: Bearer $ALGUNA_API_KEY" \
  -H "Alguna-Version: 2026-04-01" \
  -H "Content-Type: application/json" \
  -d '{"customer_id": "cust_01H2ABC", "name": "EUR Wallet", "currency": "EUR"}'

Currency Matching

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

---

Updating a Wallet

PATCH accepts name, currency, active and product_ids. Deactivating a wallet takes it out of the payment methods offered on an invoice without removing its balance or history.

curl -X PATCH https://api.alguna.io/wallets/wlt_01H1VECT \
  -H "Authorization: Bearer $ALGUNA_API_KEY" \
  -H "Alguna-Version: 2026-04-01" \
  -H "Content-Type: application/json" \
  -d '{
    "active": false
  }'

---

Deleting a Wallet

curl -X DELETE https://api.alguna.io/wallets/wlt_01H1VECT \
  -H "Authorization: Bearer $ALGUNA_API_KEY" \
  -H "Alguna-Version: 2026-04-01"

A wallet with a non-zero balance cannot be deleted. Debit it down to zero first, or deactivate it instead of deleting it.

---

Best Practices

One wallet per currency

Wallets never convert. Create a wallet for each currency the customer is invoiced in.

Always send a reference

Every credit and debit carries a reference_id. Point it at the payment, invoice or adjustment that caused it so the ledger stays reconcilable.

Scope with products

Use product_ids when a prepaid balance should only pay for part of the catalog.

Deactivate before deleting

Setting active to false stops new charges while keeping the balance and history intact.

---

Next Steps

Credits Overview

Learn about the credit system.

Credit Grants

Create and manage credit grants.

Wallets API

Full request and response reference.