GET /api/wallets/:walletId/transactions — transaction history

Fetch paginated transaction records for a wallet, sorted newest first. Includes both approved and blocked attempts with decision reason fields.

Retrieve the full transaction history for a wallet, paginated and sorted newest-first. Every authorisation attempt is recorded — including those that were blocked by spend controls or the merchant allowlist. The decision field tells you the outcome, and blockReason explains why a transaction was rejected, making it straightforward to surface this information in a dashboard or agent audit log.

Endpoint

GET /api/wallets/:walletId/transactions

Authentication

Requires a valid Session JWT in the Authorization header.

Authorization: Bearer <session_jwt>

---

Path Parameters

walletId · string · required

The UUID of the wallet whose transaction history you want to retrieve.

---

Query Parameters

page · integer · default: "1"

The page number to retrieve. Pages are 1-indexed.

pageSize · integer · default: "10"

The number of records to return per page.

---

Response 200 OK

The response envelope contains success: true, a data array of transaction records, and a pagination object with totals.

success · boolean

Always true for a successful response.

data · object[]

Array of transaction records for the requested page, sorted newest-first.

Show transaction fields

data[].id · string

Unique transaction UUID.

data[].walletId · string

The wallet this transaction belongs to.

data[].amount · integer

Transaction amount in kobo.

data[].merchant · string

Merchant identifier at the point of authorisation.

data[].merchantName · string

Human-readable merchant name as reported by the payment terminal.

data[].recipientAccountNo · string

Recipient bank account number for this transaction.

data[].recipientBankCode · string

Bank code for the recipient account.

data[].decision · string

Authorisation outcome. One of:

• "approved" — the transaction was approved and funds were reserved.
• "blocked" — the transaction was rejected by a spend control or allowlist rule.

data[].reason · string | null

Human-readable explanation of the decision outcome. null for approved transactions with no additional context.

data[].blockReason · string | null

Structured reason code for why the transaction was blocked. null for approved transactions. Possible values include:

• "exceeds_per_tx_limit" — amount exceeded spendLimitPerTx.
• "exceeds_period_limit" — would exceed spendLimitPeriod for the current window.
• "merchant_not_in_allowlist" — merchant is not in merchantAllowlist.
• "wallet_expired" — the wallet’s expiry has passed.

data[].createdAt · string

ISO 8601 timestamp of the authorisation attempt.

data[].auditEvents · object[]

Array of audit event records associated with this transaction, for compliance and debugging purposes.

pagination · object

Metadata about the paginated result set.

Show pagination fields

pagination.page · integer

The current page number.

pagination.pageSize · integer

The number of records per page.

pagination.totalCount · integer

Total number of transaction records across all pages.

pagination.totalPages · integer

Total number of pages at the current pageSize.

Example Response

{
  "success": true,
  "data": [
    {
      "id": "txn_d4e5f6a7-b8c9-4012-8def-012345678901",
      "walletId": "wlt_f7e6d5c4-b3a2-4190-8fed-cba987654321",
      "amount": 345000,
      "merchant": "aws",
      "merchantName": "AWS",
      "recipientAccountNo": "0123456789",
      "recipientBankCode": "058",
      "decision": "approved",
      "reason": null,
      "blockReason": null,
      "createdAt": "2025-07-15T11:03:44Z",
      "auditEvents": []
    },
    {
      "id": "txn_e5f6a7b8-c9d0-4123-9ef0-123456789012",
      "walletId": "wlt_f7e6d5c4-b3a2-4190-8fed-cba987654321",
      "amount": 750000,
      "merchant": "rackspace",
      "merchantName": "Rackspace",
      "recipientAccountNo": "0987654321",
      "recipientBankCode": "011",
      "decision": "blocked",
      "reason": "Merchant not in allowlist",
      "blockReason": "merchant_not_in_allowlist",
      "createdAt": "2025-07-15T10:58:17Z",
      "auditEvents": []
    }
  ],
  "pagination": {
    "page": 1,
    "pageSize": 10,
    "totalCount": 42,
    "totalPages": 5
  }
}

Understanding decision and blockReason

decision	blockReason	What happened
approved	null	Payment went through. Funds were debited from the wallet.
blocked	exceeds_per_tx_limit	The requested amount was above spendLimitPerTx.
blocked	exceeds_period_limit	Approving this transaction would have pushed cumulative spend over spendLimitPeriod for the current rolling window.
blocked	merchant_not_in_allowlist	useAllowlist is true and the merchant name was not found in merchantAllowlist.
blocked	wallet_expired	The wallet’s expiry timestamp had already passed when the authorisation was attempted.

---

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."
  }
}