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

# List Transactions

> Retrieve a paginated list of transactions for your account.

Retrieve and filter your full transaction history. Results include an aggregate overview independent of pagination.

## Overview object

Every list response includes an `overview` with counts for the **full filtered set** — not just the current page:

```json theme={null}
{
  "overview": {
    "total": 20,
    "completed": 15,
    "failed": 5,
    "pending": 0
  }
}
```

Counts respect all query filters (`status`, `type`, `from`, `to`, `channelId`, `amountMin`, `amountMax`, `q`) but ignore `cursor` — the numbers stay consistent across pages.

## Transaction fee field

Each transaction item includes a `transactionFee` field (merchant API) / `transaction_fee` field (developer API):

| Status      | `transaction_fee` value                |
| ----------- | -------------------------------------- |
| `PENDING`   | Actual fee charged from service wallet |
| `SUCCESS`   | Actual fee charged from service wallet |
| `FAILED`    | `0`                                    |
| `CANCELLED` | `0`                                    |
| `EXPIRED`   | `0`                                    |

The fee is `0` when no pricing rule is configured for your account.

## Pagination

Transactions return newest first. Pass `nextCursor` from the previous response to fetch the next page.

```bash theme={null}
# Page 1
curl "https://api.palpluss.com/v1/transactions?limit=20" \
  -u "$PALPLUSS_API_KEY:"

# Page 2
curl "https://api.palpluss.com/v1/transactions?limit=20&cursor=eyJpZCI6ImZhOThhNTc3In0=" \
  -u "$PALPLUSS_API_KEY:"
```

`nextCursor: null` means you have reached the last page.

## Filtering

Combine `status` and `type` to narrow results:

```bash theme={null}
# All successful STK payments
curl "https://api.palpluss.com/v1/transactions?type=STK&status=SUCCESS" \
  -u "$PALPLUSS_API_KEY:"

# All pending B2C payouts
curl "https://api.palpluss.com/v1/transactions?type=B2C&status=PENDING" \
  -u "$PALPLUSS_API_KEY:"
```


## OpenAPI

