> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xbridge.co.tz/llms.txt
> Use this file to discover all available pages before exploring further.

# Wallets

> Open a wallet, fund it with a verified deposit, and run an escrow hold-and-capture.

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.

<Note>Requires an active customer — see [Customer onboarding](/recipes/kyc-onboarding). Bearer token from [`/generate-token`](/authentication); re-token on `401`.</Note>

## Open and activate a wallet

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

<Steps>
  <Step title="Open">
    ```bash theme={null}
    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.
  </Step>

  <Step title="Approve + activate">
    ```bash theme={null}
    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 '{}'
    ```
  </Step>
</Steps>

## Fund it (verified deposit)

When your gateway has collected money (see [Collections](/recipes/collections)), record it. Bridge verifies the deposit on the gateway before crediting. Idempotent on `gatewayReference`.

```bash theme={null}
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:

```bash theme={null}
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).

```json Response (transactions) theme={null}
{
  "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.

<Steps>
  <Step title="Reserve (place a hold)">
    ```bash theme={null}
    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)
    ```
  </Step>

  <Step title="Commit (capture) — on delivery">
    ```bash theme={null}
    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" }'
    ```
  </Step>

  <Step title="…or release — on cancellation">
    ```bash theme={null}
    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" }'
    ```
  </Step>
</Steps>

## Next

<Card title="BNPL" icon="cart-shopping" href="/recipes/bnpl" horizontal>Combine an escrow down-payment with a loan and auto-sweep repayments.</Card>