Check Wallet Balance

The Wallet Balance API allows clients to retrieve their current LumiID wallet balance and associated account information programmatically. This endpoint is useful for monitoring available funds, implementing automated wallet monitoring, and checking account balances before initiating identity verification requests.GET

GET https://api.lumiid.com/v1/wallet/balance/

1. Authentication

The endpoint requires your LumiID API key. Include your API key in the Authorization header using the Bearer authentication scheme.

Authorization: Bearer YOUR_LUMIID_API_KEY
Accept: application/json

2. Request parameters

No query parameters or request body are required.

Parameter	Type	Required	Description
None	—	—	Authentication is handled through the API key.

3. Example request

cURL

curl -X GET \
  "https://api.lumiid.com/v1/wallet/balance/" \
  -H "Authorization: Bearer YOUR_LUMIID_API_KEY" \
  -H "Accept: application/json"

4. Successful response

200 OK

{
  "status": "success",
  "balance": "3630.00",
  "client": {
    "name": "Sample Company LTD"
  }
}

5. Response fields

Field	Type	Description
`status`	string	Indicates whether the request was successful.
`balance`	string	Current wallet balance, represented as a decimal string.
`client`	object	Contains the authenticated client’s information.
`client.name`	string	Registered organization name associated with the API key.

Note: The balance is returned as a string to preserve decimal precision. Parse it using a decimal-safe numeric type when performing financial calculations.

6. Error responses

404 — Wallet not found

Returned when the authenticated organization does not have an associated wallet.

{
  "error": "Wallet not found"
}

401 — Unauthorized

Returned when the API key is missing or invalid, assuming the authentication class returns this status.

{
  "error": "Invalid or missing API key."
}

7. Integration examples

React.js

For production applications, call this endpoint through your backend to protect your API key.

import { useState } from "react";

export default function WalletBalance() {
  const [wallet, setWallet] = useState(null);
  const [loading, setLoading] = useState(false);
  const [error, setError] = useState("");

  const fetchBalance = async () => {
    setLoading(true);
    setError("");

    try {
      const response = await fetch("/api/wallet/balance/", {
        headers: {
          Accept: "application/json"
        },
        credentials: "include"
      });

      const data = await response.json();

      if (!response.ok) {
        throw new Error(data.error || "Unable to retrieve balance");
      }

      setWallet(data);
    } catch (err) {
      setError(err.message);
    } finally {
      setLoading(false);
    }
  };

  return (
    <div>
      <button onClick={fetchBalance} disabled={loading}>
        {loading ? "Loading..." : "Check Wallet Balance"}
      </button>

      {error && <p>{error}</p>}

      {wallet && (
        <div>
          <h3>{wallet.client.name}</h3>
          <h2>₦{wallet.balance}</h2>
          <p>Status: {wallet.status}</p>
        </div>
      )}
    </div>
  );
}

The /api/wallet/balance/ route above is an example of your own backend proxy.

PHP

<?php

$apiKey = getenv('LUMIID_API_KEY');

$url = 'https://api.lumiid.com/v1/wallet/balance/';

$ch = curl_init($url);

curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPGET => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . $apiKey,
        'Accept: application/json'
    ],
    CURLOPT_TIMEOUT => 30
]);

$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);

if ($response === false) {
    error_log(curl_error($ch));
    curl_close($ch);
    http_response_code(502);
    exit(json_encode(['error' => 'Unable to reach LumiID']));
}

curl_close($ch);

$data = json_decode($response, true);

if ($httpCode !== 200) {
    http_response_code($httpCode);
    echo $response;
    exit;
}

echo json_encode([
    'client' => $data['client']['name'],
    'balance' => $data['balance'],
    'status' => $data['status']
]);

Flutter (Dart)

Install the HTTP package:

flutter pub add http

Create a wallet service:

import 'dart:convert';
import 'package:http/http.dart' as http;

class LumiIDWalletService {
  final String apiKey;

  LumiIDWalletService({required this.apiKey});

  Future<Map<String, dynamic>> getBalance() async {
    final url = Uri.parse(
      'https://api.lumiid.com/v1/wallet/balance/',
    );

    final response = await http.get(
      url,
      headers: {
        'Authorization': 'Bearer $apiKey',
        'Accept': 'application/json',
      },
    );

    final data = jsonDecode(response.body);

    if (response.statusCode != 200) {
      throw Exception(
        data['error'] ?? 'Unable to retrieve wallet balance',
      );
    }

    return Map<String, dynamic>.from(data);
  }
}

Example usage:

final walletService = LumiIDWalletService(
  apiKey: 'YOUR_LUMIID_API_KEY',
);

final wallet = await walletService.getBalance();

print('Client: ${wallet['client']['name']}');
print('Balance: ₦${wallet['balance']}');

For production Flutter applications, retrieve the balance through your authenticated backend rather than embedding a permanent secret API key in the application.

8. Recommended use cases

Wallet monitoring: Periodically check available wallet funds.
Low-balance alerts: Notify administrators when the wallet balance falls below a configured threshold.
Dashboard integration: Display the current LumiID wallet balance in your application.
Transaction monitoring: Check available funds before initiating verification requests.

Important: This endpoint retrieves the current wallet balance. It does not fund the wallet, initiate transactions, or reserve funds for verification requests. Authentication is scoped to the organization associated with the API key.

Get Started

General

Government Verification

Business Verification

Biometric & AML

SDKs & Integration

Reference

Check Wallet Balance

1. Authentication

2. Request parameters

3. Example request

4. Successful response

5. Response fields

6. Error responses

404 — Wallet not found

401 — Unauthorized

7. Integration examples

React.js

PHP

Flutter (Dart)

8. Recommended use cases

​1. Authentication

​2. Request parameters

​3. Example request

​4. Successful response

​5. Response fields

​6. Error responses

​404 — Wallet not found

​401 — Unauthorized

​7. Integration examples

​React.js

​PHP

​Flutter (Dart)

​8. Recommended use cases

1. Authentication

2. Request parameters

3. Example request

4. Successful response

5. Response fields

6. Error responses

404 — Wallet not found

401 — Unauthorized

7. Integration examples

React.js

PHP

Flutter (Dart)

8. Recommended use cases