Wallet API

Complete API for wallet management including balances, transactions, orders, block/unblock operations, and transaction monitoring.

Base URL: https://sandbox.finhub.cloud/api/v2.1/wallets (wallet management)
Alt URL: https://sandbox.finhub.cloud/api/v2.1/fintrans (balance via FinTrans)

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

Status	Description	Operations Allowed
INACTIVE	Created during registration	None - read-only
PENDING_ACTIVATION	All prerequisites met	None - awaiting activation
ACTIVE	Account activated	All operations enabled
SUSPENDED	Temporarily suspended	Read-only
BLOCKED	Permanently blocked	None

Available Endpoints

Wallet Query & Balance

Method	Path	Description
`GET`	`/wallets/{walletId}/balance`	Get individual wallet balance
`GET`	`/wallets/customer/{customerId}`	Get wallets for a customer
`POST`	`/wallets/balance`	Get tenant Master GP wallet balance summary
`POST`	`/wallets/balance/by-lob`	Get balance breakdown by line of business (B2B/B2C/B2X)
`POST`	`/wallets/tenant`	Get tenant wallets with filtering
`POST`	`/wallets/tenant-assets`	Get tenant asset aggregates
`POST`	`/wallets/classified`	Get classified wallet view
`POST`	`/wallets/customer-balance`	Get customer Master GP wallet balance
`POST`	`/wallets/children-balance`	Get children balance summary (Power Tenant rollup)
`POST`	`/wallets/{walletId}/linked-assets`	Get linked external assets (top-up only)
`POST`	`/wallets/{walletId}/beneficiaries`	Get beneficiaries linked to a wallet

Transactions & Orders

Method	Path	Description
`POST`	`/wallets/transactions`	Get overall transactions (paginated, filtered)
`POST`	`/wallets/customer-transactions`	Get transaction history for a specific customer
`POST`	`/wallets/transactions-by-type`	Get transactions grouped by B2B/B2C type
`POST`	`/wallets/asset-transactions`	Get transactions for a specific asset
`POST`	`/wallets/aggregate-order-status`	Get order counts by type and status (dashboard)
`POST`	`/wallets/pending-orders`	Get pending orders list
`POST`	`/wallets/order-detail`	Get order detail by orderId
`POST`	`/wallets/cancel-order`	Cancel a pending order
`POST`	`/wallets/orders/prepare`	Prepare payment order (Order Wizard)
`POST`	`/wallets/orders/execute`	Execute payment order (Order Wizard)

Block / Unblock

Method	Path	Description
`POST`	`/wallets/block-history`	Get block balance orders history
`POST`	`/wallets/unblock`	Unblock a frozen deposit order
`POST`	`/wallets/customer-block-orders`	Get block orders for a customer

Transaction Monitoring (TM)

Method	Path	Description
`POST`	`/wallets/tm/transactions`	Get TM transactions list
`POST`	`/wallets/tm/transaction-detail`	Get TM transaction detail
`POST`	`/wallets/tm/update-status`	Update TM monitoring status
`POST`	`/wallets/tm/consumer-detail`	Get TM consumer detail

Other

Method	Path	Description
`POST`	`/wallets/{walletId}/fund`	Fund wallet (sandbox testing)
`POST`	`/fintrans/{walletId}/payment-documents`	Upload payment document

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 "Accept: application/json, text/plain, */*" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-Tenant-ID: 97e7ff29-15f3-49ef-9681-3bbfcce4f6cd" \
  -H "X-Forwarded-From: e2e-test" \
  -H "platform: web" \
  -H "deviceId: 356938035643809"

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

string

required

Amount to add (e.g., "1000.00" or number in cents)

currency

string

default:"EUR"

Currency code (default: EUR)

Code Examples

