Wallets - Alguna Docs

A wallet is a prepaid balance of money, in one currency, belonging to one customer. The customer (or you, on their behalf) funds it, every movement is recorded on the wallet ledger, and the wallet is offered as a payment method on invoices in the same currency. Use wallets when a customer wants to deposit funds up front and settle invoices from the balance, or when you sell prepaid packages that should be spendable on only part of your catalogue.

Wallets and credit grants are separate systems. A wallet holds money the customer paid in; a credit grant is credit you allocate, consumed while invoices are priced. The overview compares them.

A customer can hold several wallets — one per currency, or several with different product_ids. Wallet ids are prefixed wlt_, wallet grant ids wgr_, customer ids cust_. See How Alguna Works.

Create a wallet

Via API

name, customer_id, and currency are required. product_ids is optional and, when set, restricts which invoice lines the wallet may pay for. See Create a wallet.

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"
  }'

import os

import requests

response = requests.post(
    "https://api.alguna.io/wallets",
    headers={
        "Authorization": f"Bearer {os.environ['ALGUNA_API_KEY']}",
        "Alguna-Version": "2026-04-01",
        "Content-Type": "application/json",
    },
    json={"customer_id": "cust_01H2ABC", "name": "Main Wallet", "currency": "USD"},
    timeout=10,
)
response.raise_for_status()

wallet = response.json()
print(wallet["id"], wallet["current_balance"], wallet["active"])

const wallet = await alguna.wallets.create({
  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; an inactive wallet cannot pay invoices. A wallet is always created empty — add funds afterwards.

From the dashboard

Open Customers → [Customer] → Profile.
In the Wallets card, add a wallet.
Name it, choose the currency, and optionally restrict it to products.
Save.

Add and remove funds

POST /wallets/{id}/credit and POST /wallets/{id}/debit move money and write a ledger entry. amount, transaction_type, and reference_id are required; description is optional. The response is the updated wallet with its new current_balance. See Credit a wallet and Debit a wallet.

# Credit
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"
  }'

# Debit
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"
  }'

import os

import requests

headers = {
    "Authorization": f"Bearer {os.environ['ALGUNA_API_KEY']}",
    "Alguna-Version": "2026-04-01",
    "Content-Type": "application/json",
}

credited = requests.post(
    "https://api.alguna.io/wallets/wlt_01H1VECT/credit",
    headers=headers,
    json={
        "amount": "500.00",
        "transaction_type": "payment",
        "reference_id": "pay_01H3DEF",
        "description": "Wallet top-up",
    },
    timeout=10,
)
credited.raise_for_status()

debited = requests.post(
    "https://api.alguna.io/wallets/wlt_01H1VECT/debit",
    headers=headers,
    json={
        "amount": "200.00",
        "transaction_type": "manual_debit",
        "reference_id": "adj_01H4GHI",
        "description": "Correction",
    },
    timeout=10,
)
debited.raise_for_status()
print(debited.json()["current_balance"])

await alguna.wallets.credit("wlt_01H1VECT", {
  amount: "500.00",
  transaction_type: "payment",
  reference_id: "pay_01H3DEF",
  description: "Wallet top-up",
});

await alguna.wallets.debit("wlt_01H1VECT", {
  amount: "200.00",
  transaction_type: "manual_debit",
  reference_id: "adj_01H4GHI",
  description: "Correction",
});

A debit larger than the balance is rejected with 422.

Transaction types

`transaction_type`	Used for
`credit_grant`	Funds added by an approved wallet grant
`payment`	Funds added by a customer payment
`refund`	Funds returned to the wallet, for example a credit note refunded with `refund_destination: "wallet"`
`manual_debit`	An operator-initiated deduction

Wallet grants

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

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"
  }'

import os

import requests

response = requests.post(
    "https://api.alguna.io/wallet-grants",
    headers={
        "Authorization": f"Bearer {os.environ['ALGUNA_API_KEY']}",
        "Alguna-Version": "2026-04-01",
        "Content-Type": "application/json",
    },
    json={
        "wallet_id": "wlt_01H1VECT",
        "amount": "500.00",
        "description": "Prepaid package",
        "expires_at": "2027-03-24T10:00:00Z",
    },
    timeout=10,
)
response.raise_for_status()

