GET /api/wallets/:walletId — fetch a single wallet

Retrieve a wallet by ID including its virtual account details, API key prefixes, and associated merchants. Useful for displaying wallet configuration.

Fetch the full configuration of a single wallet by its ID. This endpoint returns the wallet’s spend controls, expiry, virtual account details, and any API keys associated with it. Note that API key fullKey values are never returned here — only the key prefix is included so you can identify which key is which without exposing secrets.

Endpoint

GET /api/wallets/:walletId

Authentication

Requires a valid Session JWT in the Authorization header.

Authorization: Bearer <session_jwt>

---

Path Parameters

walletId · string · required

The UUID of the wallet to retrieve. Returned as data.wallet.id when the wallet was created.

---

Response 200 OK

The response envelope contains success: true and a data object with the wallet, its linked virtual account, associated API key prefixes, and merchant records.

success · boolean

Always true for a successful response.

data · object

Container for the wallet and its associated resources.

Show data fields

data.wallet · object

The wallet configuration object.

Show wallet fields

data.wallet.id · string

Unique wallet UUID.

data.wallet.name · string

Human-readable wallet label.

data.wallet.userId · string

UUID of the user who owns this wallet.

data.wallet.businessId · string | null

The associated business ID, or null if not linked to a business account.

data.wallet.balance · integer

Current wallet balance in kobo.

data.wallet.spendLimitPerTx · integer

Per-transaction spend cap, in kobo.

data.wallet.spendLimitPeriod · integer

Rolling-period cumulative spend cap, in kobo.

data.wallet.periodWindowDays · integer

Length of the rolling spend window, in days.

data.wallet.expiry · string

ISO 8601 datetime at which the wallet deactivates.

data.wallet.expiresAt · string | null

Resolved expiry datetime used internally.

data.wallet.useAllowlist · boolean

Whether merchant-allowlist enforcement is active for this wallet.

data.wallet.merchantAllowlist · string[]

List of permitted merchant names. Empty array when useAllowlist is false.

data.wallet.status · string

Wallet lifecycle status (e.g. "ACTIVE").

data.wallet.createdAt · string

ISO 8601 timestamp of wallet creation.

data.wallet.updatedAt · string

ISO 8601 timestamp of the most recent update.

data.virtualAccount · object

The virtual bank account linked to this wallet.

Show virtualAccount fields

data.virtualAccount.id · string

Virtual account UUID.

data.virtualAccount.walletId · string

The wallet this virtual account is linked to.

data.virtualAccount.accountNumber · string

10-digit Nigerian bank account number.

data.virtualAccount.accountName · string

Account name as displayed on transfers.

data.virtualAccount.bankName · string

Issuing bank name.

data.virtualAccount.providerRef · string

Provider-assigned reference for this virtual account.

data.virtualAccount.createdAt · string

ISO 8601 timestamp of virtual account creation.

data.apiKeys · object[]

All API keys associated with this wallet. Only the key prefix is returned — fullKey is never exposed after initial creation.

Show apiKey fields

data.apiKeys[].id · string

API key UUID.

data.apiKeys[].keyPrefix · string

The prefix characters of the key, safe to display in your UI for identification.

data.apiKeys[].createdAt · string

ISO 8601 timestamp of when this key was issued.

data.merchants · object[]

Merchant records that have been associated with this wallet through transactions.

Show merchant fields

data.merchants[].id · string

Internal merchant UUID.

data.merchants[].name · string

Merchant name as reported at the point of authorisation.

Example Response

{
  "success": true,
  "data": {
    "wallet": {
      "id": "wlt_f7e6d5c4-b3a2-4190-8fed-cba987654321",
      "name": "Procurement Agent — Q3 2025",
      "userId": "usr_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "businessId": null,
      "balance": 1250000,
      "spendLimitPerTx": 500000,
      "spendLimitPeriod": 2000000,
      "periodWindowDays": 30,
      "expiry": "2027-01-01T00:00:00.000Z",
      "expiresAt": null,
      "useAllowlist": true,
      "merchantAllowlist": ["AWS", "Vercel", "Stripe"],
      "status": "ACTIVE",
      "createdAt": "2025-07-15T09:41:02Z",
      "updatedAt": "2025-07-15T09:41:02Z"
    },
    "virtualAccount": {
      "id": "va-uuid",
      "walletId": "wlt_f7e6d5c4-b3a2-4190-8fed-cba987654321",
      "accountNumber": "9876543210",
      "accountName": "Procurement Agent — Q3 2025",
      "bankName": "Providus Bank",
      "providerRef": "mock-ref-abc123",
      "createdAt": "2025-07-15T09:41:02Z"
    },
    "apiKeys": [
      {
        "id": "key_aabbccdd-eeff-0011-2233-445566778899",
        "keyPrefix": "ax_live_9f2a3b",
        "createdAt": "2025-07-15T09:41:02Z"
      }
    ],
    "merchants": [
      {
        "id": "mrc_99887766-5544-3322-1100-ffeeddccbbaa",
        "name": "AWS"
      },
      {
        "id": "mrc_aabbccdd-1122-3344-5566-778899aabbcc",
        "name": "Vercel"
      }
    ]
  }
}

---

Error Responses

Status	Code	Description
401	UNAUTHORIZED	Missing or invalid Session JWT.
404	WALLET_NOT_FOUND	No wallet exists with the supplied walletId.

{
  "error": {
    "code": "WALLET_NOT_FOUND",
    "message": "No wallet found with ID wlt_f7e6d5c4-b3a2-4190-8fed-cba987654321."
  }
}