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

# Get Transaction

> Retrieve transaction status for reconciliation or post-timeout verification

<Note>
  This endpoint requires HMAC-SHA256 authentication. See [Authentication](../../docs/terminal-gateway/authentication) for signature computation details.
</Note>

## When to Use This Endpoint

* **After payment timeout** - Check if the payment completed after a 504 response
* **Reconciliation** - Verify transaction status for accounting purposes
* **Status polling** - Check on pending transactions

## Transaction Status Values

| Status               | Description                                                  |
| -------------------- | ------------------------------------------------------------ |
| `PENDING`            | Transaction created, awaiting terminal response              |
| `COMPLETED`          | Transaction completed successfully                           |
| `FAILED`             | Transaction failed (check error details in response)         |
| `CANCELLED`          | Transaction was cancelled                                    |
| `AWAITING_RECONNECT` | Terminal disconnected mid-payment, waiting for reconnection  |
| `VOIDED`             | Payment was voided (terminal reconnected after grace period) |

## Voided Transactions

A transaction may be voided if:

1. Terminal disconnected during payment processing
2. 60-second grace period expired
3. Terminal reconnected with a successful payment result
4. Payment was automatically voided to prevent orphaned charges

Check the `voidedAt` and `voidReason` fields for voided transactions.


## OpenAPI

````yaml api-reference/terminal-gateway/openapi.json GET /v1/transactions/{transactionId}
openapi: 3.1.0
info:
  title: Terminal Gateway HTTP API
  version: 1.0.0
  description: >-
    HTTP API for POS-to-terminal communication. Enables payment processing
    through connected terminals.
  contact:
    name: Modulus Labs Support
    email: support@moduluslabs.io
servers:
  - url: https://your-endpoint.moduluslabs.io
    description: >-
      Your provisioned Terminal Gateway API endpoint. Contact
      support@moduluslabs.io to obtain your URL and credentials.
security:
  - hmacAuth: []
tags:
  - name: Terminals
    description: Terminal discovery and management
  - name: Payments
    description: Payment processing
  - name: Transactions
    description: Transaction status and reconciliation
  - name: Webhooks
    description: Webhook endpoint management for asynchronous payment notifications