curl -X POST "https://sandbox.finhub.cloud/api/v2.1/wallets/wallet_12345/fund" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/plain, */*" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-Tenant-ID: 97e7ff29-15f3-49ef-9681-3bbfcce4f6cd" \
  -H "X-Forwarded-From: e2e-test" \
  -H "platform: web" \
  -H "deviceId: 356938035643809" \
  -d '{"amount": "1000.00", "currency": "EUR"}'

{
  "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 Customer Wallets

Retrieves all wallets belonging to a specific customer (individual or organization).

GET /api/v2.1/wallets/customer/{customerId}

Request

customerId

string

required

Customer UUID (individual or organization)

customerType

string

Customer type: B2C (individual) or B2B (organization). Defaults to B2B.

X-Tenant-ID

string

required

Tenant identifier

Code Examples

curl -X GET "https://sandbox.finhub.cloud/api/v2.1/wallets/customer/cust_12345?customerType=B2B" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Tenant-ID: finsei"

{
  "code": 200,
  "data": [
    {
      "walletId": "69a7d5b0-58f0-4394-a3fc-4d33058dc89e",
      "walletExternalId": "69a7d5b0-58f0-4394-a3fc-4d33058dc89e",
      "customerId": "cust_12345",
      "walletName": "GP Wallet EUR",
      "walletType": "master_general_purpose",
      "status": "ACTIVE",
      "currency": "EUR",
      "balance": "10000.00",
      "availableBalance": "9500.00",
      "iban": "FI2112345600000785"
    }
  ]
}

Tenant Wallet Management

Get Tenant Balance Summary

POST /api/v2.1/wallets/balance

Returns the Master GP wallet balance summary for the tenant. Used by the Wallet Overview dashboard.

X-Tenant-ID

string

required

Tenant identifier

X-Organization-ID

string

Organization ID (for scoping)

tenantId

string

Tenant UUID (overrides header if provided)

{
  "code": 200,
  "data": {
    "walletId": "69a7d5b0-...",
    "currentBalance": "50000.00",
    "availableBalance": "48500.00",
    "blockedBalance": "1500.00",
    "currency": "EUR"
  }
}

Get Balance by Line of Business

POST /api/v2.1/wallets/balance/by-lob

Returns aggregated balance breakdown by B2B, B2C, and B2X. Used by the LOB breakdown chart.

walletId

string

Master GP wallet ID. If omitted, the BFF resolves it automatically.

{
  "walletId": "69a7d5b0-...",
  "balances": [
    { "lineOfBusiness": "B2X", "available": "10000.00", "current": "10000.00", "blocked": "0.00", "currency": "EUR", "childWalletCount": 10 },
    { "lineOfBusiness": "B2B", "available": "8000.00", "current": "8000.00", "blocked": "0.00", "currency": "EUR", "childWalletCount": 7 },
    { "lineOfBusiness": "B2C", "available": "2000.00", "current": "2000.00", "blocked": "0.00", "currency": "EUR", "childWalletCount": 3 }
  ]
}

Get Tenant Wallets

POST /api/v2.1/wallets/tenant

Returns wallets for the tenant with optional filtering.

Get Tenant Assets

POST /api/v2.1/wallets/tenant-assets

Returns wallet asset aggregates for the tenant.

Get Classified Wallets

POST /api/v2.1/wallets/classified

Returns a classified view of wallets grouped by wallet type (master GP, fee collector, segregated, etc.).

Get Customer Master GP Wallet

POST /api/v2.1/wallets/customer-balance

Returns the Master GP wallet with CURRENCY asset balance for a specific customer.

Get Children Balance Summary

POST /api/v2.1/wallets/children-balance

Returns aggregated balance summary of child tenants (Power Tenant view). The BFF auto-resolves the parent_wallet_id if not provided.

parent_wallet_id

string

Parent Master GP wallet ID. Auto-resolved if omitted.

asset_sub_unit_id

string

Asset sub-unit ID. Defaults to EUR: dd35508b-7529-49b8-ae56-fafd523f953f

page

integer

default:"1"

Page number (1-indexed)

page_size

integer

default:"20"

Results per page

Get Linked External Assets

POST /api/v2.1/wallets/{walletId}/linked-assets

Returns linked external assets for a wallet (top-up channels only).

Get Wallet Beneficiaries

POST /api/v2.1/wallets/{walletId}/beneficiaries

Returns beneficiaries linked to a specific wallet. Also available via legacy alias at POST /wallets/{walletId}/assets.

Transaction & Order Endpoints

Get Overall Transactions

POST /api/v2.1/wallets/transactions

Retrieves paginated transaction list with filters. Maps to WSO2 GetOverAllTransactions.

startDate

string

Start date (YYYY-MM-DD). Also accepts fromDate.

endDate

string

End date (YYYY-MM-DD). Also accepts toDate.

pageNumber

integer

default:"1"

Page number (1-indexed). Also accepts page.

pageSize

integer

default:"20"

Results per page

orderType

string

Filter by WSO2 order type (e.g., sepa_transfer, sepa_instant_payment, deposit_via_bank_transfer)

searchKey

string

Text search across transactions

{
  "overAllTransactions": [
    {
      "orderId": "ord_123",
      "orderType": "sepa_transfer_external",
      "status": "completed",
      "amount": "500.00",
      "currency": "EUR",
      "createdDate": "2026-01-15T10:00:00Z"
    }
  ],
  "totalCount": 45
}

Get Customer Transactions

POST /api/v2.1/wallets/customer-transactions

Returns transaction history for a specific customer (organization or individual). Maps to WSO2 GetOverAllTransactionHistoryByCustomer.

Get Transactions by Customer Type

POST /api/v2.1/wallets/transactions-by-type

Returns transactions grouped by B2B/B2C customer type. Maps to WSO2 GetTransactionHistoryByCustomerType.

Get Asset Transactions

POST /api/v2.1/wallets/asset-transactions

Returns transactions for a specific asset. Maps to WSO2 GetAssetTransactions.

Get Aggregate Order Status

POST /api/v2.1/wallets/aggregate-order-status

Returns order counts grouped by orderType and status for dashboard charts. Maps to WSO2 GetAggregateOrderStatus.

startDate

string

required

Start date (YYYY-MM-DD)

endDate

string

required

End date (YYYY-MM-DD)

{
  "totalOrders": 120,
  "aggregates": [
    {
      "orderType": "sepa_transfer_external",
      "totalCount": 45,
      "statusCounts": [
        { "status": "completed", "count": 40 },
        { "status": "pending", "count": 5 }
      ]
    }
  ]
}

Get Pending Orders

POST /api/v2.1/wallets/pending-orders

Returns a paginated list of pending orders. Maps to WSO2 GetPendingOrders.

Get Order Detail

POST /api/v2.1/wallets/order-detail

Returns order detail by orderId. Maps to WSO2 GetOrderDetail.

orderId

string

required

Order ID to retrieve

Cancel Pending Order

POST /api/v2.1/wallets/cancel-order

Cancels a pending order with reason. Results in rejected status. Maps to WSO2 CancelOrder.

orderId

string

required

Order ID to cancel

reason

string

Cancellation reason

Cancellable states: created, validated, processing, pending sanction check, rule prepare: ready, rule prepare: pending consent.

Block / Unblock Endpoints

Get Block Balance Orders History

POST /api/v2.1/wallets/block-history

Returns history of block/unblock operations. Maps to WSO2 GetBlockBalanceOrdersHistory.

Unblock Deposit Order

POST /api/v2.1/wallets/unblock

Unblocks a frozen deposit order. Maps to WSO2 UnblockDepositOrder.

blockOrderId

string

required

Block order ID to unblock. Also accepts orderId (auto-mapped).

Get Block Orders by Customer

POST /api/v2.1/wallets/customer-block-orders

Returns block orders for a specific customer. Maps to WSO2 GetBlockOrdersByCustomerId.

Transaction Monitoring (TM)

Get TM Transactions

POST /api/v2.1/wallets/tm/transactions

Returns transaction monitoring transaction list. Maps to WSO2 TMGetTransactions.

pageNumber

integer

default:"1"

Page number

pageSize

integer

default:"20"

Results per page

startDate

string

Start date (defaults to 1 month ago)

endDate

string

End date (defaults to today)

filterReasons

array

Filter by monitoring reasons. Must be a string array (not empty string).

Get TM Transaction Detail

POST /api/v2.1/wallets/tm/transaction-detail

Returns detailed transaction monitoring info for a specific transaction. Maps to WSO2 TMGetTransactionDetail.

Update TM Status

POST /api/v2.1/wallets/tm/update-status

Updates transaction monitoring status for a transaction. Maps to WSO2 TMUpdateTransactionMonitoringStatus.

Get TM Consumer Detail

POST /api/v2.1/wallets/tm/consumer-detail

Returns consumer detail from transaction monitoring. Maps to WSO2 TMGetConsumerDetail.

Upload Payment Document

POST /api/v2.1/fintrans/{walletId}/payment-documents

Uploads a payment document (invoice, proof of funds) for a wallet. Required for high-value transactions above threshold.

walletId

string

required

Wallet ID

X-Tenant-ID

string

required

Tenant identifier

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.

Wallet Status Meanings

Status	Can Transfer	Can Receive	Can Topup	Action Required
ACTIVE	✅ Yes	✅ Yes	✅ Yes	None
INACTIVE	❌ No	❌ No	❌ No	Activate account
SUSPENDED	❌ No	✅ Yes	❌ No	Contact support
BLOCKED	❌ No	❌ No	❌ No	Compliance review

Topup Operations Overview

After activation, you can fund your wallet using:

Sandbox Testing: POST /wallets/{walletId}/fund (instant, sandbox-only)
Production (Prepare-Execute):
- POST /fintrans/{accountId}/types/topup/prepare — stage the topup with source IBAN and amount
- POST /fintrans/{accountId}/types/topup/execute — execute with preparedOrderId
- See Account Operations — Topup Workflow for full details
External Bank Transfer: Send funds to the wallet IBAN directly

The /wallets/{walletId}/fund endpoint is sandbox-only. In production, use the topup prepare-execute workflow via /fintrans/{accountId}/types/topup/prepare and /execute.

Response Codes

Code	Description
`200`	Balance retrieved successfully
`400`	Invalid request parameters
`401`	Unauthorized - invalid or missing token
`403`	Forbidden - wallet access denied
`404`	Wallet or account not found
`422`	Account not activated
`500`	Internal 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

Version	Date	Changes
v1.0	2026-01-13	Comprehensive wallet operations documentation

Headers

X-Tenant-ID

string

required

Tenant identifier

Example:

"97e7ff29-15f3-49ef-9681-3bbfcce4f6cd"

Path Parameters

walletId

string

required

Response

200

Client Categories

Product Suite

Service Models

CoreX Service Model

API Service Model

Hybrid Service Model

​Wallet API

​Prerequisites

​Wallet Lifecycle States

​Available Endpoints

​Wallet Query & Balance

​Transactions & Orders

​Block / Unblock

​Transaction Monitoring (TM)

​Other

​Get Wallet Balance

​Request

​Code Examples

​Fund Wallet (Sandbox Only)

​Request

​Code Examples

​Get Customer Wallets

​Request

​Code Examples

​Tenant Wallet Management

​Get Tenant Balance Summary

​Get Balance by Line of Business

​Get Tenant Wallets

​Get Tenant Assets

​Get Classified Wallets

​Get Customer Master GP Wallet

​Get Children Balance Summary

​Get Linked External Assets

​Get Wallet Beneficiaries

​Transaction & Order Endpoints

​Get Overall Transactions

​Get Customer Transactions

​Get Transactions by Customer Type

​Get Asset Transactions

​Get Aggregate Order Status

​Get Pending Orders

​Get Order Detail

​Cancel Pending Order

​Block / Unblock Endpoints

​Get Block Balance Orders History

​Unblock Deposit Order

​Get Block Orders by Customer

​Transaction Monitoring (TM)

​Get TM Transactions

​Get TM Transaction Detail

​Update TM Status

​Get TM Consumer Detail

​Upload Payment Document

​Balance Components Explained

​Current Balance

​Available Balance

​Blocked Balance

​Reserved Balance

​Wallet Status Meanings

​Topup Operations Overview

​Response Codes

​API Schema Reference

​Related Endpoints

Standard Headers

Account Operations

Beneficiaries

Transfers

Individual Activation

Organization Activation

​Changelog

Headers

Path Parameters

Response

Wallet API

Prerequisites

Wallet Lifecycle States

Available Endpoints

Wallet Query & Balance

Transactions & Orders

Block / Unblock

Transaction Monitoring (TM)

Other

Get Wallet Balance

Request

Code Examples

Fund Wallet (Sandbox Only)

Request

Code Examples

Get Customer Wallets

Request

Code Examples

Tenant Wallet Management

Get Tenant Balance Summary

Get Balance by Line of Business

Get Tenant Wallets

Get Tenant Assets

Get Classified Wallets

Get Customer Master GP Wallet

Get Children Balance Summary

Get Linked External Assets

Get Wallet Beneficiaries

Transaction & Order Endpoints

Get Overall Transactions

Get Customer Transactions

Get Transactions by Customer Type

Get Asset Transactions

Get Aggregate Order Status

Get Pending Orders

Get Order Detail

Cancel Pending Order

Block / Unblock Endpoints

Get Block Balance Orders History

Unblock Deposit Order

Get Block Orders by Customer

Transaction Monitoring (TM)

Get TM Transactions

Get TM Transaction Detail

Update TM Status

Get TM Consumer Detail

Upload Payment Document

Balance Components Explained

Current Balance

Available Balance

Blocked Balance

Reserved Balance

Wallet Status Meanings

Topup Operations Overview

Response Codes

API Schema Reference

Related Endpoints

Changelog