Wallets

Wallets are the balance-holding layer behind collections, disbursements, deposits, withdrawals, and internal transfers. Most business integrations only need a few wallet operations at first, but the SDK already covers the broader lifecycle.

Install

npm install @wistfare/core @wistfare/wallet

pip install wistfare

go get github.com/wistfare/wistfare-go

dependencies:
  wistfare_core: ^0.1.0
  wistfare_wallet: ^0.1.0

cargo add wistfare

dependencies: [
  .package(path: "../sdks/swift")
]

implementation("com.wistfare:sdk:0.1.0")

dotnet add package Wistfare.Core
dotnet add package Wistfare.Wallet

Get the Wallets Client

import { Wistfare } from '@wistfare/core';
import { WalletClient } from '@wistfare/wallet';

const wf = new Wistfare({
  apiKey: process.env.WISTFARE_API_KEY!,
});

const wallets = new WalletClient(wf);

from wistfare import Wistfare

wf = Wistfare(api_key="wf_live_xxx")

wallets = wf.wallets

import (
  "os"

  "github.com/wistfare/wistfare-go/core"
  "github.com/wistfare/wistfare-go/wallet"
)

client := core.New(os.Getenv("WISTFARE_API_KEY"))
wallets := wallet.New(client)

import 'package:wistfare_core/wistfare_core.dart';
import 'package:wistfare_wallet/wistfare_wallet.dart';

final wf = Wistfare(apiKey: 'wf_live_xxx');
final wallets = WalletClient(wf);

use wistfare::Wistfare;

let client = Wistfare::new("wf_live_xxx")?;
let wallets = client.wallets();

import Wistfare

let client = try Wistfare(apiKey: "wf_live_xxx")
let wallets = client.wallets

import com.wistfare.sdk.Wistfare
import com.wistfare.sdk.WistfareConfig

val client = Wistfare(WistfareConfig(apiKey = "wf_live_xxx"))
val wallets = client.wallets

using Wistfare.Core;
using Wistfare.Wallet;

var client = new WistfareClient(new WistfareOptions
{
    ApiKey = Environment.GetEnvironmentVariable("WISTFARE_API_KEY")!,
});

var wallets = new WalletClient(client);

Get a Wallet

Retrieve a wallet by any of the supported fields. The ownerId can be either a business ID or an individual user ID.

// Get by wallet ID
const wallet = await wallets.get({ walletId: 'wal_456' });

// Get by owner (business ID or individual ID)
const wallet = await wallets.get({ ownerId: 'biz_123' });

# Get by wallet ID
wallet = wallets.get(wallet_id="wal_456")

# Get by owner (business ID or individual ID)
wallet = wallets.get(owner_id="biz_123")

// Get by wallet ID
wallet, err := wallets.Get(ctx, &wallet.GetParams{
  WalletID: "wal_456",
})

// Get by owner (business ID or individual ID)
wallet, err := wallets.Get(ctx, &wallet.GetParams{
  OwnerID: "biz_123",
})

// Get by wallet ID
final wallet = await wallets.get(walletId: 'wal_456');

// Get by owner (business ID or individual ID)
final wallet = await wallets.get(ownerId: 'biz_123');

// Get by wallet ID
var wallet = await wallets.GetAsync(new GetWalletParams
{
    WalletId = "wal_456",
});

// Get by owner (business ID or individual ID)
var wallet = await wallets.GetAsync(new GetWalletParams
{
    OwnerId = "biz_123",
});

# Get by wallet ID
curl -X GET "https://api-production.wistfare.com/v1/wallets?walletId=wal_456" \
  -H "X-API-Key: wf_live_xxx"

# Get by owner
curl -X GET "https://api-production.wistfare.com/v1/wallets?ownerId=biz_123" \
  -H "X-API-Key: wf_live_xxx"

Response

A successful call returns a Wallet object:

{
  "id": "wal_456",
  "ownerId": "biz_123",
  "ownerType": "business",
  "currency": "RWF",
  "balance": "150000",
  "availableBalance": "148000",
  "pendingBalance": "2000",
  "status": "active",
  "createdAt": "2026-01-01T00:00:00Z",
  "updatedAt": "2026-03-19T10:00:00Z"
}

Field	Type	Description
`id`	string	Unique wallet identifier
`ownerId`	string	The business or user that owns this wallet
`ownerType`	string	`business` or `user`
`currency`	string	Currency code (e.g. `RWF`)
`balance`	string	Total wallet balance
`availableBalance`	string	Balance available for transactions
`pendingBalance`	string	Balance held in pending transactions
`status`	string	One of `active`, `frozen`, `closed`
`createdAt`	string	ISO 8601 timestamp
`updatedAt`	string	ISO 8601 timestamp

Transfer Funds

const transfer = await wallets.transfer({
  fromWalletId: 'wal_ops',
  toWalletId: 'wal_storefront',
  amount: '25000',
  referenceId: 'topup_001',
  description: 'Top up storefront float',
});

transfer = wallets.transfer(
    from_wallet_id="wal_ops",
    to_wallet_id="wal_storefront",
    amount="25000",
    reference_id="topup_001",
    description="Top up storefront float",
)

transfer, err := wallets.Transfer(ctx, &wallet.TransferParams{
  FromWalletID: "wal_ops",
  ToWalletID:   "wal_storefront",
  Amount:       "25000",
  ReferenceID:  "topup_001",
  Description:  "Top up storefront float",
})

final transfer = await wallets.transfer(
  TransferParams(
    fromWalletId: 'wal_ops',
    toWalletId: 'wal_storefront',
    amount: '25000',
    referenceId: 'topup_001',
    description: 'Top up storefront float',
  ),
);

var transfer = await wallets.TransferAsync(new TransferParams
{
    FromWalletId = "wal_ops",
    ToWalletId = "wal_storefront",
    Amount = "25000",
    ReferenceId = "topup_001",
    Description = "Top up storefront float",
});

curl -X POST https://api-production.wistfare.com/v1/wallets/transfers \
  -H "X-API-Key: wf_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "fromWalletId": "wal_ops",
    "toWalletId": "wal_storefront",
    "amount": "25000",
    "referenceId": "topup_001",
    "description": "Top up storefront float"
  }'

Deposits, Withdrawals, Roles, and Members

The wallet SDKs also expose:

deposits and deposit confirmation
withdrawals to external rails
transaction history per wallet
wallet roles for shared access
wallet members for permissioned collaboration

That gives you enough surface to build both simple merchant wallets and more advanced shared-wallet experiences on top of Wistfare.