openapi: 3.0.3
info:
  title: Astrada bank-accounts bank-transactions API
  version: '2024-02-28'
  contact:
    email: developer@astrada.co
  description: 'Welcome to our API Reference. 👋

    '
servers:
- url: https://api.astrada.co
security: null
tags:
- name: bank-transactions
  description: Access bank transactions synced from connected accounts. Transactions are ingested via Plaid and can be matched against card transactions.
paths:
  /bank-transactions/{subaccountId}/{transactionId}:
    parameters:
    - $ref: '#/components/parameters/subaccount-id-2'
    - $ref: '#/components/parameters/transaction-id'
    get:
      tags:
      - bank-transactions
      summary: Retrieve bank transaction
      description: Returns detailed information about a specific bank transaction by its identifier, including match status and transaction metadata.
      operationId: GetBankTransaction
      security:
      - main-auth:
        - banking:read
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/bank-transaction'
              examples:
                Example Get Bank Transaction Response:
                  $ref: '#/components/examples/bank-transaction'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/not-found'
        '500':
          $ref: '#/components/responses/server-error'
  /bank-transactions/{subaccountId}:
    parameters:
    - $ref: '#/components/parameters/subaccount-id-2'
    get:
      tags:
      - bank-transactions
      summary: List bank transactions
      description: 'Returns a list of bank transactions for a subaccount. Bank transactions are synced from connected financial institutions. A movement may briefly appear as its pending posting until the posted transaction replaces it (the pending row is then removed from the feed).


        By default, `GET /bank-transactions/{subaccountId}` returns transactions ordered by the latest `date`.


        This endpoint supports cursor-based pagination and various filters including date range, amount range, and match status.

        '
      operationId: ListBankTransactions
      parameters:
      - $ref: '#/components/parameters/bank-account-id-2'
      - $ref: '#/components/parameters/card-id-2'
      - $ref: '#/components/parameters/start-date'
      - $ref: '#/components/parameters/end-date'
      - $ref: '#/components/parameters/min-amount'
      - $ref: '#/components/parameters/max-amount'
      - $ref: '#/components/parameters/transaction-type'
      - $ref: '#/components/parameters/matched'
      - in: query
        name: source
        description: Filter transactions by source.
        required: false
        schema:
          type: string
          enum:
          - PLAID
          - UPLOAD
      - in: query
        name: statementId
        description: Filter transactions by the statement they were imported from.
        required: false
        schema:
          type: string
          format: uuid
      - $ref: '#/components/parameters/banking-limit'
      - $ref: '#/components/parameters/cursor'
      security:
      - main-auth:
        - banking:read
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                required:
                - items
                - pagination
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/bank-transaction'
                  pagination:
                    type: object
                    required:
                    - hasMore
                    properties:
                      cursor:
                        type: string
                        description: Cursor to use for the next page of results.
                      hasMore:
                        type: boolean
                        description: Whether there are more results available.
              examples:
                Example List Bank Transactions Response:
                  value:
                    items:
                    - _links:
                        self:
                          href: /bank-transactions/1fcb895e-9217-4a6f-9d10-5a7dcef86c11/7f2a9c4e-3b1d-4e8f-a5c7-6d0e2f9b8a3c
                        bankAccount:
                          href: /bank-accounts/3a8f2c1d-5e7b-4d9a-b6c8-9f0e1d2a3b4c
                        card:
                          href: /cards/5dec2c49-0aa5-4683-a317-427eb5d115f3
                        match:
                          href: /transaction-matches/1fcb895e-9217-4a6f-9d10-5a7dcef86c11/b1c2d3e4-f5a6-7b8c-9d0e-1f2a3b4c5d6e
                      id: 7f2a9c4e-3b1d-4e8f-a5c7-6d0e2f9b8a3c
                      accountId: 8f3a1b2c-4d5e-6f7a-8b9c-0d1e2f3a4b5c
                      subaccountId: 1fcb895e-9217-4a6f-9d10-5a7dcef86c11
                      bankAccountId: 3a8f2c1d-5e7b-4d9a-b6c8-9f0e1d2a3b4c
                      cardId: 5dec2c49-0aa5-4683-a317-427eb5d115f3
                      matchId: b1c2d3e4-f5a6-7b8c-9d0e-1f2a3b4c5d6e
                      date: '2025-10-15'
                      amount: 42.5
                      currency: USD
                      description: UBER TRIP
                      merchantName: Uber
                      category:
                      - Travel
                      transactionType: debit
                      source: PLAID
                      statementId: null
                      status: matched
                      settlement: null
                      createdAt: '2025-10-15T14:30:00.000Z'
                    - _links:
                        self:
                          href: /bank-transactions/1fcb895e-9217-4a6f-9d10-5a7dcef86c11/2e5f8a1b-4c7d-3e9f-b0a2-8d6c4f1e7b3a
                        bankAccount:
                          href: /bank-accounts/3a8f2c1d-5e7b-4d9a-b6c8-9f0e1d2a3b4c
                        card:
                          href: /cards/5dec2c49-0aa5-4683-a317-427eb5d115f3
                      id: 2e5f8a1b-4c7d-3e9f-b0a2-8d6c4f1e7b3a
                      accountId: 8f3a1b2c-4d5e-6f7a-8b9c-0d1e2f3a4b5c
                      subaccountId: 1fcb895e-9217-4a6f-9d10-5a7dcef86c11
                      bankAccountId: 3a8f2c1d-5e7b-4d9a-b6c8-9f0e1d2a3b4c
                      cardId: 5dec2c49-0aa5-4683-a317-427eb5d115f3
                      matchId: null
                      date: '2025-10-14'
                      amount: 156.23
                      currency: USD
                      description: AMAZON MARKETPLACE
                      merchantName: Amazon
                      category:
                      - Shopping
                      transactionType: debit
                      source: PLAID
                      statementId: null
                      status: posted
                      settlement: null
                      createdAt: '2025-10-14T09:15:00.000Z'
                    pagination:
                      cursor: ZXhhbXBsZQ==
                      hasMore: true
          links:
            GetFirstBankTransaction:
              operationId: GetBankTransaction
              parameters:
                transactionId: $response.body#/items/0/id
              description: Retrieve the first bank transaction from the list.
        '400':
          $ref: '#/components/responses/bad-request'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '500':
          $ref: '#/components/responses/server-error'
  /bank-transactions/{subaccountId}/webhooks:
    parameters:
    - $ref: '#/components/parameters/subaccount-id-2'
    post:
      tags:
      - bank-transactions
      summary: Trigger bank transaction webhooks
      description: 'Manually triggers webhook delivery for specified bank transactions. This can be used to re-emit webhooks that may have been missed or to force re-matching of transactions.


        You can specify which webhook event types to emit: `banktransaction.created` for transaction data or `transaction.match.created` for match results.

        '
      operationId: TriggerBankTransactionWebhooks
      security:
      - main-auth:
        - banking:admin
      requestBody:
        description: Webhook trigger request
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - ids
              properties:
                ids:
                  description: List of bank transaction identifiers to emit webhooks for. Must contain at least one ID.
                  type: array
                  minItems: 1
                  items:
                    type: string
                    format: uuid
                webhooks:
                  description: The types of webhook events to emit.
                  type: array
                  items:
                    type: string
                    enum:
                    - banktransaction.created
                    - transaction.match.created
                forceRematch:
                  description: 'Set to `true` to re-run the matching algorithm for the named transactions before emitting webhooks. Transactions that already have a match are genuinely re-scored: the existing match id is preserved when the pairing survives, updated when a better pairing exists, and removed when the movement no longer matches.'
                  type: boolean
                  default: false
                dispatchUnmatched:
                  description: 'After the re-match, emit the standalone bank-only feed entry for each named transaction the matcher left unmatched (idempotent per transaction — already-emitted standalones are skipped). Requires `forceRematch: true` and `webhooks` to include `transaction.match.created`; the request is rejected with `400` otherwise, because only a same-run re-match can distinguish a genuinely unmatched movement from a duplicate of an already-settled purchase.'
                  type: boolean
                  default: false
            examples:
              TriggerWebhooksExample:
                value:
                  ids:
                  - 7f2a9c4e-3b1d-4e8f-a5c7-6d0e2f9b8a3c
                  webhooks:
                  - banktransaction.created
                  - transaction.match.created
                  forceRematch: false
              RematchAndDispatchExample:
                value:
                  ids:
                  - 7f2a9c4e-3b1d-4e8f-a5c7-6d0e2f9b8a3c
                  webhooks:
                  - transaction.match.created
                  forceRematch: true
                  dispatchUnmatched: true
      responses:
        '200':
          description: Webhooks triggered
          content:
            application/json:
              schema:
                type: object
                required:
                - message
                - emitted
                - resent
                - matched
                - skipped
                - failed
                properties:
                  message:
                    type: string
                    description: Human-readable summary of the operation.
                  emitted:
                    type: integer
                    description: Number of webhook events emitted.
                  resent:
                    type: integer
                    description: Number of webhooks resent.
                  matched:
                    type: integer
                    description: Number of transactions that were matched.
                  skipped:
                    type: integer
                    description: Number of transactions that were skipped.
                  failed:
                    type: array
                    description: Transactions that failed to process.
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          description: The transaction identifier that failed.
                        error:
                          type: string
                          description: The error message describing why processing failed.
                  dispatched:
                    type: integer
                    description: Number of standalone bank-only emissions dispatched for still-unmatched transactions. Only present when `dispatchUnmatched` was requested (and on service versions that support the flag).
                  dispatchError:
                    type: string
                    description: Present when the standalone dispatch step failed after a successful re-match; the matching results above still stand.
              examples:
                Example Trigger Webhooks Response:
                  value:
                    message: Processed 1 transactions
                    emitted: 2
                    resent: 0
                    matched: 1
                    skipped: 0
                    failed: []
        '400':
          $ref: '#/components/responses/bad-request'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '500':
          $ref: '#/components/responses/server-error'