````yaml GET /transactions
openapi: 3.1.0
info:
  title: PalPluss API
  version: '1.0'
  summary: >-
    Payment infrastructure for Kenya — STK Push, B2C payouts, and wallet
    management.
  description: >
    The PalPluss API gives developers programmatic access to M-Pesa STK Push
    collections,

    B2C payouts, service wallet top-ups, and payment channel management.


    **Base URL:** `https://api.palpluss.com/v1`


    All requests must be authenticated with an API key using HTTP Basic Auth.

    All responses are wrapped in a standard envelope. See [Errors](#tag/errors)
    for error codes.


    Amounts are in **KES (Kenyan Shillings)** unless stated otherwise. Phone
    numbers

    are normalized to the `254XXXXXXXXX` format internally.
  contact:
    name: PalPluss Developer Support
    email: developer@palpluss.com
    url: https://palpluss.com/developers
servers:
  - url: https://api.palpluss.com/v1
    description: Production
  - url: https://sandbox.palpluss.com/v1
    description: Sandbox
security:
  - BasicAuth: []
tags:
  - name: STK Push
    description: >
      Initiate M-Pesa STK Push payment prompts. The customer receives a PIN
      prompt on their

      phone and confirms payment. PalPluss delivers the result asynchronously to
      your webhook URL.
  - name: Transactions
    description: >-
      Query the status of any transaction by ID, or list all transactions with
      filters.
  - name: B2C Payouts
    description: >
      Send money directly to a customer's M-Pesa number. Requires KYC approval
      and sufficient

      B2C wallet balance. Payouts are processed asynchronously.
  - name: Service Wallet
    description: >
      The service wallet holds pre-funded tokens used to pay PalPluss
      transaction fees.

      Top up via STK Push. Balance is deducted with each API call.
  - name: Payment Channels
    description: >
      Payment channels represent the M-Pesa shortcodes (Paybill / Till)
      associated with your

      account. Channels are used to route STK Push requests to a specific
      shortcode.
paths:
  /transactions:
    get:
      tags:
        - Transactions
      summary: List transactions
      description: |
        Returns a paginated list of transactions for your account, newest first.
        Use `cursor` from the previous response to fetch the next page.
      operationId: listTransactions
      parameters:
        - name: limit
          in: query
          description: Number of records per page (1–100, default 20).
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
        - name: cursor
          in: query
          description: Pagination cursor from the previous response `nextCursor` field.
          schema:
            type: string
        - name: status
          in: query
          description: Filter by transaction status.
          schema:
            $ref: '#/components/schemas/TransactionStatus'
        - name: type
          in: query
          description: Filter by transaction type.
          schema:
            $ref: '#/components/schemas/TransactionType'
      responses:
        '200':
          description: Paginated list of transactions.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/SuccessEnvelope'
                  - type: object
                    properties:
                      data:
                        type: object
                        properties:
                          overview:
                            type: object
                            description: >-
                              Aggregate counts for the current filter set
                              (ignores cursor).
                            properties:
                              total:
                                type: integer
                                description: >-
                                  Total number of transactions matching the
                                  applied filters.
                              completed:
                                type: integer
                                description: Number of transactions with status `SUCCESS`.
                              failed:
                                type: integer
                                description: Number of transactions with status `FAILED`.
                              pending:
                                type: integer
                                description: Number of transactions with status `PENDING`.
                          items:
                            type: array
                            items:
                              $ref: '#/components/schemas/Transaction'
                          nextCursor:
                            type: string
                            nullable: true
                            description: >-
                              Pass this value as `cursor` to fetch the next
                              page. `null` means no more pages.
              examples:
                success:
                  value:
                    success: true
                    data:
                      overview:
                        total: 20
                        completed: 15
                        failed: 5
                        pending: 0
                      items:
                        - transactionId: fa98a577-95ea-4a8f-8467-1fbe74f5d6f4
                          type: STK
                          status: SUCCESS
                          amount: 1000
                          currency: KES
                          phone: '254712345678'
                          accountReference: INV-2024-001
                          createdAt: '2026-03-01T08:00:00.000Z'
                          updatedAt: '2026-03-01T08:01:30.000Z'
                      nextCursor: eyJpZCI6ImZhOThhNTc3In0=
                    requestId: c1b2a3d4-0000-0000-0000-000000000000
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  schemas:
    TransactionStatus:
      type: string
      enum:
        - PENDING
        - PROCESSING
        - SUCCESS
        - FAILED
        - REVERSED
        - CANCELLED
      description: |
        - `PENDING` — Awaiting customer action or provider response
        - `PROCESSING` — Provider accepted; waiting for final confirmation
        - `SUCCESS` — Completed successfully
        - `FAILED` — Transaction failed (provider declined or timeout)
        - `REVERSED` — Successfully reversed (wallet credited back)
        - `CANCELLED` — Cancelled before processing
    TransactionType:
      type: string
      enum:
        - STK
        - B2C
      description: |
        - `STK` — M-Pesa STK Push collection
        - `B2C` — Business to Customer payout
    SuccessEnvelope:
      type: object
      required:
        - success
        - data
        - requestId
      properties:
        success:
          type: boolean
          example: true
        data:
          type: object
          description: Response payload. Shape varies by endpoint.
        requestId:
          type: string
          format: uuid
          description: Unique identifier for this API request. Include in support tickets.
          example: c1b2a3d4-e5f6-7890-abcd-ef1234567890
    Transaction:
      type: object
      properties:
        transactionId:
          type: string
          format: uuid
          description: Unique transaction identifier.
        tenantId:
          type: string
          format: uuid
        type:
          $ref: '#/components/schemas/TransactionType'
        status:
          $ref: '#/components/schemas/TransactionStatus'
        amount:
          type: number
          format: decimal
          description: Transaction amount in KES.
          example: 1000
        currency:
          type: string
          example: KES
        phone:
          type: string
          description: Customer phone in `254XXXXXXXXX` format.
          example: '254712345678'
        channelId:
          type: string
          format: uuid
          nullable: true
        accountReference:
          type: string
          nullable: true
          description: Reference you supplied (STK) or external reference (B2C).
          example: INV-2024-001
        transactionDesc:
          type: string
          nullable: true
          example: 'Payment for invoice #2024-001'
        provider:
          type: string
          nullable: true
          example: m-pesa
        providerRequestId:
          type: string
          nullable: true
          example: 29115-34620561-1
        providerCheckoutId:
          type: string
          nullable: true
          example: ws_CO_191220191020363925
        resultCode:
          type: string
          nullable: true
          description: M-Pesa result code. `"0"` = success.
          example: '0'
        resultDesc:
          type: string
          nullable: true
          example: The service request is processed successfully.
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    ErrorEnvelope:
      type: object
      required:
        - success
        - error
        - requestId
      properties:
        success:
          type: boolean
          example: false
        error:
          type: object
          required:
            - message
            - code
          properties:
            message:
              type: string
              description: Human-readable error description.
              example: Invalid API key
            code:
              type: string
              description: Machine-readable error code.
              example: INVALID_API_KEY
            details:
              type: object
              description: Optional structured details about the error.
        requestId:
          type: string
          format: uuid
          example: c1b2a3d4-e5f6-7890-abcd-ef1234567890
  responses:
    Unauthorized:
      description: Missing, invalid, or revoked API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
          examples:
            invalid_key:
              value:
                success: false
                error:
                  message: Invalid or revoked API key.
                  code: INVALID_API_KEY
                  details: {}
                requestId: a1b2c3d4-0000-0000-0000-000000000000
    RateLimited:
      description: Rate limit exceeded — 60 requests per minute per API key.
      headers:
        x-ratelimit-limit:
          schema:
            type: integer
          description: Maximum requests per minute.
        x-ratelimit-remaining:
          schema:
            type: integer
          description: Remaining requests in the current window.
        x-ratelimit-reset:
          schema:
            type: integer
          description: Unix timestamp when the window resets.
        Retry-After:
          schema:
            type: integer
          description: Seconds to wait before retrying.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
          examples:
            rate_limited:
              value:
                success: false
                error:
                  message: Rate limit exceeded. Try again in 12 seconds.
                  code: RATE_LIMIT_EXCEEDED
                  details:
                    limit: 60
                    remaining: 0
                    resetInSeconds: 12
                requestId: a1b2c3d4-0000-0000-0000-000000000000
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic
      description: >
        Paste your PalPluss API key in the **username** field and leave the

        **password** field empty — it is ignored.


        Get your key from **console → Settings → API Keys** (starts with
        `pk_live_` or `pk_test_`).


        In your own code, send the key directly:

        `Authorization: Basic YOUR_API_KEY`

````