Skip to main content

​
Overview

Wallet APIs for account creation, balance/transactions, and funding/withdrawals.
Auth: JTW token is valid for 1 hour from the time of issuance. After it expires, you must generate a new token.

​
Get a token

Generate a short‑lived token using your keyId and secret. 
POST /api/generate-token
Content-Type: application/json

{
  "keyId": "00000000-0000-4000-8000-000000000000",
  "secret": "<your-api-secret>"
}
Response
{
  "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiresAt": "2025-01-01T12:00:00.000Z",
  "businessId": "11111111-2222-3333-4444-555555555555",
  "environment": "sandbox",
  "scopes": ["wms:read", "wms:write"]
}
Use the token in the Authorization header for all subsequent requests: 
Authorization: Bearer <token>

​
Walett Management

​
Open wallet

POST /api/v1/wms/wallets
Authorization: Bearer <token>
Content-Type: application/json

{
  "businessId": "11111111-2222-3333-4444-555555555555",
  "customerId": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  "productCode": "SAVINGS_BASIC"
}
Response
{
  "id": "a1b2c3d4-0000-0000-0000-000000000000",
  "businessId": "11111111-2222-3333-4444-555555555555",
  "customerId": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  "productCode": "SAVINGS_BASIC",
  "fspAccountId": "4921",
  "createdAt": "2025-01-01T10:00:00.000Z",
  "updatedAt": "2025-01-01T10:00:01.000Z"
}

​
Get wallet

GET /api/v1/wms/wallets/{walletId}
Authorization: Bearer <token>
Response
{
  "id": "a1b2c3d4-0000-0000-0000-000000000000",
  "businessId": "11111111-2222-3333-4444-555555555555",
  "customerId": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  "productCode": "SAVINGS_BASIC",
  "fspAccountId": "4921",
  "balanceMinor": 0,
  "createdAt": "2025-01-01T10:00:00.000Z",
  "updatedAt": "2025-01-01T10:00:01.000Z"
}

​
List transactions

GET /api/v1/wms/wallets/{walletId}/transactions
Authorization: Bearer <token>
Response
{
  "items": [
    {
      "id": "tx_01H...",
      "walletId": "a1b2c3d4-0000-0000-0000-000000000000",
      "type": "topup",
      "amountMinor": "100000",
      "currency": "TZS",
      "reference": null,
      "externalId": null,
      "createdAt": "2025-01-01T10:05:00.000Z"
    }
  ]
}

​
Top up

POST /api/v1/wms/wallets/{walletId}/topup
Authorization: Bearer <token>
Content-Type: application/json

{
  "amountMinor": 100000,
  "currency": "TZS"
}
Response
{
  "status": "accepted",
  "transactionId": "tx_01H..."
}

​
Payout

​
Transfer between wallets

POST /api/v1/wms/wallets/transfer
Authorization: Bearer <token>
Content-Type: application/json

{
  "fromWalletId": "a1b2c3d4-...",
  "toWalletId": "b2c3d4e5-...",
  "amountMinor": 250000,
  "currency": "TZS"
}
Response
{
  "status": "accepted",
  "transferId": "tr_01H..."
}

​
Wallet statement

GET /api/v1/wms/wallets/{walletId}/statement
Authorization: Bearer <token>
Response
{
  "walletId": "a1b2c3d4-...",
  "period": { "fromDate": "2025-01-01", "toDate": "2025-01-31" },
  "openingBalanceMinor": 0,
  "closingBalanceMinor": 500000,
  "transactions": [
    { "date": "2025-01-05", "type": "topup", "amountMinor": 500000, "currency": "TZS" }
  ]
}

​
Freeze wallet

POST /api/v1/wms/wallets/{walletId}:freeze
Authorization: Bearer <token>
Content-Type: application/json

{
  "reason": "suspected fraud"
}
Response
{ "status": "frozen", "walletId": "a1b2c3d4-..." }

​
Unfreeze wallet

POST /api/v1/wms/wallets/{walletId}:unfreeze
Authorization: Bearer <token>
Response
{ "status": "active", "walletId": "a1b2c3d4-..." }

POST /api/v1/wms/wallets/{walletId}/payout
Authorization: Bearer <token>
Content-Type: application/json

{
  "amountMinor": 50000,
  "currency": "TZS"
}
Response
{
  "status": "accepted",
  "transactionId": "tx_01H..."
}

​
API reference

​
Reports

All reports support fromDate, toDate, optional format=json|csv|pdf.

​
Portfolio summary

GET /api/v1/wms/reports/portfolio-summary?fromDate=2025-01-01&toDate=2025-01-31
Authorization: Bearer <token>
Response
{
  "fromDate": "2025-01-01",
  "toDate": "2025-01-31",
  "totals": { "numWallets": 42000, "balanceMinor": 98765432100 },
  "byProduct": [
    { "productCode": "SAVINGS_BASIC", "numWallets": 30000, "balanceMinor": 70000000000 }
  ]
}

​
Transaction activity & volume

GET /api/v1/wms/reports/transaction-activity?fromDate=2025-01-01&toDate=2025-01-31&transactionType=topup&frequency=daily
Authorization: Bearer <token>
Response
{
  "fromDate": "2025-01-01",
  "toDate": "2025-01-31",
  "series": [
    { "date": "2025-01-01", "count": 1200, "amountMinor": 500000000 },
    { "date": "2025-01-02", "count": 1500, "amountMinor": 600000000 }
  ]
}

​
Liquidity & float

GET /api/v1/wms/reports/liquidity?fromDate=2025-01-01&toDate=2025-01-31&floatType=custodian&frequency=daily
Authorization: Bearer <token>
Response
{
  "fromDate": "2025-01-01",
  "toDate": "2025-01-31",
  "floatType": "custodian",
  "series": [
    { "date": "2025-01-01", "balanceMinor": 20000000000 },
    { "date": "2025-01-02", "balanceMinor": 20500000000 }
  ]
}

​
Reconciliation

GET /api/v1/wms/reports/reconciliation?fromDate=2025-01-01&toDate=2025-01-31&status=pending&fspId=fspi_bank
Authorization: Bearer <token>
Response
{
  "fromDate": "2025-01-01",
  "toDate": "2025-01-31",
  "status": "pending",
  "items": [
    { "reference": "ext_123", "amountMinor": 1000000, "currency": "TZS", "accountType": "custodian" }
  ]
}

​
Finance

​
Float/custodian positions

GET /api/v1/wms/reports/liquidity?fromDate=2025-01-01&toDate=2025-01-31&floatType=fsp
Authorization: Bearer <token>

​
Journal exports

GET /api/v1/wms/reports/reconciliation?fromDate=2025-01-01&toDate=2025-01-31&status=reconciled&format=csv
Authorization: Bearer <token>