grant = response.json()
print(grant["id"], grant["status"])

const grant = await alguna.walletGrants.create({
  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`	Meaning
`pending`	Created, not yet funded. The wallet balance is unchanged.
`approved`	Funded. Approval credits the wallet with a `credit_grant` ledger entry for the grant amount.
`voided`	Cancelled before funding
`expired`	Passed `expires_at`

Transitions are pending → approved, pending → voided, pending → expired, and approved → expired; voided and expired are terminal. A grant funded by an invoice (invoice_id) is approved when that invoice is paid; a top-up recorded without a payment is approved immediately.

List 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"

import os

import requests

headers = {
    "Authorization": f"Bearer {os.environ['ALGUNA_API_KEY']}",
    "Alguna-Version": "2026-04-01",
}

on_wallet = requests.get(
    "https://api.alguna.io/wallets/wlt_01H1VECT/grants", headers=headers, timeout=10
)
on_wallet.raise_for_status()

approved = requests.get(
    "https://api.alguna.io/wallet-grants",
    headers=headers,
    params={"limit": 50, "offset": 0, "status": "approved"},
    timeout=10,
)
approved.raise_for_status()
print(len(approved.json()["data"]))

const onWallet = await alguna.wallets.listGrants("wlt_01H1VECT");
const approved = await alguna.walletGrants.list({ limit: 50, offset: 0, status: "approved" });

See List grants for a wallet and List wallet grants.

Check the balance

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

import os

import requests

response = requests.get(
    "https://api.alguna.io/wallets/wlt_01H1VECT/balance",
    headers={
        "Authorization": f"Bearer {os.environ['ALGUNA_API_KEY']}",
        "Alguna-Version": "2026-04-01",
    },
    timeout=10,
)
response.raise_for_status()
print(response.json()["balance"])

const { balance } = await alguna.wallets.getBalance("wlt_01H1VECT");

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. GET /wallets?customer_id=…&active=true lists a customer’s wallets.

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 (or product_ids is empty).
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. Anything left stays payable by another method. See Invoicing Customers.

Update or deactivate a wallet

PATCH /wallets/{id} accepts name, currency, active, and product_ids. Deactivating a wallet takes it out of the payment methods offered on an invoice without touching its balance or history. See Update a wallet.

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 }'

import os

import requests

requests.patch(
    "https://api.alguna.io/wallets/wlt_01H1VECT",
    headers={
        "Authorization": f"Bearer {os.environ['ALGUNA_API_KEY']}",
        "Alguna-Version": "2026-04-01",
        "Content-Type": "application/json",
    },
    json={"active": False},
    timeout=10,
).raise_for_status()

await alguna.wallets.update("wlt_01H1VECT", { active: false });

Delete a wallet

DELETE /wallets/{id} returns 204. A wallet with a non-zero balance cannot be deleted: debit it to zero first, or deactivate it instead. See Delete a wallet.

Multi-currency

A wallet holds one currency, so a customer who is invoiced in more than one needs a wallet per currency. Invoices are paid from the wallet matching their currency. See Multi-Currency.

Best practices

One wallet per currency

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

Always send a reference

Point reference_id at the payment, invoice, or adjustment that caused the movement so the ledger reconciles.

Scope with products

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

Deactivate before deleting

active: false stops new charges while keeping the balance and history.

Next steps

Credits Overview

Wallets versus credit grants.

Credit Notes

Refund a credit note into a wallet.

Wallets API

Full request and response reference.

​Create a wallet

​Via API

​From the dashboard

​Add and remove funds

​Transaction types

​Wallet grants

​Grant status

​List grants

​Check the balance

​Paying invoices from a wallet

​Update or deactivate a wallet

​Delete a wallet

​Multi-currency

​Best practices

One wallet per currency

Always send a reference

Scope with products

Deactivate before deleting

​Next steps

Credits Overview

Credit Notes

Wallets API

Create a wallet

Via API

From the dashboard

Add and remove funds

Transaction types

Wallet grants

Grant status

List grants

Check the balance

Paying invoices from a wallet

Update or deactivate a wallet

Delete a wallet

Multi-currency

Best practices

Next steps