paths:
  /v1/transactions/{transactionId}:
    get:
      tags:
        - Transactions
      summary: Get Transaction
      description: >-
        Retrieve the status of a transaction. Useful for reconciliation or
        checking status after a payment timeout.
      operationId: getTransaction
      parameters:
        - name: transactionId
          in: path
          required: true
          description: The transaction ID to query
          schema:
            type: string
          example: TXN-20240115-001
      responses:
        '200':
          description: Transaction details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionRecord'
              example:
                transactionId: TXN-20240115-001
                status: COMPLETED
                request:
                  transactionId: TXN-20240115-001
                  amount: '99.99'
                  currency: USD
                  paymentMethod: CARD
                response:
                  transactionId: TXN-20240115-001
                  status: SUCCESS
                  amount: '99.99'
                  currency: USD
                  paymentMethod: CARD
                  authorizationCode: AUTH123456
                  timestamp: '2024-01-15T10:37:30.000Z'
                createdAt: '2024-01-15T10:37:00.000Z'
                updatedAt: '2024-01-15T10:37:30.000Z'
                completedAt: '2024-01-15T10:37:30.000Z'
                timestamp: '2024-01-15T10:40:00.000Z'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  schemas:
    TransactionRecord:
      type: object
      required:
        - transactionId
        - status
        - request
        - createdAt
        - updatedAt
        - timestamp
      properties:
        transactionId:
          type: string
          description: Unique transaction identifier
        status:
          type: string
          enum:
            - PENDING
            - COMPLETED
            - FAILED
            - CANCELLED
            - AWAITING_RECONNECT
            - VOIDED
          description: Transaction status
        request:
          $ref: '#/components/schemas/PaymentRequest'
        response:
          $ref: '#/components/schemas/PaymentResponse'
        createdAt:
          type: string
          format: date-time
          description: ISO 8601 timestamp of creation
        updatedAt:
          type: string
          format: date-time
          description: ISO 8601 timestamp of last update
        completedAt:
          type: string
          format: date-time
          description: ISO 8601 timestamp of completion
        terminalDeviceId:
          type: string
          description: Stable terminal device identifier
        voidedAt:
          type: string
          format: date-time
          description: ISO 8601 timestamp when payment was voided
        voidReason:
          type: string
          description: Reason for voiding the payment
        timestamp:
          type: string
          format: date-time
          description: ISO 8601 timestamp of this response
    PaymentRequest:
      type: object
      required:
        - amount
        - currency
        - paymentMethod
      properties:
        transactionId:
          type: string
          description: Unique transaction identifier. Auto-generated if not provided.
        amount:
          oneOf:
            - type: string
            - type: number
          description: Payment amount
        currency:
          type: string
          description: ISO 4217 currency code (e.g., USD, EUR, PHP)
        paymentMethod:
          type: string
          enum:
            - CARD
            - CASH
            - MOBILE
            - OTHER
          description: Payment method
        webhookMode:
          type: boolean
          default: false
          description: >-
            When true, disables 90-second long-polling and returns 202 Accepted
            immediately. Payment result will be delivered via webhook. Requires
            at least one webhook endpoint configured.
        products:
          type: array
          description: Array of products in the transaction
          items:
            $ref: '#/components/schemas/Product'
        customerInfo:
          $ref: '#/components/schemas/CustomerInfo'
        metadata:
          type: object
          description: Custom key-value pairs for your use
          additionalProperties: true
    PaymentResponse:
      type: object
      required:
        - transactionId
        - status
        - amount
        - currency
        - paymentMethod
        - timestamp
      properties:
        transactionId:
          type: string
          description: Transaction identifier
        status:
          type: string
          enum:
            - SUCCESS
            - FAILED
            - PENDING
            - CANCELLED
          description: Payment status
        amount:
          oneOf:
            - type: string
            - type: number
          description: Payment amount
        currency:
          type: string
          description: Currency code
        paymentMethod:
          type: string
          description: Payment method used
        authorizationCode:
          type: string
          description: Authorization code from payment processor (success only)
        errorCode:
          type: string
          description: Error code if status is FAILED
        errorMessage:
          type: string
          description: Human-readable error message if status is FAILED
        receiptData:
          type: string
          description: Opaque receipt data from terminal
        timestamp:
          type: string
          format: date-time
          description: ISO 8601 timestamp of when the payment was processed
        metadata:
          type: object
          description: Custom metadata returned from the original request
          additionalProperties: true
    Error:
      type: object
      required:
        - error
        - timestamp
      properties:
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
              description: Error code
            message:
              type: string
              description: Human-readable error message
            details:
              type: object
              description: Additional error details
              additionalProperties: true
        timestamp:
          type: string
          format: date-time
          description: ISO 8601 timestamp
        requestId:
          type: string
          description: Request identifier for debugging
        transactionId:
          type: string
          description: Transaction ID if applicable
    Product:
      type: object
      required:
        - id
        - name
        - price
        - quantity
      properties:
        id:
          type: string
          description: Product identifier
        name:
          type: string
          description: Product name
        price:
          oneOf:
            - type: string
            - type: number
          description: Unit price
        quantity:
          type: number
          description: Quantity
        category:
          type: string
          description: Product category
        sku:
          type: string
          description: Stock keeping unit
        brand:
          type: string
          description: Brand name
        tax:
          type: number
          description: Tax amount
        discount:
          type: number
          description: Discount amount
    CustomerInfo:
      type: object
      properties:
        customerId:
          type: string
          description: Customer identifier
        email:
          type: string
          format: email
          description: Customer email address
        phone:
          type: string
          description: Customer phone number
  responses:
    Unauthorized:
      description: Authentication failed
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            unauthorized:
              summary: Invalid API key
              value:
                error:
                  code: UNAUTHORIZED
                  message: Missing or invalid API key
                timestamp: '2024-01-15T10:40:00.000Z'
            invalidSignature:
              summary: Invalid signature
              value:
                error:
                  code: INVALID_SIGNATURE
                  message: HMAC signature verification failed
                timestamp: '2024-01-15T10:40:00.000Z'
            timestampExpired:
              summary: Timestamp expired
              value:
                error:
                  code: TIMESTAMP_EXPIRED
                  message: Request timestamp outside 5-minute window
                timestamp: '2024-01-15T10:40:00.000Z'
    Forbidden:
      description: Access denied
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: GROUP_MISMATCH
              message: Resource belongs to a different group
            timestamp: '2024-01-15T10:40:00.000Z'
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            terminalNotFound:
              summary: Terminal not found
              value:
                error:
                  code: TERMINAL_NOT_FOUND
                  message: Terminal not found or offline
                timestamp: '2024-01-15T10:40:00.000Z'
            transactionNotFound:
              summary: Transaction not found
              value:
                error:
                  code: TRANSACTION_NOT_FOUND
                  message: Transaction not found
                timestamp: '2024-01-15T10:40:00.000Z'
    InternalError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: INTERNAL_ERROR
              message: Unexpected server error
            timestamp: '2024-01-15T10:40:00.000Z'
  securitySchemes:
    hmacAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: >-
        HMAC-SHA256 authentication. Requires three headers: x-api-key (your API
        key), x-timestamp (ISO 8601 timestamp), and x-signature (Base64-encoded
        HMAC-SHA256 signature). See Authentication documentation for signature
        computation.

````