components:
  examples:
    bank-transaction:
      description: Example of a Bank Transaction resource
      value:
        _links:
          self:
            href: /bank-transactions/1fcb895e-9217-4a6f-9d10-5a7dcef86c11/7f2a9c4e-3b1d-4e8f-a5c7-6d0e2f9b8a3c
          bankAccount:
            href: /bank-accounts/3a8f2c1d-5e7b-4d9a-b6c8-9f0e1d2a3b4c
          card:
            href: /cards/5dec2c49-0aa5-4683-a317-427eb5d115f3
          match:
            href: /transaction-matches/1fcb895e-9217-4a6f-9d10-5a7dcef86c11/b1c2d3e4-f5a6-7b8c-9d0e-1f2a3b4c5d6e
        id: 7f2a9c4e-3b1d-4e8f-a5c7-6d0e2f9b8a3c
        accountId: 8f3a1b2c-4d5e-6f7a-8b9c-0d1e2f3a4b5c
        subaccountId: 1fcb895e-9217-4a6f-9d10-5a7dcef86c11
        bankAccountId: 3a8f2c1d-5e7b-4d9a-b6c8-9f0e1d2a3b4c
        cardId: 5dec2c49-0aa5-4683-a317-427eb5d115f3
        matchId: b1c2d3e4-f5a6-7b8c-9d0e-1f2a3b4c5d6e
        date: '2025-10-15'
        amount: 42.5
        currency: USD
        description: UBER TRIP
        merchantName: Uber
        category:
        - Travel
        transactionType: debit
        source: PLAID
        statementId: null
        status: early_cleared
        settlement:
          state: early_cleared
          emissionType: early_clearing
          emittedAt: '2025-10-15T15:00:00.000Z'
          supersededAt: null
        createdAt: '2025-10-15T14:30:00.000Z'
  parameters:
    transaction-type:
      in: query
      name: transactionType
      description: Filter bank transactions by transaction type
      required: false
      schema:
        type: string
        enum:
        - debit
        - credit
      example: debit
    min-amount:
      in: query
      name: minAmount
      description: Filter transactions with an amount greater than or equal to this value
      required: false
      schema:
        type: number
      example: 10
    matched:
      in: query
      name: matched
      description: Filter bank transactions by match status. Set to `true` to return only matched transactions, or `false` for unmatched.
      required: false
      schema:
        type: string
        enum:
        - 'true'
        - 'false'
      example: 'true'
    end-date:
      in: query
      name: endDate
      description: Filter results up to this date (inclusive), in YYYY-MM-DD format
      required: false
      schema:
        type: string
        format: date
      example: '2025-10-31'
    bank-account-id-2:
      in: query
      name: bankAccountId
      description: Filter by bank account identifier
      required: false
      schema:
        type: string
        format: uuid
      example: 3a8f2c1d-5e7b-4d9a-b6c8-9f0e1d2a3b4c
    banking-limit:
      in: query
      name: limit
      description: Maximum number of items to return
      required: false
      schema:
        type: integer
        minimum: 1
        maximum: 1000
        default: 250
      example: 250
    transaction-id:
      in: path
      name: transactionId
      required: true
      schema:
        type: string
        format: uuid
      example: 9340721f-bdce-4afa-bd9d-26cceb9d2176
    cursor:
      in: query
      name: cursor
      required: false
      description: The cursor to use for pagination. Identifies your place on the list
      schema:
        type: string
        format: byte
      example: ZXhhbXBsZQ==
    subaccount-id-2:
      in: path
      name: subaccountId
      required: true
      schema:
        type: string
        format: uuid
      example: 24c4f90d-ab3b-4f6e-8a1d-d251a4fcf34c
    start-date:
      in: query
      name: startDate
      description: Filter results from this date (inclusive), in YYYY-MM-DD format
      required: false
      schema:
        type: string
        format: date
      example: '2025-10-01'
    card-id-2:
      in: path
      name: cardId
      required: true
      schema:
        type: string
        format: uuid
      example: 6d18f5bb-b9d6-4237-97c2-44b1bdb71d6b
    max-amount:
      in: query
      name: maxAmount
      description: Filter transactions with an amount less than or equal to this value
      required: false
      schema:
        type: number
      example: 500
  responses:
    server-error:
      description: The server encountered an unexpected condition that prevented it from fulfilling the request
      content:
        application/problem+json:
          schema:
            type: object
            properties:
              detail:
                type: string
              title:
                type: string
                enum:
                - Internal Server Error
            required:
            - detail
            - title
          example:
            title: Internal Server Error
            detail: The server encountered an unexpected condition that prevented it from fulfilling the request.
    bad-request:
      description: The server cannot or will not process the request due to something that is perceived to be a client error
      content:
        application/problem+json:
          schema:
            type: object
            properties:
              detail:
                type: string
              title:
                type: string
                enum:
                - Bad Request
              errors:
                type: array
                items:
                  type: object
                  properties:
                    title:
                      type: string
                    detail:
                      type: string
                  required:
                  - title
                  - detail
            required:
            - detail
            - title
          examples:
            Example Generic Bad Request Payload Response:
              value:
                title: Bad Request
                detail: Request object failed validation.
            Example Generic Bad Request Parameters Response:
              value:
                title: Bad Request
                detail: Request parameters are invalid.
    not-found:
      description: The requested resource was not found on the server
      content:
        application/problem+json:
          schema:
            type: object
            properties:
              type:
                type: string
              instance:
                type: string
              detail:
                type: string
              title:
                type: string
                enum:
                - Not Found
            required:
            - detail
            - title
          example:
            title: Not Found
            detail: The requested resource was not found on the server.
    unauthorized:
      description: Authentication credentials were either missing or incorrect
      content:
        application/problem+json:
          schema:
            type: object
            properties:
              detail:
                type: string
              title:
                type: string
                enum:
                - Unauthorized
            required:
            - detail
            - title
          example:
            title: Unauthorized
            detail: Authentication credentials were either missing or incorrect.
    forbidden:
      description: Authentication credentials used do not have have permissions to perform the request
      content:
        application/problem+json:
          schema:
            type: object
            properties:
              detail:
                type: string
              title:
                type: string
                enum:
                - Forbidden
            required:
            - detail
            - title
          example:
            title: Forbidden
            detail: You do not have permission to access the requested resource.
  schemas:
    link:
      type: object
      properties:
        href:
          type: string
        templated:
          type: boolean
        type:
          type: string
        deprecation:
          type: string
        name:
          type: string
        profile:
          type: string
        title:
          type: string
        hreflang:
          type: string
      required:
      - href
    bank-transaction:
      type: object
      required:
      - _links
      - id
      - accountId
      - subaccountId
      - bankAccountId
      - cardId
      - matchId
      - date
      - amount
      - currency
      - description
      - merchantName
      - category
      - transactionType
      - source
      - status
      - settlement
      - createdAt
      properties:
        _links:
          type: object
          description: HAL-style links to related resources.
          required:
          - self
          - bankAccount
          properties:
            self:
              $ref: '#/components/schemas/link'
            bankAccount:
              $ref: '#/components/schemas/link'
            card:
              $ref: '#/components/schemas/link'
            match:
              $ref: '#/components/schemas/link'
        id:
          type: string
          format: uuid
          description: The unique identifier of the bank transaction.
        accountId:
          type: string
          format: uuid
          description: The unique identifier of the account that owns this transaction.
        subaccountId:
          type: string
          format: uuid
          description: The unique identifier of the subaccount associated with this transaction.
        bankAccountId:
          type: string
          format: uuid
          description: The unique identifier of the bank account this transaction belongs to.
        cardId:
          type: string
          format: uuid
          nullable: true
          description: The identifier of the card linked to the bank account, used for transaction matching.
        matchId:
          type: string
          format: uuid
          nullable: true
          description: The identifier of the transaction match, if this bank transaction has been matched to a card transaction.
        date:
          type: string
          format: date
          description: The date the transaction was posted, in YYYY-MM-DD format.
        amount:
          type: number
          description: The transaction amount.
        currency:
          type: string
          description: The currency of the transaction following ISO 4217 format.
          minLength: 3
          maxLength: 3
        description:
          type: string
          nullable: true
          description: The transaction description provided by the financial institution.
        merchantName:
          type: string
          nullable: true
          description: The name of the merchant.
        category:
          type: array
          nullable: true
          description: The transaction categories assigned by the provider.
          items:
            type: string
        transactionType:
          type: string
          description: 'The type of transaction.

            - `debit`: Money sent (outflow).

            - `credit`: Money received (inflow).

            '
          enum:
          - debit
          - credit
        source:
          type: string
          description: 'The source of this transaction.

            - `PLAID`: Synced from a connected financial institution via Plaid.

            - `UPLOAD`: Imported from a manually uploaded bank statement.

            '
          enum:
          - PLAID
          - UPLOAD
        statementId:
          type: string
          format: uuid
          nullable: true
          description: The identifier of the bank statement this transaction was imported from, if applicable.
        status:
          type: string
          description: 'The lifecycle stage of the bank movement, derived from its match pointer and settlement state.

            - `posted`: Synced, not yet matched.

            - `matched`: Paired to a card transaction without an early settlement of its own (e.g. connector off, or a below-HIGH match) — the movement is represented by the card transaction''s network settlement, and any standalone it previously emitted is netted to zero.

            - `settled`: A bank-only movement settled standalone on the unified feed.

            - `early_cleared`: A matched movement settled its card transaction early.

            - `superseded`: A previously bank-only movement was retracted or corrected.

            '
          enum:
          - posted
          - matched
          - settled
          - early_cleared
          - superseded
        settlement:
          type: object
          nullable: true
          description: Settlement outcome on the unified transaction feed. Present when the movement has settled live; null otherwise (unmatched, connector off, or shadow-only).
          required:
          - state
          - emissionType
          - emittedAt
          - supersededAt
          properties:
            state:
              type: string
              enum:
              - settled
              - early_cleared
              - superseded
            emissionType:
              type: string
              enum:
              - early_clearing
              - bank_only
            emittedAt:
              type: string
              format: date-time
              nullable: true
              description: When the settlement was emitted to the feed.
            supersededAt:
              type: string
              format: date-time
              nullable: true
              description: When the settlement was superseded or corrected, if applicable.
        createdAt:
          description: Date and time when this resource was created, in UTC, following ISO 8601 format.
          type: string
          format: date-time
  securitySchemes:
    main-auth:
      type: oauth2
      flows:
        implicit:
          authorizationUrl: https://api.astrada.co/auth/realms/{accountId}/protocol/openid-connect/token
          refreshUrl: https://api.astrada.co/auth/realms/{accountId}/protocol/openid-connect/token
          scopes:
            accounts:write: Accounts write resource
            accounts:read: Accounts read resource
            subaccounts:write: Subaccounts write resource
            subaccounts:read: Subaccounts read resource
            card-connector-data-links:write: card-connector-data-link resource
            card-connector-consents:read: Card Consent read resource
            card-connector-consents:write: Card Consent write resource
            webhooks:read: Read Webhook resources
            webhooks:write: Write Webhook resources
            card-subscriptions:write: Create card subscription
            card-subscriptions:read: Read card subscription
            card-verifications:write: Create card verification
            card-verifications:read: Read Card verification
            cards:read: Read Card resources
            cardholder:read: Read Cardholder resources
            cardholder:write: Write Cardholder resources
            transactions:read: Read Transaction resources
            transaction-messages:read: Read Transaction Message resources
            network-bulk-feeds:read: Read network bulk feed
            network-bulk-feeds:write: Write network bulk feed
            network-links:write: Write network link
            enrollment-methods:write: Write enrollment methods
            simulation:write: Write sandbox simulations
            banking:read: Read banking resources
            banking:write: Write banking resources
            banking:admin: Admin banking operations
            appstore:enrollment:write: Enroll cards via the appstore B2C flow
            appstore:cards:read: View enrolled cards in the appstore
            appstore:transactions:read: View synced transactions in the appstore
            appstore:transactions:sync: Trigger transaction sync in the appstore
            appstore:sessions:read: Read appstore session state
            appstore:sessions:write: Write or delete appstore session state
            appstore:tokens:read: Read appstore stored tokens and connections
            appstore:tokens:write: Write appstore stored tokens and connections
externalDocs:
  description: Find out more about Astrada API.
  url: https://docs.astrada.co/reference