openapi: 3.0.3
info:
  title: Mobile Check Cashing SDK — Get Transaction History
  version: '1'
  description: |
    Retrieve a customer's check cashing transaction history, optionally
    filtered to a single card account and paged through results.

    Requires an active SDK partner session — the `SessionId` header from
    `POST /api/v1/partners/authenticate` — plus the `customerId`. Called by
    both Card and PayPal partners; it does not require the OBO `ssoToken`.
servers:
  - url: https://check-cashing-uat.spykemobile.net
    description: UAT (Sandbox)
  - url: https://check-cashing.spykemobile.net
    description: Production
security:
  - OAuth2:
      - sdkapi
tags:
  - name: Transactions
    description: Customer transaction history.
paths:
  /api/v1/partners/get-transaction-history:
    post:
      tags:
        - Transactions
      operationId: getTransactionHistory
      summary: Retrieve customer transaction history
      description: |
        Returns paged transaction history for a customer. By default,
        the 20 most recent transactions are returned. Specify
        `accountId` to filter to a single card, or
        `pagingTransactionReferenceNumber` to page from a known
        anchor transaction.
      parameters:
        - $ref: '#/components/parameters/SessionIdHeader'
        - $ref: '#/components/parameters/DeviceIdHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GetTransactionHistoryRequest'
            example:
              customerId: 2eaf7fe8-8d9c-414c-9763-9a7e897d8496
              accountId: ''
              pagingTransactionReferenceNumber: ''
              pageSize: 3
      responses:
        '200':
          description: Transaction history returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetTransactionHistoryResponse'
              example:
                searchResults:
                  - statusCode: 14
                    statusMessage: Account Funded
                    state: 4
                    transactionId: a00b79cc-64c5-42ae-a1bf-b93ba04cbd8f
                    createdOn: '2023-07-12T13:07:04Z'
                    amount: 1173
                    fee: 59
                    processingStatus: 1101
                    classificationStatus: 1012
                    declineReasonCode: 0
                    declineReasonMessage: ''
                    pickupLocationId: 0
                    mobileTransactionTypeId: 100
                    ocrAmount: 1173
                    userEnteredAmount: 1173
                    submittedForClassificationOn: '2023-07-12T13:07:04Z'
                    finishedClassificationOn: '2023-07-12T13:07:04Z'
                    submittedForApprovalOn: '2023-07-12T13:07:11Z'
                    finishedApprovalOn: '2023-07-12T13:07:14Z'
                    lastFourDigitsOfCard: ''
                    cardNickname: ''
                    loadStatus: 1011
                    expectedLoadDate: '2023-07-12T13:07:11Z'
                    actualLoadDate: '2023-07-12T13:07:14Z'
                    loadAmount: 1114
                    destinationDisplayName: John Smith
                totalRecords: 6
        '400':
          description: Validation error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationProblemDetails'
              example:
                errors: {}
                type: https://tools.ietf.org/html/rfc7231#section-6.5.1
                title: Bad Request
                status: 400
                detail: One or more validation errors occurred.
                instance: /api/v1/partners/get-transaction-history
                validationErrors:
                  - key: query.customerId
                    message: The input was not valid.
components:
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://auth.spykemobile.net/connect/token
          scopes:
            sdkapi: Mobile Check Cashing SDK partner methods
  parameters:
    SessionIdHeader:
      name: SessionId
      in: header
      required: true
      schema:
        type: string
    DeviceIdHeader:
      name: DeviceId
      in: header
      required: true
      schema:
        type: string
  schemas:
    GetTransactionHistoryRequest:
      type: object
      required:
        - customerId
      properties:
        customerId:
          type: string
          format: uuid
          minLength: 36
          maxLength: 36
          description: Customer GUID.
        accountId:
          type: string
          description: |
            Optional card GUID. When provided, transactions are
            filtered to this card only. Pass an empty string to
            return transactions across all cards.
        pagingTransactionReferenceNumber:
          type: string
          description: |
            Optional GUID of the first transaction in the page.
            Returns this transaction plus the next `pageSize`
            transactions older than it.
        pageSize:
          type: integer
          minimum: 0
          description: |
            Optional page size. The dev-center field table caps this
            at 10 but the description notes that the default page
            size is 20 — confirm the actual upper bound with the API
            team. If omitted, the 20 most recent transactions are
            returned.
    GetTransactionHistoryResponse:
      type: object
      required:
        - searchResults
        - totalRecords
      properties:
        searchResults:
          type: array
          items:
            $ref: '#/components/schemas/TransactionRecord'
        totalRecords:
          type: integer
    TransactionRecord:
      type: object
      description: |
        Single transaction record. Numeric status / classification
        / load codes carry the legacy enumerations used by the
        check cashing back-end; map them via the Error Codes page or
        the integration spec sheet.
      properties:
        statusCode:
          type: integer
        statusMessage:
          type: string
        state:
          type: integer
        transactionId:
          type: string
          format: uuid
        createdOn:
          type: string
          format: date-time
        amount:
          type: integer
          description: Amount in cents.
        fee:
          type: integer
          description: Fee in cents.
        processingStatus:
          type: integer
        classificationStatus:
          type: integer
        declineReasonCode:
          type: integer
        declineReasonMessage:
          type: string
        pickupLocationId:
          type: integer
        mobileTransactionTypeId:
          type: integer
        ocrAmount:
          type: integer
        userEnteredAmount:
          type: integer
        submittedForClassificationOn:
          type: string
          format: date-time
        finishedClassificationOn:
          type: string
          format: date-time
        submittedForApprovalOn:
          type: string
          format: date-time
        finishedApprovalOn:
          type: string
          format: date-time
        lastFourDigitsOfCard:
          type: string
        cardNickname:
          type: string
        loadStatus:
          type: integer
        expectedLoadDate:
          type: string
          format: date-time
        actualLoadDate:
          type: string
          format: date-time
        loadAmount:
          type: integer
        destinationDisplayName:
          type: string
    ValidationProblemDetails:
      type: object
      required:
        - type
        - title
        - status
      properties:
        errors:
          type: object
          additionalProperties: true
        type:
          type: string
          format: uri
        title:
          type: string
        status:
          type: integer
        detail:
          type: string
        instance:
          type: string
        validationErrors:
          type: array
          items:
            type: object
            required:
              - key
              - message
            properties:
              key:
                type: string
              message:
                type: string