openapi: "3.0.3"
info:
  title: "MineSec (glue) Transaction Query API"
  description: "External client-facing API for querying transaction records"
  version: "183-20261028-9a02ec5"
servers:
  - url: "https://glue-stage.mspayhub.com"
security:
  - OpenApiBearerAuth: []
tags:
  - name: "Transactions"
    description: "Transaction query operations"
paths:

  /api/v1/pos/transactions:
    get:
      tags:
        - "Transactions"
      summary: "List transactions"
      description: "Get a paginated list of transactions with optional filtering."
      parameters:
        - $ref: "#/components/parameters/XMineSecRequestId"
        - name: "startingAfter"
          in: "query"
          description: "The tranId to query the next page after. Mutually exclusive with endingBefore."
          schema:
            type: "string"
        - name: "endingBefore"
          in: "query"
          description: "The tranId to query the previous page before. Mutually exclusive with startingAfter."
          schema:
            type: "string"
        - name: "limit"
          in: "query"
          description: "Number of results to return per page. Default 10, maximum 2000."
          schema:
            type: "integer"
            default: 10
            maximum: 2000
        - name: "page"
          in: "query"
          description: "Page number for page-based pagination, as an alternative to cursor-based pagination via startingAfter/endingBefore. When used, cursorStarting/cursorEnding in the response will be null."
          schema:
            type: "integer"
        - name: "tranId"
          in: "query"
          description: "MineSec transaction id"
          schema:
            type: "string"
        - name: "srsTranId"
          in: "query"
          description: "SRS tran id (M-prefix)"
          schema:
            type: "string"
        - name: "linkedTranId"
          in: "query"
          description: "Transaction id of the linked/parent transaction, e.g. the original sale for a refund or auth-completion"
          schema:
            type: "string"
        - name: "linkedSrsTranId"
          in: "query"
          description: "SRS tran id (M-prefix) of the linked/parent transaction, e.g. the original sale for a refund or auth-completion"
          schema:
            type: "string"
        - name: "tranTypes"
          in: "query"
          description: "Comma-separated list of transaction types (e.g. SALE, REFUND, AUTH)"
          style: "form"
          explode: false
          schema:
            type: "array"
            items:
              $ref: "#/components/schemas/TranType"
        - name: "tranStatuses"
          in: "query"
          description: "Comma-separated list of transaction statuses"
          style: "form"
          explode: false
          schema:
            type: "array"
            items:
              $ref: "#/components/schemas/TranStatus"
        - name: "minAmount"
          in: "query"
          description: "Minimum transaction amount"
          schema:
            type: "string"
        - name: "maxAmount"
          in: "query"
          description: "Maximum transaction amount"
          schema:
            type: "string"
        - name: "currency"
          in: "query"
          description: "Transaction currency"
          schema:
            type: "string"
        - name: "paymentMethods"
          in: "query"
          description: "Comma-separated list of payment methods (e.g. VISA, MASTERCARD)"
          style: "form"
          explode: false
          schema:
            type: "array"
            items:
              $ref: "#/components/schemas/PaymentMethod"
        - name: "accountBin"
          in: "query"
          description: "First 6 digits of the account"
          schema:
            type: "string"
        - name: "accountLast4"
          in: "query"
          description: "Last 4 digits of the account"
          schema:
            type: "string"
        - name: "sdkId"
          in: "query"
          description: "SDK ID. Also accepts the key deviceId as an alias."
          schema:
            type: "string"
        - name: "posReference"
          in: "query"
          description: "POS reference"
          schema:
            type: "string"
        - name: "trace"
          in: "query"
          description: "Transaction trace number"
          schema:
            type: "string"
        - name: "profileId"
          in: "query"
          description: "Profile ID associated with the transaction"
          schema:
            type: "string"
        - name: "providerReference"
          in: "query"
          description: "Provider reference for the transaction"
          schema:
            type: "string"
        - name: "providerMchId"
          in: "query"
          description: "Provider reference of the merchant id"
          schema:
            type: "string"
        - name: "merchantName"
          in: "query"
          description: "Merchant name (prefix match)"
          schema:
            type: "string"
        - name: "acptId"
          in: "query"
          description: "Acceptance ID linked to the transaction"
          schema:
            type: "string"
        - name: "primaryMid"
          in: "query"
          description: "Primary merchant identifier"
          schema:
            type: "string"
        - name: "primaryTid"
          in: "query"
          description: "Primary terminal identifier"
          schema:
            type: "string"
        - name: "rrn"
          in: "query"
          description: "Retrieval Reference Number (RRN) for the transaction. Also accepts the key acquirerRefNo as an alias."
          schema:
            type: "string"
        - name: "approvalCode"
          in: "query"
          description: "Approval code"
          schema:
            type: "string"
        - name: "batchNo"
          in: "query"
          description: "Batch number associated with the transaction"
          schema:
            type: "string"
        - name: "batchId"
          in: "query"
          description: "Batch ID linked to the transaction"
          schema:
            type: "string"
        - name: "beginTime"
          in: "query"
          description: "Filter transactions starting from this time. Accepts YYYY-MM-DD or full ISO8601 date-time; a date-only value is treated as the start of that day."
          schema:
            type: "string"
            format: "date-time"
        - name: "endTime"
          in: "query"
          description: "Filter transactions up to this time. Accepts YYYY-MM-DD or full ISO8601 date-time; a date-only value is treated as the end of that day."
          schema:
            type: "string"
            format: "date-time"
      responses:
        "200":
          description: "List of transactions retrieved successfully"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CursorPaginatedTransactionExtract"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"

  /api/v1/pos/transactions/{tranId}:
    get:
      tags:
        - "Transactions"
      summary: "Get transaction by ID"
      parameters:
        - $ref: "#/components/parameters/XMineSecRequestId"
        - name: "tranId"
          in: "path"
          required: true
          schema:
            type: "string"
      responses:
        "200":
          description: "Transaction retrieved successfully"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Transaction"
        "404":
          description: "Transaction not found"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"

  /api/v1/pos/transactions/{tranId}/history-tree:
    get:
      tags:
        - "Transactions"
      summary: "Get transaction history tree"
      description: |
        Returns the complete relationship hierarchy (original transaction and its related child
        transactions) that the given transaction belongs to. `tranId` may be the original transaction
        or any child/descendant; the tree always starts from the root transaction.
        The hierarchy, ordering and `treeComplete` flag are returned as-is from the backend.
      parameters:
        - $ref: "#/components/parameters/XMineSecRequestId"
        - name: "tranId"
          in: "path"
          required: true
          schema:
            type: "string"
      responses:
        "200":
          description: "Transaction history tree retrieved successfully"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HistoryTree"
              example:
                selectedTransactionId: "tran_01KF12TA15CPFDW2NKKQDQRJ5F"
                treeComplete: true
                root:
                  tranId: "tran_01KF12TA15CPFDW2NKKQDQRJ5E"
                  linkedTranId: null
                  tranType: "SALE"
                  tranStatus: "APPROVED"
                  amount:
                    value: "100.00"
                    currency: "HKD"
                  createdAt: "2026-01-15T08:30:00Z"
                  updatedAt: "2026-01-15T09:00:00Z"
                  children:
                    - tranId: "tran_01KF12TA15CPFDW2NKKQDQRJ5F"
                      linkedTranId: "tran_01KF12TA15CPFDW2NKKQDQRJ5E"
                      tranType: "REFUND"
                      tranStatus: "APPROVED"
                      amount:
                        value: "30.00"
                        currency: "HKD"
                      createdAt: "2026-01-15T09:00:00Z"
                      updatedAt: null
                      children: []
        "404":
          description: "Transaction not found"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"

  /api/v1/pos/transactions/posReference/{posReference}:
    get:
      tags:
        - "Transactions"
      summary: "Get transaction by POS reference"
      parameters:
        - $ref: "#/components/parameters/XMineSecRequestId"
        - name: "posReference"
          in: "path"
          required: true
          schema:
            type: "string"
      responses:
        "200":
          description: "Transaction retrieved successfully"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Transaction"
        "404":
          description: "Transaction not found for the given POS reference"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"

  /api/v1/pos/transactions/requestId/{requestId}:
    get:
      tags:
        - "Transactions"
      summary: "Get transaction by request ID"
      parameters:
        - $ref: "#/components/parameters/XMineSecRequestId"
        - name: "requestId"
          in: "path"
          required: true
          schema:
            type: "string"
      responses:
        "200":
          description: "Transaction retrieved successfully"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Transaction"
        "404":
          description: "Transaction not found for the given request ID"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"

