Skip to main content
GET
https://sandbox.finhub.cloud
/
api
/
v2.1
/
wallets
/
{walletId}
/
balance
Wallet API
curl --request GET \
  --url https://sandbox.finhub.cloud/api/v2.1/wallets/{walletId}/balance \
  --header 'Authorization: <authorization>' \
  --header 'X-Tenant-ID: <x-tenant-id>'
{
  "success": true,
  "data": {
    "walletId": "wallet_12345",
    "accountId": "acc_67890",
    "balances": {
      "available": {
        "value": 5000.00,
        "currency": "EUR"
      },
      "pending": {
        "value": 150.00,
        "currency": "EUR"
      },
      "reserved": {
        "value": 0.00,
        "currency": "EUR"
      },
      "total": {
        "value": 5150.00,
        "currency": "EUR"
      }
    },
    "lastUpdated": "2024-01-15T10:30:00Z"
  }
}

​
Wallet API

APIs for querying wallet balances, managing wallet funding, and monitoring financial account status.
Base URL: https://sandbox.finhub.cloud/api/v2.1/fintrans (for balance operations)
Base URL: https://sandbox.finhub.cloud/api/v2.1/wallets (for funding operations)
For complete details on authentication and headers, refer to the Standard HTTP Headers reference documentation.

​
Prerequisites

Before accessing wallet operations:
  • Customer account must be ACTIVATED (individual or organization)
  • Wallet is automatically created during activation
  • JWT token obtained via session/login
Wallet Access: Only activated customers can access wallet operations. Attempting to access wallet before activation will return a 404 error.

​
Wallet Lifecycle States

StatusDescriptionOperations Allowed
INACTIVECreated during registrationNone - read-only
PENDING_ACTIVATIONAll prerequisites metNone - awaiting activation
ACTIVEAccount activatedAll operations enabled
SUSPENDEDTemporarily suspendedRead-only
BLOCKEDPermanently blockedNone

​
Available Endpoints

Get Balance

Query current wallet balance

Fund Wallet

Add funds to wallet (Sandbox)

​
Get Wallet Balance

Retrieves the current balance for a specified wallet.

​
Request

​
walletId
string
required
Wallet identifier
​
Authorization
string
required
Bearer token for authentication
​
X-Tenant-ID
string
required
Tenant identifier

​
Code Examples

curl -X GET "https://sandbox.finhub.cloud/api/v2.1/wallets/wallet_12345/balance" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-Tenant-ID: YOUR_TENANT_ID"

{
  "success": true,
  "data": {
    "walletId": "wallet_12345",
    "accountId": "acc_67890",
    "balances": {
      "available": {
        "value": 5000.00,
        "currency": "EUR"
      },
      "pending": {
        "value": 150.00,
        "currency": "EUR"
      },
      "reserved": {
        "value": 0.00,
        "currency": "EUR"
      },
      "total": {
        "value": 5150.00,
        "currency": "EUR"
      }
    },
    "lastUpdated": "2024-01-15T10:30:00Z"
  }
}

​
Fund Wallet (Sandbox Only)

This endpoint is only available in the Sandbox environment for testing purposes. It is not available in production.
Adds funds to a wallet for testing purposes in the sandbox environment.

​
Request

​
walletId
string
required
Wallet identifier
​
amount
number
default:"10000"
Amount to add (default: 10000)
​
currency
string
default:"EUR"
Currency code (default: EUR)

​
Code Examples

curl -X POST "https://sandbox.finhub.cloud/api/v2.1/wallets/wallet_12345/fund?amount=5000&currency=EUR" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-Tenant-ID: YOUR_TENANT_ID"

{
  "success": true,
  "data": {
    "walletId": "wallet_12345",
    "transactionId": "txn_sandbox_12345",
    "amount": {
      "value": 5000.00,
      "currency": "EUR"
    },
    "previousBalance": {
      "value": 1000.00,
      "currency": "EUR"
    },
    "newBalance": {
      "value": 6000.00,
      "currency": "EUR"
    },
    "fundedAt": "2024-01-15T10:30:00Z",
    "note": "Sandbox funding - for testing purposes only"
  }
}

