Wallets

Wallets hold stored value for a customer. Deposits are gateway-verified before they credit. Escrow lets you hold funds and capture or release them later.

Requires an active customer — see Customer onboarding. Bearer token from /generate-token; re-token on 401.

Open and activate a wallet

A new wallet must be opened, approved, then activated before use.

Open

WALLET=$(curl -s -X POST $BRIDGE_URL/v1/wms/wallets \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d "{\"customerId\":\"$CUSTOMER_ID\",\"productCode\":\"CSAV\"}")
WALLET_ID=$(echo $WALLET | jq -r .id)

businessId is taken from your token. Use GET /v1/wms/products to list wallet product codes.

Approve + activate

curl -s -X POST $BRIDGE_URL/v1/wms/wallets/$WALLET_ID/approve  -H "Authorization: Bearer $TOKEN" -d '{}'
curl -s -X POST $BRIDGE_URL/v1/wms/wallets/$WALLET_ID/activate -H "Authorization: Bearer $TOKEN" -d '{}'

Fund it (verified deposit)

When your gateway has collected money (see Collections), record it. Bridge verifies the deposit on the gateway before crediting. Idempotent on gatewayReference.

curl -s -X POST $BRIDGE_URL/v1/wms/wallets/$WALLET_ID/submit-deposit \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{ "gatewayReference": "MPESA-DEF456UVW", "amount": 50000, "fspId": "CLICKPESA", "description": "Top-up" }'

Check the balance and history:

curl -s $BRIDGE_URL/v1/wms/wallets/$WALLET_ID -H "Authorization: Bearer $TOKEN" | jq
curl -s $BRIDGE_URL/v1/wms/wallets/$WALLET_ID/transactions -H "Authorization: Bearer $TOKEN" | jq

Transactions come back as two arrays — use items (the x-bridge view) and avoid fineractItems for now (it’s the raw core-engine data).

Response (transactions)

{
  "items": [
    {
      "id": "3a5e87bb-f073-43c5-a77c-b87e394305fe",
      "walletId": "f029d5af-2dae-4c27-ae86-993e362949ab",
      "type": "topup",
      "status": "completed",
      "amount": "1000.00",
      "currency": "TZS",
      "reference": "COL-738609d8-db35-4329-83e7-360cdd15d83c",
      "externalId": "3",
      "description": "Mobile money deposit",
      "createdAt": "2026-05-21T11:29:52.656Z"
    }
  ],
  "fineractItems": [ /* raw core-engine data — build against items; avoid for now */ ]
}

Escrow: hold and capture

The marketplace pattern — reserve funds, then commit on delivery or release on cancellation.

Reserve (place a hold)

RES=$(curl -s -X POST $BRIDGE_URL/v1/wms/wallets/$WALLET_ID/reserve \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{ "amount": 15000, "currency": "TZS", "reference": "ORDER-2026-001", "description": "Hold for delivery" }')
TX_ID=$(echo $RES | jq -r .transactionId)

Commit (capture) — on delivery

curl -s -X POST $BRIDGE_URL/v1/wms/transactions/$TX_ID/commit \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{ "note": "Merchant confirmed delivery" }'

…or release — on cancellation

curl -s -X POST $BRIDGE_URL/v1/wms/transactions/$TX_ID/release \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{ "reason": "Customer cancelled" }'

BNPL

Combine an escrow down-payment with a loan and auto-sweep repayments.

Build a flow

Open and activate a wallet

Fund it (verified deposit)

Escrow: hold and capture

Next

BNPL

​Open and activate a wallet

​Fund it (verified deposit)

​Escrow: hold and capture

​Next

BNPL

Open and activate a wallet

Fund it (verified deposit)

Escrow: hold and capture

Next