components:
  securitySchemes:
    OpenApiBearerAuth:
      type: "http"
      scheme: "bearer"
      bearerFormat: "JWT"
      description: "Bearer token authentication for POS API access"
  responses:
    Unauthorized:
      description: "Missing or invalid JWT token"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          example:
            status: 401
            path: "/api/v1/pos/transactions"
            requestId: "req_01KF12TA15CPFDW2NKKQDQRJ5E"
            title: "Unauthorized"
            message: "Token is not valid or has expired"
    Forbidden:
      description: "Insufficient scope in JWT token"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          example:
            status: 403
            path: "/api/v1/pos/transactions"
            requestId: "req_01KF12TA15CPFDW2NKKQDQRJ5E"
            title: "AuthorizationException"
            message: "Insufficient scope: requires pos:transactions"
  parameters:
    XMineSecRequestId:
      name: "x-minesec-request-id"
      in: "header"
      required: false
      description: "Optional request ID for tracing. Accepts ULID or req_ULID format."
      schema:
        type: "string"
        example: "req_01KF12TA15CPFDW2NKKQDQRJ5E"
  schemas:
    # ==================== Common Schemas ====================
    ErrorResponse:
      type: "object"
      properties:
        status:
          type: "integer"
          format: "int32"
        path:
          type: "string"
        requestId:
          type: "string"
        title:
          type: "string"
        message:
          type: "string"
      required:
        - "path"
        - "requestId"
        - "title"
        - "message"
        - "status"
    Amount:
      type: "object"
      properties:
        value:
          type: "string"
          description: "Monetary value as string"
        currency:
          type: "string"
          description: "ISO alpha-3 currency code"
      required:
        - "value"
        - "currency"

    HistoryTree:
      type: "object"
      properties:
        selectedTransactionId:
          type: "string"
          description: "The transaction ID supplied in the request"
        treeComplete:
          type: "boolean"
          description: "false when the backend cannot guarantee the full historical hierarchy"
        root:
          $ref: "#/components/schemas/HistoryTreeNode"
      required:
        - "selectedTransactionId"
        - "treeComplete"
        - "root"
    HistoryTreeNode:
      type: "object"
      properties:
        tranId:
          type: "string"
        linkedTranId:
          type: "string"
          nullable: true
          description: "Parent transaction ID; null for the root transaction"
        tranType:
          $ref: "#/components/schemas/TranType"
        tranStatus:
          $ref: "#/components/schemas/TranStatus"
        amount:
          $ref: "#/components/schemas/Amount"
        createdAt:
          type: "string"
          format: "date-time"
        updatedAt:
          type: "string"
          format: "date-time"
          nullable: true
        children:
          type: "array"
          description: "Child transactions, in backend order"
          items:
            $ref: "#/components/schemas/HistoryTreeNode"
      required:
        - "tranId"
        - "tranType"
        - "tranStatus"
        - "amount"
        - "createdAt"
        - "children"

    # ==================== Enums ====================
    TranType:
      type: "string"
      enum:
        - "SALE"
        - "REFUND"
        - "AUTH"
        - "AUTH_COMP"
        - "DEFERRED_AUTH"
        - "INSTALL"
        - "CASH_IN"
        - "CASH_OUT"
    TranStatus:
      type: "string"
      enum:
        - "PROCESSING"
        - "APPROVED"
        - "DECLINED"
        - "VOIDED"
        - "REVERSED"
        - "AUTH_ONLY"
        - "ADJUSTED"
    PaymentMethod:
      type: "string"
      enum:
        - "VISA"
        - "MASTERCARD"
        - "UNIONPAY"
        - "AMEX"
        - "JCB"
        - "DISCOVER"
        - "DINERS"
        - "MAESTRO"
        - "HIMYAN"
        - "NAPS"
        - "MY_DEBIT"
        - "ELO"
        - "CPACE"
        - "NAPAS"
        - "TROY"
        - "TAKAPAY"
        - "SADEEQ"
        - "ALIPAY"
        - "WECHAT"
        - "VISA_QR"
        - "MASTERCARD_QR"
        - "UNIONPAY_QR"
        - "SHOPEE_PAY_QR"
        - "GRAB_PAY_QR"
        - "ALIPAY_PLUS_QR"
        - "DUIT_NOW_QR"
        - "PAY_NOW"
        - "PH_QR"
        - "JCB_EMV_QR"
        - "LINEPAY_QR"
        - "EZ_PAY"
        - "PI_QR"
        - "ESUNWALLET_QR"
        - "TAIWANPAY_QR"
        - "EASYWALLET_QR"
        - "JKOPAY_QR"
        - "IPASSMONEY_PAY_QR"
        - "ICASH_PAY_QR"
        - "PLUSPAY_QR"
        - "PXPAYPLUS_QR"
        - "GAMA_PAY_QR"
        - "OPAY_QR"
        - "LINEPAYMONEY_QR"
        - "PAYPAY_QR"
        - "BCCARD_QR"
        - "NETS_QR"
        - "NTTDATA_QR"
        - "UCARD"
        - "CUP"
        - "SMARTPAY"
        - "BONUSPAY_QR"
        - "CASHLEZ_QR"
        - "UNKNOWN"
    EntryMode:
      type: "string"
      enum:
        - "NFC"
        - "SWIPE"
        - "CHIP"
        - "FALLBACK"
        - "MANUAL_KEYED"
        - "MERCHANT_PRESENT"
        - "CONSUMER_PRESENT"
        - "RETRIEVE"
        - "UNKNOWN"
    CvmPerformed:
      type: "string"
      enum:
        - "NO_CVM"
        - "SIGNATURE"
        - "PIN"
        - "OFFLINE_PIN"
        - "CDCVM"
        - "PIN_BYPASSED"
    HostMessageFormat:
      type: "string"
      enum:
        - "MOCK"
        - "MPGS_AP"
        - "CARD_NOW"
        - "TWOC2P"
        - "CARDWORKS"
        - "SHIFT4"
        - "SHIFT4_HD"
        - "PAY_STORE"
        - "POMELO"
        - "EFT_PAY"
        - "EZPAY"
        - "BANKNBOX"
        - "IULINK"
        - "RAZER"
        - "WALLYT"
        - "GCAG"
        - "POSTBRIDGE"
        - "RENDEZVOUS"
        - "STD_JSON"
        - "S2M_SELECT"
        - "VAULTSPAY"
        - "SMART_VISTA"
        - "SADAD"
        - "AIRWALLEX"
        - "AIRWALLEX_EU"
        - "WORLDPAY"
        - "CASHPLUS"
        - "PSS"
        - "RAWBANK"
        - "NEOCASH"
        - "CASHLEZ"
        - "QRIS"
        - "MASARAT"
        - "BONUSPAY"
        - "ALTO"
        - "AXS"
        - "CARDINFOLINK"
        - "BBL"
        - "ONERWAY"
        - "ACB"
        - "KEENU"
        - "SELECT_STANDARD"
        - "SELECT_MANUAL_MODE"
        - "SELECT_AUTO_MODE"
        - "SELECT_V24_MODE"
        - "STD_JSON_BSD"
        - "STD_JSON_YEDPAY"
    ActionType:
      type: "string"
      enum:
        - "NEW"
        - "ADJUST"
        - "VOID"
        - "AUTH_COMP"
        - "LINK_REFUND"
        - "CONFIRM"
        - "MERCHANT_PRESENT_QR"
        - "CONSUMER_PRESENT_QR"
        - "NOTIFIED"
        - "INQUIRY"
        - "CLOSE"
        - "INCREMENTAL_AUTH"
    ActionStatus:
      type: "string"
      enum:
        - "PROCESSING"
        - "SUCCESS"
        - "REJECTED"
        - "TIMEOUT"
        - "REVERSED"
        - "TO_BE_REVERSE"
    BatchStatus:
      type: "string"
      enum:
        - "OPEN"
        - "SETTLED"
        - "SETTLE_FAILED"
        - "SETTLEMENT_IN_PROGRESS"

    # ==================== Transaction Schemas ====================
    GeoResult:
      type: "string"
      description: "Geo-fence outcome decided by the caller (SRS/TMS) before the request reached Enabler"
      enum:
        - "NA"
        - "ALLOWED"
        - "FLAGGED"
        - "DENIED"
    Installment:
      type: "object"
      description: "The Installment Plan applied to a transaction. Plan-owned attributes come from the resolved MMS configuration"
      properties:
        planId:
          type: "string"
        planName:
          type: "string"
          description: "The plan's display name at the time it was applied"
        installmentCount:
          type: "integer"
          format: "int32"
        interestModel:
          $ref: "#/components/schemas/InterestModel"
        installmentType:
          $ref: "#/components/schemas/InstallmentType"
        revolving:
          $ref: "#/components/schemas/Revolving"
        issuerPreapprovalReference:
          type: "string"
          description: "Issuer/acquirer enrolment or approval reference, normalised from the authorisation response; absent if the host returned none"
      required:
        - "planId"
        - "planName"
        - "installmentCount"
        - "interestModel"
        - "installmentType"
    AllowedActions:
      type: "object"
      description: "Backend-calculated flags for which derived operations a transaction currently permits"
      properties:
        refund:
          type: "boolean"
          default: false
        completion:
          type: "boolean"
          default: false
        incrementalAuth:
          type: "boolean"
          default: false
    InterestModel:
      type: "string"
      enum:
        - "WITH_INTEREST"
        - "NO_INTEREST"
    InstallmentType:
      type: "string"
      enum:
        - "REGULAR"
        - "REVOLVING"
    Revolving:
      type: "object"
      properties:
        initialPaymentAmount:
          $ref: "#/components/schemas/Amount"
        remainingAmount:
          $ref: "#/components/schemas/Amount"
      required:
        - "initialPaymentAmount"
        - "remainingAmount"
    Transaction:
      type: "object"
      description: "Transaction response"
      properties:
        tranId:
          type: "string"
        tranType:
          $ref: "#/components/schemas/TranType"
        tranStatus:
          $ref: "#/components/schemas/TranStatus"
        amount:
          $ref: "#/components/schemas/Amount"
        paymentMethod:
          $ref: "#/components/schemas/PaymentMethod"
        entryMode:
          $ref: "#/components/schemas/EntryMode"
        accountMasked:
          type: "string"
        accountBin:
          type: "string"
        accountLast4:
          type: "string"
        issCountryCode:
          type: "string"
        cvmPerformed:
          $ref: "#/components/schemas/CvmPerformed"
        cvmSignatureUrl:
          type: "string"
        cvmSignatureBase64:
          type: "string"
        aid:
          type: "string"
        appName:
          type: "string"
        tc:
          type: "string"
        tvr:
          type: "string"
        tsi:
          type: "string"
        atc:
          type: "string"
        profileId:
          type: "string"
        acceptanceId:
          type: "string"
          deprecated: true
          description: "Deprecated. Use acptId instead"
        acptId:
          type: "string"
        sdkId:
          type: "string"
        posReference:
          type: "string"
        extOrderId:
          type: "string"
          description: "External order ID supplied by the integrator"
        trace:
          type: "string"
        description:
          type: "string"
        callbackUrl:
          type: "string"
        installmentPlan:
          type: "integer"
          description: "Legacy count-only installment plan, superseded by installments"
        installments:
          description: "Installment applied to this SALE, if it was paid in installments"
          allOf:
            - $ref: "#/components/schemas/Installment"
        merchantName:
          type: "string"
        merchantAddr:
          type: "string"
        mcc:
          type: "string"
        primaryMid:
          type: "string"
        primaryTid:
          type: "string"
        subMid:
          type: "string"
        subTid:
          type: "string"
        hostMessageFormat:
          $ref: "#/components/schemas/HostMessageFormat"
        providerReference:
          type: "string"
        providerMchId:
          type: "string"
        isvId:
          type: "string"
        isvName:
          type: "string"
        shopId:
          type: "string"
        shopName:
          type: "string"
        linkedTranId:
          type: "string"
          description: "ID of the immediate parent transaction (e.g. the original sale for a refund)"
        linkedSrsTranId:
          type: "string"
        hasChildren:
          type: "boolean"
          description: "True when at least one derived transaction points to this one. Absent when not evaluated (e.g. list responses)"
        refundedAmount:
          $ref: "#/components/schemas/Amount"
        availableRefundAmount:
          $ref: "#/components/schemas/Amount"
        completedAmount:
          $ref: "#/components/schemas/Amount"
        availableCompletionAmount:
          $ref: "#/components/schemas/Amount"
        allowedActions:
          $ref: "#/components/schemas/AllowedActions"
        preferredAcceptanceTag:
          type: "string"
        extraData:
          type: "string"
        rrn:
          type: "string"
        approvalCode:
          type: "string"
        batchId:
          type: "string"
        batchNo:
          type: "string"
        actions:
          type: "array"
          items:
            $ref: "#/components/schemas/Action"
        srsTranId:
          type: "string"
        consumerPaymentDevice:
          type: "string"
        geoResult:
          $ref: "#/components/schemas/GeoResult"
        geoLocation:
          type: "object"
          additionalProperties: true
          description: "Device location snapshot captured when the geo-fence check ran; passed through verbatim"
        geoId:
          type: "string"
          description: "Identifier of the geo-fence rule the caller matched"
        createdAt:
          type: "string"
          format: "date-time"
          example: "2026-01-26T12:57:01.373+08:00"
        updatedAt:
          type: "string"
          format: "date-time"
          example: "2026-01-26T12:57:01.381+08:00"
      required:
        - "tranId"
        - "tranType"
        - "tranStatus"
        - "amount"
        - "paymentMethod"
        - "entryMode"
        - "profileId"
        - "acptId"
        - "trace"
        - "merchantName"
        - "merchantAddr"
        - "mcc"
        - "primaryMid"
        - "primaryTid"
        - "hostMessageFormat"
        - "batchId"
        - "batchNo"
        - "actions"
        - "createdAt"
    Action:
      type: "object"
      description: "Transaction action"
      properties:
        actionId:
          type: "string"
        trace:
          type: "string"
        actionType:
          $ref: "#/components/schemas/ActionType"
        actionStatus:
          $ref: "#/components/schemas/ActionStatus"
        requestId:
          type: "string"
        amount:
          $ref: "#/components/schemas/Amount"
        tranId:
          type: "string"
        reason:
          type: "string"
        hostRespCode:
          type: "string"
        hostRespMessage:
          type: "string"
        posReference:
          type: "string"
        extraData:
          type: "string"
        hostRespExtra:
          type: "object"
        geoResult:
          $ref: "#/components/schemas/GeoResult"
        geoLocation:
          type: "object"
          additionalProperties: true
          description: "Device location snapshot captured when the geo-fence check ran; passed through verbatim"
        geoId:
          type: "string"
          description: "Identifier of the geo-fence rule the caller matched"
        createdAt:
          type: "string"
          format: "date-time"
          example: "2026-01-26T12:57:01.373+08:00"
        updatedAt:
          type: "string"
          format: "date-time"
          example: "2026-01-26T12:57:01.381+08:00"
      required:
        - "actionId"
        - "trace"
        - "actionType"
        - "actionStatus"
        - "requestId"
        - "createdAt"
    TransactionExtract:
      type: "object"
      description: "Lightweight transaction view returned by the transaction list endpoint. Does not include the actions list, merchantAddr, callbackUrl, extraData, or preferredAcceptanceTag found on the full Transaction object."
      properties:
        tranId:
          type: "string"
        tranType:
          $ref: "#/components/schemas/TranType"
        tranStatus:
          $ref: "#/components/schemas/TranStatus"
        amount:
          $ref: "#/components/schemas/Amount"
        paymentMethod:
          $ref: "#/components/schemas/PaymentMethod"
        entryMode:
          $ref: "#/components/schemas/EntryMode"
        accountBin:
          type: "string"
        accountLast4:
          type: "string"
        cvmPerformed:
          $ref: "#/components/schemas/CvmPerformed"
        mcc:
          type: "string"
        sdkId:
          type: "string"
        posReference:
          type: "string"
        extOrderId:
          type: "string"
          description: "External order ID supplied by the integrator"
        description:
          type: "string"
        trace:
          type: "string"
        merchantName:
          type: "string"
        primaryMid:
          type: "string"
        primaryTid:
          type: "string"
        subMid:
          type: "string"
        subTid:
          type: "string"
        hostMessageFormat:
          $ref: "#/components/schemas/HostMessageFormat"
        providerReference:
          type: "string"
        providerMchId:
          type: "string"
        isvId:
          type: "string"
        isvName:
          type: "string"
        shopId:
          type: "string"
        shopName:
          type: "string"
        profileId:
          type: "string"
        acptId:
          type: "string"
        linkedTranId:
          type: "string"
          description: "ID of the immediate parent transaction (e.g. the original sale for a refund)"
        linkedSrsTranId:
          type: "string"
        installmentPlan:
          type: "integer"
          description: "Legacy count-only installment plan, superseded by installments"
        installments:
          description: "Installment applied to this SALE, if it was paid in installments"
          allOf:
            - $ref: "#/components/schemas/Installment"
        rrn:
          type: "string"
        approvalCode:
          type: "string"
        batchNo:
          type: "string"
        batchId:
          type: "string"
        batchStatus:
          $ref: "#/components/schemas/BatchStatus"
        srsTranId:
          type: "string"
        consumerPaymentDevice:
          type: "string"
        accountMasked:
          type: "string"
        issCountryCode:
          type: "string"
        aid:
          type: "string"
        appName:
          type: "string"
        tc:
          type: "string"
        tvr:
          type: "string"
        tsi:
          type: "string"
        atc:
          type: "string"
        cvmSignatureUrl:
          type: "string"
        hostRespExtra:
          type: "object"
        refundedAmount:
          $ref: "#/components/schemas/Amount"
        availableRefundAmount:
          $ref: "#/components/schemas/Amount"
        completedAmount:
          $ref: "#/components/schemas/Amount"
        availableCompletionAmount:
          $ref: "#/components/schemas/Amount"
        allowedActions:
          $ref: "#/components/schemas/AllowedActions"
        createdAt:
          type: "string"
          format: "date-time"
          example: "2026-01-26T12:57:01.373+08:00"
        updatedAt:
          type: "string"
          format: "date-time"
          example: "2026-01-26T12:57:01.381+08:00"
        cursor:
          type: "string"
          description: "Pagination cursor for this item, equal to tranId. Use as the value of startingAfter/endingBefore to fetch the adjacent page."
      required:
        - "tranId"
        - "tranType"
        - "tranStatus"
        - "amount"
        - "paymentMethod"
        - "entryMode"
        - "cvmPerformed"
        - "trace"
        - "merchantName"
        - "primaryMid"
        - "primaryTid"
        - "hostMessageFormat"
        - "profileId"
        - "acptId"
        - "batchNo"
        - "batchId"
        - "createdAt"
        - "cursor"
    CursorPaginatedTransactionExtract:
      type: "object"
      description: "Cursor-paginated list of transactions"
      properties:
        hasMore:
          type: "boolean"
          description: "Whether more results exist beyond this page"
        requestPath:
          type: "string"
          description: "The request path including query parameters, as echoed back by the server"
        requestSize:
          type: "integer"
          description: "The requested page size (limit)"
        dataSize:
          type: "integer"
          description: "The number of items actually returned in this page"
        totalSize:
          type: "integer"
          description: "Total number of matching transactions across all pages"
        cursorStarting:
          type: "string"
          nullable: true
          description: "The cursor (tranId) of the first item in this page. Pass as startingAfter to fetch the next page."
        cursorEnding:
          type: "string"
          nullable: true
          description: "The cursor (tranId) of the last item in this page. Pass as endingBefore to fetch the previous page."
        data:
          type: "array"
          items:
            $ref: "#/components/schemas/TransactionExtract"
      required:
        - "hasMore"
        - "requestPath"
        - "requestSize"
        - "dataSize"
        - "totalSize"
        - "data"