​
Get Account Transactions

Retrieves transaction history for a wallet/account.

​
Request

​
accountId
string
required
Account identifier

​
Code Examples

curl -X GET "https://sandbox.finhub.cloud/api/wallet/accounts/acc_12345/transactions" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-Tenant-ID: YOUR_TENANT_ID"

{
  "success": true,
  "data": {
    "accountId": "acc_12345",
    "transactions": [
      {
        "transactionId": "txn_001",
        "type": "CREDIT",
        "amount": {
          "value": 1000.00,
          "currency": "EUR"
        },
        "description": "Incoming transfer",
        "reference": "INV-2024-001",
        "balanceAfter": 5000.00,
        "createdAt": "2024-01-15T10:00:00Z"
      },
      {
        "transactionId": "txn_002",
        "type": "DEBIT",
        "amount": {
          "value": 250.00,
          "currency": "EUR"
        },
        "description": "SEPA transfer",
        "reference": "Payment to vendor",
        "balanceAfter": 4750.00,
        "createdAt": "2024-01-15T11:30:00Z"
      }
    ],
    "pagination": {
      "total": 45,
      "page": 1,
      "pageSize": 20
    }
  }
}

​
Balance Components Explained

​
Current Balance

The total amount in the wallet, including all pending and reserved funds. 
currentBalance = availableBalance + blockedBalance + pendingBalance

​
Available Balance

Funds you can use immediately for transfers, payments, or withdrawals. Formula: 
availableBalance = currentBalance - blockedBalance - reservedBalance

​
Blocked Balance

Funds temporarily held for:
  • Pending authorization holds
  • Compliance reviews
  • Dispute resolutions
  • Chargebacks

​
Reserved Balance

Funds earmarked for specific transactions that are being processed.

​
Balance History

Track balance changes over time: 
const getBalanceHistory = async (accountId, days = 30) => {
  const response = await fetch(
    `https://sandbox.finhub.cloud/api/v2.1/fintrans/${accountId}/balance-history?days=${days}`,
    {
      headers: {
        'Authorization': `Bearer ${accessToken}`,
        'X-Tenant-ID': tenantId
      }
    }
  );
  
  const { data } = await response.json();
  return data.balanceHistory;
};
Response: 
{
  "balanceHistory": [
    {
      "date": "2024-01-15",
      "balance": "5000.00",
      "currency": "EUR"
    },
    {
      "date": "2024-01-14",
      "balance": "4750.00",
      "currency": "EUR"
    }
  ]
}

​
Wallet Status Meanings

StatusCan TransferCan ReceiveCan TopupAction Required
ACTIVE✅ Yes✅ Yes✅ YesNone
INACTIVE❌ No❌ No❌ NoActivate account
SUSPENDED❌ No✅ Yes❌ NoContact support
BLOCKED❌ No❌ No❌ NoCompliance review

​
Topup Operations Overview

After activation, you can fund your wallet using:
  1. Sandbox Testing: POST /wallets/{walletId}/funding (instant)
  2. Production:
    • Bank transfer to provided IBAN
    • Card payment (if enabled)
    • Partner integrations

​
Response Codes

CodeDescription
200Balance retrieved successfully
400Invalid request parameters
401Unauthorized - invalid or missing token
403Forbidden - wallet access denied
404Wallet or account not found
422Account not activated
500Internal server error

​
API Schema Reference

For the complete OpenAPI schema specification, see the API Schema Mapping document.

Standard Headers

Complete HTTP headers reference

Account Operations

Get allowed operations and limits

Beneficiaries

Manage payment beneficiaries

Transfers

Execute transfers and payments

Individual Activation

Activate individual account

Organization Activation

Activate organization account

​
Changelog

VersionDateChanges
v1.02026-01-13Comprehensive wallet operations documentation