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

# Get merchant transaction history

> Retrieve ledger transactions for the authenticated merchant. Accessible to `merchant` role users (scoped to their own `merchant_id` from the JWT) and `admin` role users (who must supply `?merchant_id=` to specify which merchant). Proxies to the internal ledger service.



## OpenAPI

````yaml /swagger.json get /merchant/api/v1/transactions
openapi: 3.0.3
info:
  title: Merchant API
  description: >-
    API for merchants to create and manage payment intents, POS counters, and
    transaction history in the FEX Payment Platform. Authentication uses
    Keycloak JWT (human merchants via password flow, POS terminals via client
    credentials).
  version: 1.0.0
  contact:
    name: FEX Payments Platform
servers:
  - url: http://api-sandbox.fexpayments.com
    description: Merchant API sandbox server
security: []
tags:
  - name: Payment Intents
    description: Create and manage payment intents
  - name: Counters
    description: >-
      POS terminal (counter) management — each counter has its own Keycloak
      client credentials and webhook endpoint
  - name: Admin
    description: Back-office endpoints restricted to platform admin role (`admin`)
  - name: Public
    description: Public endpoints accessible without authentication (for QR code payments)
  - name: Onboarding
    description: Merchant registration — requires platform admin JWT (realm role `admin`)
paths:
  /merchant/api/v1/transactions:
    get:
      tags:
        - Admin
      summary: Get merchant transaction history
      description: >-
        Retrieve ledger transactions for the authenticated merchant. Accessible
        to `merchant` role users (scoped to their own `merchant_id` from the
        JWT) and `admin` role users (who must supply `?merchant_id=` to specify
        which merchant). Proxies to the internal ledger service.
      parameters:
        - name: page
          in: query
          description: 'Page number (default: 1)'
          schema:
            type: integer
            minimum: 1
            default: 1
        - name: limit
          in: query
          description: 'Items per page (default: 20, max: 100)'
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
      responses:
        '200':
          description: Paginated transaction list
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  merchant_id:
                    type: string
                    format: uuid
                    example: 74815c83-e47b-4dc5-aefe-abe4484dd280
                  transactions:
                    type: array
                    items:
                      $ref: '#/components/schemas/LedgerTransaction'
                  page:
                    type: integer
                    example: 1
                  limit:
                    type: integer
                    example: 20
                  total:
                    type: integer
                    example: 47
                  total_pages:
                    type: integer
                    example: 3
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: Forbidden — platform admin must supply ?merchant_id= query param
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                error: Merchant identity not found in token
        '500':
          $ref: '#/components/responses/InternalError'
      security:
        - BearerAuth: []
components:
  schemas:
    LedgerTransaction:
      type: object
      description: A ledger transaction record from the ledger service
      properties:
        transaction_id:
          type: string
          format: uuid
          example: 550e8400-e29b-41d4-a716-446655440000
        transaction_type:
          type: string
          enum:
            - deposit
            - withdrawal
            - transfer
            - payment
            - refund
            - fee
            - reversal
          example: payment
          description: >-
            Merchant accounts receive `payment` type transactions when customers
            pay
        status:
          type: string
          enum:
            - pending
            - processing
            - completed
            - failed
            - reversed
          example: completed
        amount:
          type: string
          example: '49.99'
          description: Decimal amount as string for precision
        currency:
          type: string
          example: USD
        from_account_id:
          type: string
          format: uuid
          description: Source wallet (user who paid)
        to_account_id:
          type: string
          format: uuid
          description: Destination account (merchant wallet)
        description:
          type: string
          example: Payment to Whole Foods Market
        metadata:
          type: object
          description: Arbitrary metadata, e.g. `payment_intent_id`
          example:
            payment_intent_id: a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11
        created_at:
          type: string
          format: date-time
        completed_at:
          type: string
          format: date-time
    ErrorResponse:
      type: object
      properties:
        success:
          type: boolean
          example: false
        error:
          type: string
          example: Invalid request body
      required:
        - success
        - error
  responses:
    Unauthorized:
      description: Unauthorized — missing or invalid JWT
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            success: false
            error: Unauthorized
    InternalError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            success: false
            error: Failed to create payment intent
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        Keycloak JWT. Roles: `admin` (platform admin — can register merchants,
        act on behalf of any merchant), `merchant` (dashboard user — scoped to
        their own `merchant_id` via user attribute mapper), POS terminals use
        client credentials flow with `merchant_id` injected via protocol mapper.

````