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

    The payments API allows you to initiate and manage payments and vendors from
    your Brex business accounts.
  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: Vendors
    description: Endpoints to manage vendors
  - name: Transfers
    description: >-
      Endpoints to initiate transfers and view transfer statuses. Note that for
      all transfer endpoints, the 'money' field is positive or unsigned for
      outgoing transfers (debits), and negative for incoming transfers
      (credits).
  - name: Linked Accounts
    description: Endpoint to view connected linked accounts
paths:
  /v1/incoming_transfers:
    post:
      tags:
        - Transfers
      summary: |

        Create incoming transfer
      description: >

        This endpoint creates a new incoming transfer. You may use use any
        eligible bank account connection to fund (ACH Debit) 

        any active Brex business account.


        **Reminder**: You may not use the Brex API for any activity that
        requires a license or registration from any 

        governmental authority without Brex's prior review and approval. This
        includes but is not limited to any money services

        business or money transmission activity.


        Please review the <a
        href="https://www.brex.com/legal/developer-portal/">Brex Access
        Agreement</a> and contact us if 

        you have any questions.
      operationId: createIncomingTransfer
      parameters:
        - name: Idempotency-Key
          in: header
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateIncomingTransferRequest'
        required: true
      responses:
        '200':
          description: createIncomingTransfer 200 response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Transfer'
      security:
        - OAuth2:
            - incoming_transfers
  /v1/linked_accounts:
    get:
      tags:
        - Linked Accounts
      summary: |

        Lists linked accounts
      description: >

        This endpoint lists all bank connections that are eligible to make ACH
        transfers to Brex business account
      operationId: listLinkedAccounts
      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 bank connections
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Page_BankConnection_'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
      security:
        - OAuth2:
            - linked_accounts.readonly
  /v1/transfers:
    get:
      tags:
        - Transfers
      summary: |

        Lists transfers 
      description: >

        This endpoint lists existing transfers for an account.


        Currently, the API can only return transfers for the following payment
        rails:

        - ACH

        - DOMESTIC_WIRE

        - CHEQUE

        - INTERNATIONAL_WIRE
      operationId: listTransfers
      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 transfers.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Page_Transfer_'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '500':
          description: Internal server error
      security:
        - OAuth2:
            - transfers.readonly
            - incoming_transfers
    post:
      tags:
        - Transfers
      summary: |

        Create transfer
      description: >

        This endpoint creates a new transfer.


        Currently, the API can only create transfers for the following payment
        rails:

        - ACH

        - DOMESTIC_WIRE

        - CHEQUE

        - INTERNATIONAL_WIRES


        **Transaction Descriptions**

        * For outgoing check payments, a successful transfer will return a
        response containing a description value with a format of `Check #<check
        number> to <recipient_name> - <external_memo>`.

        * For book transfers (from one Brex Business account to another), the
        recipient value will have a format of `<customer_account.dba_name> -
        <external_memo>` and the sender will have a format of `<target customer
        account's dba name> - <external_memo>`.

        * For other payment rails, the format will be `<counterparty_name> -
        <external_memo>`, where Counterparty name is
        `payment_instrument.beneficiary_name` or `contact.name`

        For vendors created from the Payments API, the `counterparty_name` will
        be the `company_name`
        [field](/openapi/payments_api/#operation/createVendor!path=company_name&t=request).


        **Reminder**: You may not use the Brex API for any activity that
        requires a license or registration from any 

        governmental authority without Brex's prior review and approval. This
        includes but is not limited to any money services

        business or money transmission activity.


        Please review the <a
        href="https://www.brex.com/legal/developer-portal/">Brex Access
        Agreement</a> and contact us if 

        you have any questions.
      operationId: createTransfer
      parameters:
        - name: Idempotency-Key
          in: header
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTransferRequest'
        required: true
      responses:
        '200':
          description: createTransfer 200 response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Transfer'
      security:
        - OAuth2:
            - transfers
  /v1/transfers/{id}:
    get:
      tags:
        - Transfers
      summary: |

        Get transfer
      description: >

        This endpoint gets a transfer by ID.


        Currently, the API can only return transfers for the following payment
        rails:

        - ACH

        - DOMESTIC_WIRE

        - CHEQUE

        - INTERNATIONAL_WIRE
      operationId: getTransfersById
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Returns a transfer.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Transfer'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '500':
          description: Internal server error
      security:
        - OAuth2:
            - transfers.readonly
            - incoming_transfers
  /v1/vendors:
    get:
      tags:
        - Vendors
      summary: |

        Lists vendors 
      description: |

        This endpoint lists all existing vendors for an account.
        Takes an optional parameter to match by vendor name.
      operationId: listVendors
      parameters:
        - name: cursor
          in: query
          schema:
            type: string
            nullable: true
        - name: limit
          in: query
          schema:
            type: integer
            format: int32
            nullable: true
        - name: name
          in: query
          schema:
            type: string
            nullable: true
      responses:
        '200':
          description: Returns a list of vendor objects.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Page_VendorResponse_'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
      security:
        - OAuth2:
            - vendors.readonly
    post:
      tags:
        - Vendors
      summary: |

        Create vendor
      description: |

        This endpoint creates a new vendor.
      operationId: createVendor
      parameters:
        - name: Idempotency-Key
          in: header
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateVendorRequest'
        required: true
      responses:
        '200':
          description: createVendor 200 response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VendorResponse'
      security:
        - OAuth2:
            - vendors
  /v1/vendors/{id}:
    get:
      tags:
        - Vendors
      summary: |

        Get vendor
      description: |

        This endpoint gets a vendor by ID.
      operationId: getVendorById
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Returns a vendor object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VendorResponse'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '500':
          description: Internal server error
      security:
        - OAuth2:
            - vendors.readonly
    put:
      tags:
        - Vendors
      summary: Update vendor
      description: |2

            Updates an existing vendor by ID.
      operationId: updateVendor
      parameters:
        - name: Idempotency-Key
          in: header
          schema:
            type: string
            nullable: true
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateVendorRequest'
        required: true
      responses:
        '200':
          description: updateVendor 200 response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VendorResponse'
      security:
        - OAuth2:
            - vendors
    delete:
      tags:
        - Vendors
      summary: |

        Delete vendor.
      description: |

        This endpoint deletes a vendor by ID.
      operationId: deleteVendor
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: deleteVendor 200 response
      security:
        - OAuth2:
            - vendors
components:
  schemas:
    ACHDetailsRequest:
      type: object
      allOf:
        - $ref: '#/components/schemas/PaymentAccountDetails'
        - required:
            - account_class
            - account_number
            - account_type
            - routing_number
            - type
          properties:
            type:
              $ref: '#/components/schemas/PaymentDetailsTypeRequest'
            routing_number:
              type: string
              description: The routing number must follow proper format.
            account_number:
              type: string
            account_type:
              $ref: '#/components/schemas/AccountType'
            account_class:
              $ref: '#/components/schemas/AccountClass'
            beneficiary_name:
              type: string
              nullable: true
    ACHDetailsResponse:
      type: object
      allOf:
        - $ref: '#/components/schemas/PaymentAccountDetailsResponse'
        - required:
            - account_number
            - payment_instrument_id
            - routing_number
            - type
          properties:
            type:
              $ref: '#/components/schemas/PaymentDetailsTypeResponse'
            payment_instrument_id:
              type: string
              description: >
                Payment Instrument ID that can be passed to the /transfers
                endpoint to trigger a transfer.

                The type of the payment instrument dictates the method.
            routing_number:
              type: string
            account_number:
              type: string
            account_type:
              nullable: true
              allOf:
                - $ref: '#/components/schemas/AccountType'
            account_class:
              nullable: true
              allOf:
                - $ref: '#/components/schemas/AccountClass'
    AccountClass:
      type: string
      enum:
        - BUSINESS
        - PERSONAL
    AccountType:
      type: string
      enum:
        - CHECKING
        - SAVING
    Address:
      type: object
      properties:
        line1:
          type: string
          description: Address line 1, no PO Box.
          nullable: true
        line2:
          type: string
          description: Address line 2 (e.g., apartment, suite, unit, or building).
          nullable: true
        city:
          type: string
          description: City, district, suburb, town, or village.
          nullable: true
        state:
          type: string
          description: >-
            For US-addressed the 2-letter State abbreviation. For
            international-addresses the county, providence, or region.
          nullable: true
        country:
          type: string
          description: Two-letter country code (ISO 3166-1 alpha-2).
          nullable: true
        postal_code:
          type: string
          description: ZIP or postal code.
          nullable: true
        phone_number:
          type: string
          description: Phone number.
          nullable: true
      description: >-
        Company business address (must be in the US; no PO box or
        virtual/forwarding addresses allowed).
    ApprovalType:
      type: string
      description: >-
        Specifies the approval type for the transaction. 

        `MANUAL` requires a cash admin to approve the transaction before
        disbursing funds. 

        When not set, the default policy will apply.
      enum:
        - MANUAL
    Balance:
      required:
        - amount
        - as_of_date
      type: object
      properties:
        amount:
          $ref: '#/components/schemas/Money'
        as_of_date:
          type: string
          format: date
    BankAccountDetailsResponse:
      type: object
      allOf:
        - $ref: '#/components/schemas/CounterPartyResponse'
        - required:
            - type
          properties:
            type:
              $ref: '#/components/schemas/CounterPartyResponseType'
            routing_number:
              type: string
              description: >-
                Routing number of a bank account (or SWIFT/BIC code for
                international transfer). For incoming cheques, this field might
                be null.
              nullable: true
            account_number:
              type: string
              description: >-
                Account number of a bank account (or IBAN code for international
                transfer). For incoming cheques, this field might be null.
              nullable: true
            description:
              type: string
              description: Description of the transfer.
              nullable: true
            beneficiary_bank:
              nullable: true
              allOf:
                - $ref: '#/components/schemas/BeneficiaryBank'
                - description: Beneficiary Bank information
            fed_reference_number:
              type: string
              description: Fed reference number for incoming wires
              nullable: true
            external_memo:
              type: string
              description: External Memo populated by the sender
              nullable: true
    BankConnection:
      required:
        - bank_details
        - id
        - last_four
      type: object
      properties:
        id:
          type: string
        bank_details:
          allOf:
            - $ref: '#/components/schemas/BankDetails'
            - description: |

                Details of the bank - Name, Type
        brex_account_id:
          type: string
          description: |

            Brex business account ID
          nullable: true
        last_four:
          type: string
        available_balance:
          nullable: true
          allOf:
            - $ref: '#/components/schemas/Balance'
        current_balance:
          nullable: true
          allOf:
            - $ref: '#/components/schemas/Balance'
    BankDetails:
      required:
        - name
        - type
      type: object
      properties:
        name:
          type: string
          description: |

            The name of the bank
        type:
          allOf:
            - $ref: '#/components/schemas/BankType'
            - description: >

                The type of bank account connected. For example, CHECKING or
                SAVING
    BankType:
      type: string
      enum:
        - CHECKING
        - SAVING
    BeneficiaryBank:
      type: object
      properties:
        name:
          type: string
          nullable: true
        address:
          nullable: true
          allOf:
            - $ref: '#/components/schemas/Address'
    BookTransferDetails:
      type: object
      allOf:
        - $ref: '#/components/schemas/CounterParty'
        - required:
            - recipient
            - type
          properties:
            type:
              $ref: '#/components/schemas/CounterPartyType'
            recipient:
              $ref: '#/components/schemas/Recipient'
    BookTransferDetailsResponse:
      type: object
      allOf:
        - $ref: '#/components/schemas/CounterPartyResponse'
        - required:
            - deposit_account_id
            - type
          properties:
            type:
              $ref: '#/components/schemas/CounterPartyResponseType'
            deposit_account_id:
              type: string
              description: >-
                This feature is currently limited to certain customers, please
                reach out if you are interested
    BrexCashAccountDetails:
      type: object
      allOf:
        - $ref: '#/components/schemas/OriginatingAccount'
        - required:
            - id
            - type
          properties:
            type:
              $ref: '#/components/schemas/OriginatingAccountType'
            id:
              type: string
              description: >

                ID of the Brex Business account: Can be found from the
                `/accounts` endpoint

                where instrument type is `CASH`.
    BrexCashAccountDetailsResponse:
      type: object
      allOf:
        - $ref: '#/components/schemas/OriginatingAccountResponse'
        - required:
            - id
            - type
          properties:
            type:
              $ref: '#/components/schemas/OriginatingAccountResponseType'
            id:
              type: string
              description: |

                ID of the Brex Business account.
    BrexCashDetails:
      type: object
      allOf:
        - $ref: '#/components/schemas/ReceivingAccount'
        - required:
            - id
            - type
          properties:
            type:
              $ref: '#/components/schemas/ReceivingAccountType'
            id:
              type: string
              description: >

                ID of the Brex business account: Can be found from the [List
                business
                accounts](/openapi/transactions_api/#operation/listAccounts)
                endpoint
    ChequeDetailsRequest:
      type: object
      allOf:
        - $ref: '#/components/schemas/PaymentAccountDetails'
        - required:
            - mailing_address
            - recipient_name
            - type
          properties:
            type:
              $ref: '#/components/schemas/PaymentDetailsTypeRequest'
            mailing_address:
              $ref: '#/components/schemas/Address'
            recipient_name:
              maxLength: 40
              type: string
            beneficiary_name:
              type: string
              nullable: true
    ChequeDetailsResponse:
      type: object
      allOf:
        - $ref: '#/components/schemas/PaymentAccountDetailsResponse'
        - required:
            - mailing_address
            - payment_instrument_id
            - recipient_name
            - type
          properties:
            type:
              $ref: '#/components/schemas/PaymentDetailsTypeResponse'
            payment_instrument_id:
              type: string
              description: >
                Payment Instrument ID that can be passed to the /transfers
                endpoint to trigger a transfer.

                The type of the payment instrument dictates the method.
            mailing_address:
              $ref: '#/components/schemas/Address'
            recipient_name:
              type: string
    CounterParty:
      type: object
      description: Counterparty Details for the transfer
      discriminator:
        propertyName: type
        mapping:
          BOOK_TRANSFER: '#/components/schemas/BookTransferDetails'
          VENDOR: '#/components/schemas/VendorDetails'
      oneOf:
        - $ref: '#/components/schemas/VendorDetails'
        - $ref: '#/components/schemas/BookTransferDetails'
    CounterPartyBankDetails:
      type: object
      allOf:
        - $ref: '#/components/schemas/CounterPartyIncomingTransfer'
        - required:
            - id
            - type
          properties:
            type:
              $ref: '#/components/schemas/CounterPartyIncomingTransferType'
            id:
              type: string
              description: >

                The financial account id: Can be found from the [List linked
                accounts](/openapi/payments_api/#operation/listLinkedAccounts)
                endpoint
    CounterPartyIncomingTransfer:
      type: object
      description: Counterparty Details for the transfer
      discriminator:
        propertyName: type
        mapping:
          BANK: '#/components/schemas/CounterPartyBankDetails'
      oneOf:
        - $ref: '#/components/schemas/CounterPartyBankDetails'
    CounterPartyIncomingTransferType:
      type: string
      enum:
        - BANK
    CounterPartyResponse:
      type: object
      description: >-
        Counterparty Details for the transfer - Currently only supports vendors
        that are returned in the 

        response from the /vendors endpoint

        BOOK_TRANSFER is a limited feature. Please reach out if you are
        interested.
            
      discriminator:
        propertyName: type
        mapping:
          BANK_ACCOUNT: '#/components/schemas/BankAccountDetailsResponse'
          BOOK_TRANSFER: '#/components/schemas/BookTransferDetailsResponse'
          VENDOR: '#/components/schemas/VendorDetailsResponse'
      oneOf:
        - $ref: '#/components/schemas/VendorDetailsResponse'
    CounterPartyResponseType:
      type: string
      enum:
        - VENDOR
        - BOOK_TRANSFER
        - BANK_ACCOUNT
    CounterPartyType:
      type: string
      enum:
        - VENDOR
        - BOOK_TRANSFER
    CreateIncomingTransferRequest:
      required:
        - amount
        - counterparty
        - description
        - receiving_account
      type: object
      properties:
        counterparty:
          $ref: '#/components/schemas/CounterPartyIncomingTransfer'
        receiving_account:
          $ref: '#/components/schemas/ReceivingAccount'
        amount:
          $ref: '#/components/schemas/Money'
        description:
          type: string
          description: >2
             
            Description of the transfer for internal use. Not exposed
            externally. 
    CreateTransferRequest:
      required:
        - amount
        - counterparty
        - description
        - external_memo
        - originating_account
      type: object
      properties:
        counterparty:
          $ref: '#/components/schemas/CounterParty'
        amount:
          $ref: '#/components/schemas/Money'
        description:
          type: string
          description: >-
            Description of the transfer for internal use. Not exposed
            externally.
        external_memo:
          maxLength: 90
          type: string
          description: >
            External memo for the transfer. `Payment Instructions` for Wires and
            the `Entry Description` for ACH payments. 

            Must be at most 90 characters for `ACH` and `WIRE` transactions

            and at most 40 characters for `CHEQUES`
        originating_account:
          allOf:
            - $ref: '#/components/schemas/OriginatingAccount'
            - description: >
                Brex originating account details. Account IDs are returned by
                the /accounts

                endpoint. This endpoint currently only supports accounts with
                instrument type `CASH` (Brex business accounts)

                Currently only USD transfers are supported and amount should be
                positive
        approval_type:
          nullable: true
          allOf:
            - $ref: '#/components/schemas/ApprovalType'
        is_ppro_enabled:
          type: boolean
          description: >
            When set to true, add Principal Protection (PPRO) to the
            transaction.
             PPRO means Brex will cover any fees charged by intemediary or receiving banks. PPRO charges will be billed separately
             in a monthly statement. PPRO is only available for international wire transactions.
    CreateVendorRequest:
      required:
        - company_name
      type: object
      properties:
        company_name:
          type: string
          description: Name for vendor. The name must be unique.
        email:
          type: string
          description: Email for vendor.
          format: email
          nullable: true
        phone:
          type: string
          description: Phone number for vendor.
          nullable: true
        payment_accounts:
          type: array
          description: Payment accounts associated with the vendor.
          nullable: true
          items:
            $ref: '#/components/schemas/PaymentAccountRequest'
    DomesticWireDetailsRequest:
      type: object
      allOf:
        - $ref: '#/components/schemas/PaymentAccountDetails'
        - required:
            - account_number
            - address
            - routing_number
            - type
          properties:
            type:
              $ref: '#/components/schemas/PaymentDetailsTypeRequest'
            routing_number:
              type: string
              description: The routing number must follow proper format.
            account_number:
              type: string
            address:
              $ref: '#/components/schemas/Address'
            beneficiary_name:
              type: string
              nullable: true
    DomesticWireDetailsResponse:
      type: object
      allOf:
        - $ref: '#/components/schemas/PaymentAccountDetailsResponse'
        - required:
            - account_number
            - address
            - payment_instrument_id
            - routing_number
            - type
          properties:
            type:
              $ref: '#/components/schemas/PaymentDetailsTypeResponse'
            payment_instrument_id:
              type: string
              description: >
                Payment Instrument ID that can be passed to the /transfers
                endpoint to trigger a transfer.

                The type of the payment instrument dictates the method.
            routing_number:
              type: string
            account_number:
              type: string
            address:
              $ref: '#/components/schemas/Address'
    InternationalWireDetailsResponse:
      type: object
      allOf:
        - $ref: '#/components/schemas/PaymentAccountDetailsResponse'
        - required:
            - address
            - iban
            - payment_instrument_id
            - swift_code
            - type
          properties:
            type:
              $ref: '#/components/schemas/PaymentDetailsTypeResponse'
            payment_instrument_id:
              type: string
              description: >
                Payment Instrument ID that can be passed to the /transfers
                endpoint to trigger a transfer.

                The type of the payment instrument dictates the method.
            swift_code:
              type: string
              description: Counterparty's `SWIFT` code
            iban:
              type: string
              description: Counterparty's international bank account number
            beneficiary_bank_name:
              type: string
              description: Name of counterparty's bank
              nullable: true
            address:
              $ref: '#/components/schemas/Address'
    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.
    OriginatingAccount:
      type: object
      description: Originating account details for the transfer
      discriminator:
        propertyName: type
        mapping:
          BREX_CASH: '#/components/schemas/BrexCashAccountDetails'
      oneOf:
        - $ref: '#/components/schemas/BrexCashAccountDetails'
    OriginatingAccountResponse:
      type: object
      description: Originating account details for the transfer
      discriminator:
        propertyName: type
        mapping:
          BREX_CASH: '#/components/schemas/BrexCashAccountDetailsResponse'
      oneOf:
        - $ref: '#/components/schemas/BrexCashAccountDetailsResponse'
    OriginatingAccountResponseType:
      type: string
      enum:
        - BREX_CASH
    OriginatingAccountType:
      type: string
      enum:
        - BREX_CASH
    Page_BankConnection_:
      required:
        - items
      type: object
      properties:
        next_cursor:
          type: string
          nullable: true
        items:
          type: array
          items:
            $ref: '#/components/schemas/BankConnection'
    Page_Transfer_:
      required:
        - items
      type: object
      properties:
        next_cursor:
          type: string
          nullable: true
        items:
          type: array
          items:
            $ref: '#/components/schemas/Transfer'
    Page_VendorResponse_:
      required:
        - items
      type: object
      properties:
        next_cursor:
          type: string
          nullable: true
        items:
          type: array
          items:
            $ref: '#/components/schemas/VendorResponse'
    PaymentAccountDetails:
      type: object
      description: >
        Payment Instruments associated with the vendor.

        Each vendor can only have one payment account per payment instrument
        type. For instance, a vendor may have associated details for each of
        ACH, DOMESTIC_WIRE, and CHEQUE, but they cannot have 2 entries for ACH.
        If you modify a vendor's existing payment instrument type with new
        details, it will overwrite any previous data.
      discriminator:
        propertyName: type
        mapping:
          DOMESTIC_WIRE: '#/components/schemas/DomesticWireDetailsRequest'
          ACH: '#/components/schemas/ACHDetailsRequest'
          CHEQUE: '#/components/schemas/ChequeDetailsRequest'
      oneOf:
        - $ref: '#/components/schemas/ACHDetailsRequest'
        - $ref: '#/components/schemas/DomesticWireDetailsRequest'
        - $ref: '#/components/schemas/ChequeDetailsRequest'
    PaymentAccountDetailsResponse:
      type: object
      discriminator:
        propertyName: type
        mapping:
          DOMESTIC_WIRE: '#/components/schemas/DomesticWireDetailsResponse'
          ACH: '#/components/schemas/ACHDetailsResponse'
          CHEQUE: '#/components/schemas/ChequeDetailsResponse'
          INTERNATIONAL_WIRE: '#/components/schemas/InternationalWireDetailsResponse'
      oneOf:
        - $ref: '#/components/schemas/ACHDetailsResponse'
        - $ref: '#/components/schemas/DomesticWireDetailsResponse'
        - $ref: '#/components/schemas/ChequeDetailsResponse'
        - $ref: '#/components/schemas/InternationalWireDetailsResponse'
    PaymentAccountRequest:
      required:
        - details
      type: object
      properties:
        details:
          $ref: '#/components/schemas/PaymentAccountDetails'
    PaymentAccountResponse:
      required:
        - details
      type: object
      properties:
        details:
          $ref: '#/components/schemas/PaymentAccountDetailsResponse'
    PaymentDetailsTypeRequest:
      type: string
      enum:
        - ACH
        - DOMESTIC_WIRE
        - CHEQUE
    PaymentDetailsTypeResponse:
      type: string
      enum:
        - ACH
        - DOMESTIC_WIRE
        - CHEQUE
        - INTERNATIONAL_WIRE
    PaymentType:
      type: string
      enum:
        - ACH
        - DOMESTIC_WIRE
        - CHEQUE
        - INTERNATIONAL_WIRE
        - BOOK_TRANSFER
        - STABLECOIN
    ReceivingAccount:
      type: object
      description: Receiving account details for the transfer
      discriminator:
        propertyName: type
        mapping:
          BREX_CASH: '#/components/schemas/BrexCashDetails'
      oneOf:
        - $ref: '#/components/schemas/BrexCashDetails'
    ReceivingAccountType:
      type: string
      enum:
        - BREX_CASH
    Recipient:
      required:
        - id
        - type
      type: object
      properties:
        type:
          $ref: '#/components/schemas/RecipientType'
        id:
          type: string
    RecipientType:
      type: string
      description: >
        Specifies the type of the recipient. 

        `ACCOUNT_ID` is the ID of a Brex Business account.

        `PAYMENT_INSTRUMENT_ID` is the ID of Payment Instrument of the receiving
        Brex account.
      enum:
        - ACCOUNT_ID
        - PAYMENT_INSTRUMENT_ID
    Transfer:
      required:
        - amount
        - id
        - originating_account
        - payment_type
        - status
      type: object
      properties:
        id:
          type: string
          description: Unique ID associated with the transfer
        counterparty:
          nullable: true
          allOf:
            - $ref: '#/components/schemas/CounterPartyResponse'
        description:
          type: string
          description: Description of the transfer
          nullable: true
        payment_type:
          $ref: '#/components/schemas/PaymentType'
        amount:
          $ref: '#/components/schemas/Money'
        process_date:
          type: string
          description: Transaction processing date
          format: date
          nullable: true
        originating_account:
          $ref: '#/components/schemas/OriginatingAccountResponse'
        status:
          $ref: '#/components/schemas/TransferStatus'
        cancellation_reason:
          nullable: true
          allOf:
            - $ref: '#/components/schemas/TransferCancellationReason'
        estimated_delivery_date:
          type: string
          description: Estimated delivery date for transfer
          format: date
          nullable: true
        creator_user_id:
          type: string
          description: User ID of the transfer initiator
          nullable: true
        created_at:
          type: string
          description: Date of transfer creation
          format: date
          nullable: true
        display_name:
          type: string
          description: Human readable name for the transaction
          nullable: true
        external_memo:
          maxLength: 90
          type: string
          description: >
            External memo for the transfer. `Payment Instructions` for Wires and
            the `Entry Description` for ACH payments. 

            Must be at most 90 characters for `ACH` and `WIRE` transactions

            and at most 40 characters for `CHEQUES`
          nullable: true
        is_ppro_enabled:
          type: boolean
          description: If Principal Protection (PPRO) is enabled
          nullable: true
    TransferCancellationReason:
      type: string
      description: >
        `USER_CANCELLED`: The transfer was canceled.

        `INSUFFICIENT_FUNDS`: The transfer could not be sent due to insufficient
        funds.

        `APPROVAL_DENIED`: The transfer was not sent because it was denied.

        `BLOCKED_BY_POSITIVE_PAY`: The transfer was blocked because of the ACH
        debit settings.
      enum:
        - USER_CANCELLED
        - INSUFFICIENT_FUNDS
        - APPROVAL_DENIED
        - BLOCKED_BY_POSITIVE_PAY
    TransferStatus:
      type: string
      description: >
        `PROCESSING`: We have started to process the sending or receiving of
        this transaction.

        `SCHEDULED`: The transaction is scheduled to enter the `PROCESSING`
        status.

        `PENDING_APPROVAL`: The transaction requires approval before it can
        enter the `SCHEDULED` or `PROCESSING` status.

        `FAILED`: A grouping of multiple terminal states that prevented the
        transaction from completing.

        This includes a a user-cancellation, approval being denied, insufficient
        funds, failed verifications, etc.

        `PROCESSED`: The money movement has been fully completed, which could
        mean money sent has arrived.
      enum:
        - PROCESSING
        - SCHEDULED
        - PENDING_APPROVAL
        - FAILED
        - PROCESSED
    UpdateVendorRequest:
      type: object
      properties:
        company_name:
          type: string
          description: Name for vendor
          nullable: true
        email:
          type: string
          description: Email for vendor
          format: email
          nullable: true
        phone:
          type: string
          description: Phone number for vendor
          nullable: true
        payment_accounts:
          type: array
          description: >
            To update payment instruments, we require the entire payload for
            each payment instrument that is being updated.
          nullable: true
          items:
            $ref: '#/components/schemas/PaymentAccountRequest'
        beneficiary_name:
          type: string
          description: Name for the Beneficiary
          nullable: true
    VendorDetails:
      type: object
      allOf:
        - $ref: '#/components/schemas/CounterParty'
        - required:
            - payment_instrument_id
            - type
          properties:
            type:
              $ref: '#/components/schemas/CounterPartyType'
            payment_instrument_id:
              type: string
              description: >
                ID of the vendor's payment instrument: this will dictate the
                payment method and the

                counterparty of the transaction.

                The payment instrument ID is returned from the /vendors response
                and the type of the

                instrument will dictate the payment method.

                eg. Passing an instrument ID of type ACH will trigger an ACH
                payment to the associated vendor.

                Since a payment instrument can be updated while retaining the
                same payment_instrument_id, 

                please make sure to double check the details.
    VendorDetailsResponse:
      type: object
      allOf:
        - $ref: '#/components/schemas/CounterPartyResponse'
        - required:
            - id
            - payment_instrument_id
            - type
          properties:
            type:
              $ref: '#/components/schemas/CounterPartyResponseType'
            payment_instrument_id:
              type: string
            id:
              type: string
              description: Vendor ID returned from `/vendors` endpoint
            routing_number:
              type: string
              description: >-
                Routing number of a bank account (or SWIFT/BIC code for
                international transfer).
              nullable: true
            account_number:
              type: string
              description: >-
                Account number of a bank account (or IBAN code for international
                transfer).
              nullable: true
    VendorResponse:
      required:
        - id
      type: object
      properties:
        id:
          type: string
          description: >
            Vendor ID: Can be passed to /transfers endpoint to specify
            counterparty.
        company_name:
          type: string
          nullable: true
        email:
          type: string
          nullable: true
        phone:
          type: string
          nullable: true
        payment_accounts:
          type: array
          nullable: true
          items:
            $ref: '#/components/schemas/PaymentAccountResponse'
  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
            vendors: View and manage vendor data
            vendors.readonly: View vendor data
            transfers: View and manage transfer data
            transfers.readonly: View transfer data
            incoming_transfers: View and manage incoming transfer data
            linked_accounts.readonly: View linked accounts
x-explorer-enabled: false
