openapi: 3.0.1
info:
  title: Transactions API
  description: >

    The transactions API lets you view your transactions, accounts, and
    statements.
  contact:
    name: Admin
    url: https://brex.com
    email: developer-support@brex.com
  version: '1.0'
  x-logo:
    altText: Brex Logo
    url: https://www.brex.com/logo.png
servers:
  - url: https://api.brex.com
    description: Production
  - url: https://api-staging.brex.com
    description: >-
      Staging (Note: This is not a sandbox. It will not work with customer
      tokens.)
security:
  - OAuth2: []
tags:
  - name: Transactions
    description: Endpoints for transaction data.
  - name: Accounts
    description: Endpoints for account data.
paths:
  /v2/accounts/card:
    get:
      tags:
        - Accounts
      summary: |

        List card accounts
      description: |

        This endpoint lists all accounts of card type.
      operationId: listCardAccounts
      responses:
        '200':
          description: Returns a list of card accounts.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CardAccount'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
      security:
        - OAuth2:
            - accounts.card.readonly
  /v2/accounts/card/primary/statements:
    get:
      tags:
        - Accounts
      summary: |

        List primary card account statements. 
      description: >

        This endpoint lists all finalized statements for the primary card
        account.
      operationId: listPrimaryCardStatements
      parameters:
        - name: cursor
          in: query
          schema:
            type: string
            nullable: true
        - name: limit
          in: query
          schema:
            type: integer
            format: int32
            nullable: true
      responses:
        '200':
          description: Returns a list of primary card account statements.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Page_Statement_'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
      security:
        - OAuth2:
            - statements.card.readonly
  /v2/accounts/cash:
    get:
      tags:
        - Accounts
      summary: |

        List cash accounts
      description: |

        This endpoint lists all the existing cash accounts with their status.
      operationId: listAccounts
      responses:
        '200':
          description: Returns a list of cash accounts.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Page_CashAccount_'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
      security:
        - OAuth2:
            - accounts.cash.readonly
  /v2/accounts/cash/primary:
    get:
      tags:
        - Accounts
      summary: |

        Get primary cash account
      description: >

        This endpoint returns the primary cash account with its status. There
        will always be only one primary account.
      operationId: getPrimaryAccount
      responses:
        '200':
          description: Returns the primary cash account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CashAccount'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
      security:
        - OAuth2:
            - accounts.cash.readonly
  /v2/accounts/cash/{id}:
    get:
      tags:
        - Accounts
      summary: |

        Get cash account by ID
      description: >

        This endpoint returns the cash account associated with the provided ID
        with its status.
      operationId: getAccount
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Returns the cash account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CashAccount'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
      security:
        - OAuth2:
            - accounts.cash.readonly
  /v2/accounts/cash/{id}/statements:
    get:
      tags:
        - Accounts
      summary: |

        List cash account statements.    
      description: |

        This endpoint lists all finalized statements for the cash account by ID.
      operationId: listCashStatements
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
        - name: cursor
          in: query
          schema:
            type: string
            nullable: true
        - name: limit
          in: query
          schema:
            type: integer
            format: int32
            nullable: true
      responses:
        '200':
          description: Returns a list of cash account statements.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Page_Statement_'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
      security:
        - OAuth2:
            - statements.cash.readonly
  /v2/transactions/card/primary:
    get:
      tags:
        - Transactions
      summary: |

        List transactions for all card accounts.
      description: >

        This endpoint lists all settled transactions for all card accounts.

        Regular users may only fetch their own "PURCHASE","REFUND" and
        "CHARGEBACK" settled transactions.


        Note: there may be a small lag when fetching transactions with cursor
        and time ranges. It is important

        to have at least a 1+ day lookback when syncing transactions to ensure
        the delayed transactions are

        properly handled.
      operationId: listPrimaryCardTransactions
      parameters:
        - name: cursor
          in: query
          schema:
            type: string
            nullable: true
        - name: limit
          in: query
          schema:
            type: integer
            format: int32
            nullable: true
        - name: user_ids
          in: query
          schema:
            type: array
            nullable: true
            items:
              type: string
        - name: posted_at_start
          in: query
          description: >

            Shows only transactions with a `posted_at_date` on or after this
            date-time. This parameter is the date-time notation as defined by
            [RFC 3339, section
            5.6](https://tools.ietf.org/html/rfc3339#section-5.6)


            When polling for new transactions, we recommend using a lookback
            window that overlaps with your previous request rather than
            advancing `posted_at_start` to the exact time of your last poll. Set
            `posted_at_start` earlier than the end of your previous query window
            (we recommend overlapping by a few days) so that transactions are
            not missed if a prior request or response failed, or if a
            transaction was posted with a slight delay. De-duplicate the
            overlapping results by transaction `id`.
          schema:
            type: string
            format: date-time
            nullable: true
          example: |

            2022-12-12T23:59:59.999
        - name: expand[]
          in: query
          schema:
            type: array
            description: >-
              `expense_id` can be passed to `expand[]` query parameter to get
              expanded, e.g., `?expand[]=expense_id`.
            nullable: true
            items:
              type: string
      responses:
        '200':
          description: Returns a list of card transactions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Page_CardTransaction_'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
      security:
        - OAuth2:
            - transactions.card.readonly
  /v2/transactions/cash/{id}:
    get:
      tags:
        - Transactions
      summary: |

        List transactions for the selected cash account.
      description: >

        This endpoint lists all transactions for the cash account with the
        selected ID.
      operationId: listCashTransactions
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
        - name: cursor
          in: query
          schema:
            type: string
            nullable: true
        - name: limit
          in: query
          schema:
            type: integer
            format: int32
            nullable: true
        - name: posted_at_start
          in: query
          description: >

            Shows only transactions with a `posted_at_date` on or after this
            date-time. This parameter is the date-time notation as defined by
            [RFC 3339, section
            5.6](https://tools.ietf.org/html/rfc3339#section-5.6)


            When polling for new transactions, we recommend using a lookback
            window that overlaps with your previous request rather than
            advancing `posted_at_start` to the exact time of your last poll. Set
            `posted_at_start` earlier than the end of your previous query window
            (for example, overlapping by a few days) so that transactions are
            not missed if a prior request or response failed, or if a
            transaction was posted with a slight delay. De-duplicate the
            overlapping results by transaction `id`.
          schema:
            type: string
            format: date-time
            nullable: true
          example: |

            2022-12-12T23:59:59.999
      responses:
        '200':
          description: Returns a list of cash transactions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Page_CashTransaction_'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
      security:
        - OAuth2:
            - transactions.cash.readonly
components:
  schemas:
    CardAccount:
      required:
        - current_statement_period
        - id
      type: object
      properties:
        id:
          type: string
          description: ID of the card account
        status:
          nullable: true
          allOf:
            - $ref: '#/components/schemas/Status'
        current_balance:
          nullable: true
          allOf:
            - $ref: '#/components/schemas/Money'
        available_balance:
          nullable: true
          allOf:
            - $ref: '#/components/schemas/Money'
        account_limit:
          nullable: true
          allOf:
            - $ref: '#/components/schemas/Money'
        current_statement_period:
          $ref: '#/components/schemas/StatementPeriod'
    CardTransaction:
      required:
        - amount
        - description
        - id
        - initiated_at_date
        - posted_at_date
      type: object
      properties:
        id:
          type: string
        card_id:
          type: string
          description: >-
            ID of the card used for the transaction. Null when type is
            REWARDS_CREDIT or COLLECTION.
          nullable: true
        description:
          type: string
          description: Description of the transaction
        amount:
          $ref: '#/components/schemas/Money'
        initiated_at_date:
          type: string
          description: ISO 8601 date string
          format: date
        posted_at_date:
          type: string
          description: ISO 8601 date string
          format: date
        type:
          nullable: true
          allOf:
            - $ref: '#/components/schemas/CardTransactionType'
        merchant:
          nullable: true
          allOf:
            - $ref: '#/components/schemas/Merchant'
        card_metadata:
          type: object
          additionalProperties:
            type: string
          description: >

            Set of key value pairs associated with this object. Please do not
            store any personally identifiable or sensitive information here.

            Limitations: maximum of 50 keys, keys cannot exceed 40 characters,
            values cannot exceed 500 characters. 
          nullable: true
        expense_id:
          type: string
          description: The expense ID related to the card transaction.
          nullable: true
        card_transaction_operation_reference_id:
          type: string
          description: >-
            The card transaction operation reference ID. Null when type is
            REWARDS_CREDIT, COLLECTION, or BNPL_FEE.
          nullable: true
    CardTransactionType:
      type: string
      enum:
        - PURCHASE
        - REFUND
        - CHARGEBACK
        - REWARDS_CREDIT
        - COLLECTION
        - BNPL_FEE
    CashAccount:
      required:
        - account_number
        - available_balance
        - current_balance
        - id
        - name
        - primary
        - routing_number
      type: object
      properties:
        id:
          type: string
          description: ID of the cash account
        name:
          type: string
        status:
          nullable: true
          allOf:
            - $ref: '#/components/schemas/Status'
        current_balance:
          $ref: '#/components/schemas/Money'
        available_balance:
          $ref: '#/components/schemas/Money'
        account_number:
          type: string
        routing_number:
          type: string
        primary:
          type: boolean
          description: >-
            Whether or not this account is the primary account. There will
            always be only one primary account.
    CashTransaction:
      required:
        - description
        - id
        - initiated_at_date
        - posted_at_date
      type: object
      properties:
        id:
          type: string
        description:
          type: string
          description: Description of the transaction
        amount:
          nullable: true
          allOf:
            - $ref: '#/components/schemas/Money'
        initiated_at_date:
          type: string
          description: ISO 8601 date of when the payment is initiated
          format: date
        posted_at_date:
          type: string
          description: ISO 8601 date of when the payment is posted
          format: date
        type:
          nullable: true
          allOf:
            - $ref: '#/components/schemas/CashTransactionType'
        transfer_id:
          type: string
          description: >-
            Transfer ID to fetch additional metadata about the transaction using
            `https://developer.brex.com/openapi/payments_api/#operation/getTransfersById`
          nullable: true
    CashTransactionType:
      type: string
      enum:
        - PAYMENT
        - DIVIDEND
        - FEE
        - ADJUSTMENT
        - INTEREST
        - CARD_COLLECTION
        - REWARDS_REDEMPTION
        - RECEIVABLES_OFFERS_ADVANCE
        - FBO_TRANSFER
        - RECEIVABLES_OFFERS_REPAYMENT
        - RECEIVABLES_OFFERS_COLLECTION
        - BREX_OPERATIONAL_TRANSFER
        - INTRA_CUSTOMER_ACCOUNT_BOOK_TRANSFER
        - BOOK_TRANSFER
        - CRYPTO_BRIDGE
        - STABLECOIN
        - TRANSACTION_FEES_COLLECTION
        - PAYBACK
    Merchant:
      required:
        - country
        - mcc
        - raw_descriptor
      type: object
      properties:
        raw_descriptor:
          type: string
          description: Merchant descriptor, it can be the merchant name.
        mcc:
          type: string
          description: >-
            A four-digit number listed in ISO 18245 for retail financial
            services, e.g. 4121 for Taxicabs and Rideshares. Please refer to
            https://en.wikipedia.org/wiki/Merchant_category_code for more
            details.
        country:
          type: string
          description: Merchant's country, in ISO 3166-1 alpha-3 format.
    Money:
      required:
        - amount
      type: object
      properties:
        amount:
          type: integer
          description: >-
            The amount of money, in the smallest denomination of the currency
            indicated by currency. For example, when currency is USD, amount is
            in cents.
          format: int64
          example: 700
        currency:
          type: string
          description: The type of currency, in ISO 4217 format.
          nullable: true
          example: USD
          default: USD
      description: >

        Money fields can be signed or unsigned. Fields are signed (an unsigned
        value will be interpreted as positive). The amount of money will be
        represented in the smallest denomination

        of the currency indicated. For example, USD 7.00 will be represented in
        cents with an amount of 700.
    Page_CardTransaction_:
      required:
        - items
      type: object
      properties:
        next_cursor:
          type: string
          nullable: true
        items:
          type: array
          items:
            $ref: '#/components/schemas/CardTransaction'
    Page_CashAccount_:
      required:
        - items
      type: object
      properties:
        next_cursor:
          type: string
          nullable: true
        items:
          type: array
          items:
            $ref: '#/components/schemas/CashAccount'
    Page_CashTransaction_:
      required:
        - items
      type: object
      properties:
        next_cursor:
          type: string
          nullable: true
        items:
          type: array
          items:
            $ref: '#/components/schemas/CashTransaction'
    Page_Statement_:
      required:
        - items
      type: object
      properties:
        next_cursor:
          type: string
          nullable: true
        items:
          type: array
          items:
            $ref: '#/components/schemas/Statement'
    Statement:
      required:
        - id
        - period
      type: object
      properties:
        id:
          type: string
        start_balance:
          nullable: true
          allOf:
            - $ref: '#/components/schemas/Money'
        end_balance:
          nullable: true
          allOf:
            - $ref: '#/components/schemas/Money'
        period:
          $ref: '#/components/schemas/StatementPeriod'
    StatementPeriod:
      required:
        - end_date
        - start_date
      type: object
      properties:
        start_date:
          type: string
          description: Start date of the statement period at UTC 00:00:00 (inclusive)
          format: date
        end_date:
          type: string
          description: End date of the statement period at UTC 00:00:00 (exclusive)
          format: date
    Status:
      type: string
      enum:
        - ACTIVE
  securitySchemes:
    OAuth2:
      type: oauth2
      description: OAuth2 security scheme
      flows:
        authorizationCode:
          authorizationUrl: https://accounts-api.brex.com/oauth2/default/v1/authorize
          tokenUrl: https://accounts-api.brex.com/oauth2/default/v1/token
          scopes:
            openid: openid
            offline_access: offline access
            transactions.card.readonly: View card transaction data
            statements.card.readonly: View card statement data
            accounts.card.readonly: View card account data
            accounts.cash.readonly: View business accounts data
x-explorer-enabled: false
