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

# Get transaction by ID or merchantTransactionId

> Retrieve a single transaction by either its Fingo transaction ID or your merchant transaction ID. Provide exactly one of the two parameters.



## OpenAPI

````yaml api-reference/openapi.json get /v1/transaction
openapi: 3.1.0
info:
  title: Fingo Pay API
  description: >-
    Fingo Pay's unified payments API for M-Pesa C2B (STK Push), B2C
    disbursements, B2B transfers, bank transfers, account balances, and
    transactions.
  version: 1.0.0
servers:
  - url: https://api.fingopay.io
security:
  - bearerAuth: []
tags:
  - name: Payments
    description: Receive payments from customers
  - name: Payouts
    description: Send payments to recipients
  - name: Accounts
    description: Account balances and management
  - name: Transactions
    description: Transaction history and lookup
  - name: Verification
    description: Pre-transaction verification and lookup
  - name: Webhooks
    description: Webhook event notifications
paths:
  /v1/transaction:
    get:
      tags:
        - Transactions
      summary: Get transaction by ID or merchantTransactionId
      description: >-
        Retrieve a single transaction by either its Fingo transaction ID or your
        merchant transaction ID. Provide exactly one of the two parameters.
      operationId: getTransaction
      parameters:
        - name: transactionId
          in: query
          required: false
          description: Fingo transaction ID (e.g., txn_01j7b6f9p5y9h).
          schema:
            type: string
        - name: merchantTransactionId
          in: query
          required: false
          description: Your merchant transaction ID.
          schema:
            type: string
      responses:
        '200':
          description: Transaction fetched successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: success
                  message:
                    type: string
                    example: Transaction fetched
                  data:
                    $ref: '#/components/schemas/Transaction'
        '400':
          $ref: '#/components/responses/ErrorResponse'
        '401':
          $ref: '#/components/responses/ErrorResponse'
        '404':
          $ref: '#/components/responses/ErrorResponse'
components:
  schemas:
    Transaction:
      type: object
      description: Transaction object returned in API responses.
      properties:
        publicId:
          type: string
          example: txn_01j7b6f9p5y9h
          description: Fingo transaction ID
        merchantTransactionId:
          type:
            - string
            - 'null'
          example: mtx_123
          description: Your merchant reference
        status:
          type: string
          enum:
            - pending
            - completed
            - failed
            - settled
            - initiated
            - rejected
          example: completed
        message:
          type:
            - string
            - 'null'
          example: Payment completed successfully
        amount:
          type:
            - integer
            - 'null'
          example: 10000
          description: Transaction amount in smallest unit
        chargedAmount:
          type:
            - integer
            - 'null'
          example: 10000
          description: Amount charged to customer
        currency:
          type: string
          example: KES
        accountType:
          type: string
          enum:
            - collections
            - payouts
          example: collections
        type:
          type: string
          enum:
            - charge
            - transfer
            - payment
            - settlement
            - airtime
            - reversal
            - bank_deposit
            - bank_withdrawal
          example: charge
        paymentMethod:
          type: string
          enum:
            - mobile_money
            - bank
          example: mobile_money
        processor:
          type: string
          enum:
            - mpesa
            - choicebank
          example: mpesa
        processorReference:
          type:
            - string
            - 'null'
          example: ODI31ABC123
          description: Reference from payment processor
        phoneNumber:
          type:
            - string
            - 'null'
          example: '+254712345678'
        narration:
          type:
            - string
            - 'null'
          example: 'Invoice #1234'
        customerId:
          type:
            - string
            - 'null'
          description: Internal customer ID
        customer:
          type:
            - object
            - 'null'
          description: Customer details if available
        fees:
          type:
            - integer
            - 'null'
          example: 100
          description: Total fees charged (in smallest unit)
        metadata:
          type:
            - object
            - 'null'
          description: >-
            Metadata echoed from the original request. Can include enterprise
            keys such as subMerchantDetails.
          additionalProperties: true
        subMerchantId:
          type:
            - string
            - 'null'
          description: Organization-scoped sub-merchant identifier supplied in the request.
        subMerchantDetails:
          oneOf:
            - $ref: '#/components/schemas/SubMerchantDetails'
            - type: 'null'
          description: Optional sub-merchant enrichment details when available.
        createdAt:
          type: integer
          example: 1723717200000
          description: Unix timestamp in milliseconds
        updatedAt:
          type: integer
          example: 1723717320000
          description: Unix timestamp in milliseconds
      required:
        - publicId
        - status
        - currency
        - accountType
        - type
        - paymentMethod
        - processor
        - createdAt
        - updatedAt
    SubMerchantDetails:
      type: object
      description: >-
        Optional sub-merchant enrichment details used when creating or updating
        a sub-merchant reference from API traffic.
      properties:
        name:
          type: string
          description: Display/trading name for the sub-merchant.
          example: Nairobi West Branch
        legalName:
          type: string
          description: Registered legal name for the sub-merchant.
          example: Nairobi West Branch Limited
        businessType:
          type: string
          description: Optional business entity type.
          example: Limited Liability Company
        email:
          type: string
          format: email
          description: Optional sub-merchant contact email.
        phoneNumber:
          type: string
          description: Optional sub-merchant contact phone number.
          example: '+254712345678'
        businessCertNo:
          type: string
          description: Optional business registration certificate number.
        taxId:
          type: string
          description: Optional tax identifier (for example KRA PIN).
        economicSector:
          type: string
          description: Optional economic sector reference.
        riskLevel:
          type: string
          enum:
            - low
            - medium
            - high
          description: >-
            Optional risk tier used for reconciliation and post-transaction
            controls.
      additionalProperties: false
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            type:
              type: string
              enum:
                - invalid_request_error
                - authentication_error
                - rate_limit_error
                - api_error
                - idempotency_error
                - not_found_error
                - conflict_error
              description: Error category
            code:
              type: string
              enum:
                - missing_parameter
                - invalid_parameter
                - unauthorized
                - forbidden
                - too_many_requests
                - internal_error
                - duplicate
                - resource_not_found
                - missing_header
                - validation_error
              description: Specific error code
            message:
              type: string
              description: Human-readable error message
            param:
              type:
                - string
                - 'null'
              description: The parameter that caused the error, if applicable
            requestId:
              type: string
              description: Request ID for support reference
          required:
            - type
            - code
            - message
      required:
        - error
  responses:
    ErrorResponse:
      description: Error response
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Use your API key as a Bearer token. Example: Authorization: Bearer
        sk_live_...

````