Modern Treasury VirtualAccount API

openapi: 3.0.1
info:
  title: Modern Treasury AccountCapability VirtualAccount API
  version: v1
  contact:
    name: Modern Treasury Engineering Team
    url: https://moderntreasury.com
  description: The Modern Treasury REST API. Please see https://docs.moderntreasury.com for more details.
servers:
- url: http://localhost:3000
- url: https://app.moderntreasury.com
tags:
- name: VirtualAccount
paths:
  /api/virtual_accounts:
    get:
      summary: list virtual_accounts
      tags:
      - VirtualAccount
      operationId: listVirtualAccounts
      security:
      - basic_auth: []
      description: Get a list of virtual accounts.
      parameters:
      - name: after_cursor
        in: query
        schema:
          type: string
          nullable: true
        required: false
      - name: per_page
        in: query
        required: false
        schema:
          type: integer
      - name: internal_account_id
        in: query
        schema:
          type: string
        required: false
      - name: counterparty_id
        in: query
        schema:
          type: string
        required: false
      - $ref: '#/components/parameters/metadata_query'
      responses:
        '200':
          description: successful
          headers:
            X-After-Cursor:
              schema:
                type: string
                nullable: true
              required: false
              description: The cursor for the next page. Including this in a call as `after_cursor` will return the next page.
            X-Per-Page:
              schema:
                type: integer
                nullable: true
              description: The current `per_page`.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/virtual_account'
        '401':
          description: unsuccessful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_message'
    post:
      summary: create virtual_account
      tags:
      - VirtualAccount
      operationId: createVirtualAccount
      security:
      - basic_auth: []
      parameters:
      - name: Idempotency-Key
        in: header
        required: false
        description: This key should be something unique, preferably something like an UUID.
        schema:
          type: string
      responses:
        '201':
          description: successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/virtual_account'
        '401':
          description: unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_message'
        '422':
          description: unsuccessful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_message'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/virtual_account_create_request'
  /api/virtual_accounts/{id}:
    parameters:
    - name: id
      in: path
      schema:
        type: string
      required: true
      description: Virtual Acccount ID
    get:
      summary: get virtual_account
      tags:
      - VirtualAccount
      operationId: getVirtualAccount
      security:
      - basic_auth: []
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/virtual_account'
        '404':
          description: not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_message'
    patch:
      summary: update virtual_account
      tags:
      - VirtualAccount
      operationId: updateVirtualAccount
      security:
      - basic_auth: []
      parameters: []
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/virtual_account'
        '422':
          description: unsuccessful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_message'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/virtual_account_update_request'
    delete:
      summary: delete virtual_account
      tags:
      - VirtualAccount
      operationId: deleteVirtualAccount
      security:
      - basic_auth: []
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/virtual_account'
components:
  schemas:
    address:
      type: object
      properties:
        id:
          type: string
          format: uuid
        object:
          type: string
        live_mode:
          type: boolean
          description: This field will be true if this object exists in the live environment or false if it exists in the test environment.
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        line1:
          type: string
          nullable: true
        line2:
          type: string
          nullable: true
        locality:
          type: string
          nullable: true
          description: Locality or City.
        region:
          type: string
          nullable: true
          description: Region or State.
        postal_code:
          type: string
          description: The postal code of the address.
          nullable: true
        country:
          type: string
          description: Country code conforms to [ISO 3166-1 alpha-2]
          nullable: true
      nullable: true
      additionalProperties: false
      minProperties: 11
      required:
      - id
      - object
      - live_mode
      - created_at
      - updated_at
      - line1
      - line2
      - locality
      - region
      - postal_code
      - country
    account_detail:
      type: object
      properties:
        id:
          type: string
          format: uuid
        object:
          type: string
        live_mode:
          type: boolean
          description: This field will be true if this object exists in the live environment or false if it exists in the test environment.
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        discarded_at:
          type: string
          format: date-time
          nullable: true
        account_number:
          type: string
          description: The account number for the bank account.
        account_number_type:
          type: string
          enum:
          - au_number
          - base_address
          - card_token
          - clabe
          - ethereum_address
          - hk_number
          - iban
          - id_number
          - nz_number
          - other
          - pan
          - polygon_address
          - sg_number
          - solana_address
          - wallet_address
          description: One of `iban`, `clabe`, `wallet_address`, or `other`. Use `other` if the bank account number is in a generic format.
        account_number_safe:
          type: string
          description: The last 4 digits of the account_number.
      additionalProperties: false
      minProperties: 8
      maxProperties: 9
      required:
      - id
      - object
      - live_mode
      - created_at
      - updated_at
      - discarded_at
      - account_number_type
      - account_number_safe
    virtual_account_create_request:
      type: object
      properties:
        name:
          type: string
          description: The name of the virtual account.
        description:
          type: string
          description: An optional description for internal use.
        counterparty_id:
          type: string
          format: uuid
          description: The ID of the counterparty that the virtual account belongs to.
        internal_account_id:
          type: string
          format: uuid
          description: The ID of the internal account that this virtual account is associated with.
        account_details:
          type: array
          items:
            $ref: '#/components/schemas/account_detail_create_request'
          description: An array of account detail objects.
        routing_details:
          type: array
          items:
            $ref: '#/components/schemas/routing_detail_create_request'
          description: An array of routing detail objects.
        debit_ledger_account_id:
          type: string
          format: uuid
          description: The ID of a debit normal ledger account. When money enters the virtual account, this ledger account will be debited. Must be accompanied by a credit_ledger_account_id if present.
        credit_ledger_account_id:
          type: string
          format: uuid
          description: The ID of a credit normal ledger account. When money leaves the virtual account, this ledger account will be credited. Must be accompanied by a debit_ledger_account_id if present.
        ledger_account:
          $ref: '#/components/schemas/ledger_account_create_request'
          description: Specifies a ledger account object that will be created with the virtual account. The resulting ledger account is linked to the virtual account for auto-ledgering IPDs.
        metadata:
          type: object
          description: Additional data represented as key-value pairs. Both the key and value must be strings.
          additionalProperties:
            type: string
      required:
      - name
      - internal_account_id
    account_detail_create_request:
      type: object
      properties:
        account_number:
          type: string
          description: The account number for the bank account.
        account_number_type:
          type: string
          enum:
          - au_number
          - base_address
          - card_token
          - clabe
          - ethereum_address
          - hk_number
          - iban
          - id_number
          - nz_number
          - other
          - pan
          - polygon_address
          - sg_number
          - solana_address
          - wallet_address
          description: One of `iban`, `clabe`, `wallet_address`, or `other`. Use `other` if the bank account number is in a generic format.
      required:
      - account_number
    virtual_account:
      type: object
      properties:
        id:
          type: string
          format: uuid
        object:
          type: string
        live_mode:
          type: boolean
          description: This field will be true if this object exists in the live environment or false if it exists in the test environment.
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        discarded_at:
          type: string
          format: date-time
          nullable: true
        name:
          type: string
          description: The name of the virtual account.
        description:
          type: string
          description: An optional free-form description for internal use.
          nullable: true
        counterparty_id:
          type: string
          format: uuid
          description: The ID of a counterparty that the virtual account belongs to. Optional.
          nullable: true
        internal_account_id:
          type: string
          format: uuid
          description: The ID of the internal account that the virtual account is in.
        account_details:
          type: array
          description: An array of account detail objects.
          items:
            $ref: '#/components/schemas/account_detail'
        routing_details:
          type: array
          description: An array of routing detail objects. These will be the routing details of the internal account.
          items:
            $ref: '#/components/schemas/routing_detail'
        debit_ledger_account_id:
          type: string
          format: uuid
          description: The ID of a debit normal ledger account. When money enters the virtual account, this ledger account will be debited. Must be accompanied by a credit_ledger_account_id if present.
          nullable: true
        credit_ledger_account_id:
          type: string
          format: uuid
          description: The ID of a credit normal ledger account. When money enters the virtual account, this ledger account will be credited. Must be accompanied by a debit_ledger_account_id if present.
          nullable: true
        ledger_account_id:
          type: string
          format: uuid
          nullable: true
          description: If the virtual account links to a ledger account in Modern Treasury, the id of the ledger account will be populated here.
        metadata:
          type: object
          description: Additional data represented as key-value pairs. Both the key and value must be strings.
          additionalProperties:
            type: string
          example:
            key: value
            foo: bar
            modern: treasury
      additionalProperties: false
      minProperties: 16
      required:
      - id
      - object
      - live_mode
      - created_at
      - updated_at
      - discarded_at
      - name
      - description
      - counterparty_id
      - internal_account_id
      - account_details
      - routing_details
      - debit_ledger_account_id
      - credit_ledger_account_id
      - ledger_account_id
      - metadata
    ledger_account_create_request:
      type: object
      properties:
        name:
          type: string
          description: The name of the ledger account.
        description:
          type: string
          description: The description of the ledger account.
          nullable: true
        normal_balance:
          type: string
          enum:
          - credit
          - debit
          description: The normal balance of the ledger account.
          _x-stainless-modelDefPath: $shared.transaction_direction
        ledger_id:
          type: string
          format: uuid
          description: The id of the ledger that this account belongs to.
        currency:
          type: string
          description: The currency of the ledger account.
        currency_exponent:
          type: integer
          description: The currency exponent of the ledger account.
          nullable: true
        ledger_account_category_ids:
          type: array
          items:
            type: string
            format: uuid
          description: The array of ledger account category ids that this ledger account should be a child of.
        ledgerable_id:
          type: string
          format: uuid
          description: If the ledger account links to another object in Modern Treasury, the id will be populated here, otherwise null.
        ledgerable_type:
          type: string
          enum:
          - counterparty
          - external_account
          - internal_account
          - virtual_account
          description: If the ledger account links to another object in Modern Treasury, the type will be populated here, otherwise null. The value is one of internal_account or external_account.
        metadata:
          type: object
          description: Additional data represented as key-value pairs. Both the key and value must be strings.
          additionalProperties:
            type: string
          example:
            key: value
            foo: bar
            modern: treasury
        external_id:
          type: string
          nullable: true
          description: An optional user-defined 180 character unique identifier.
      required:
      - name
      - normal_balance
      - ledger_id
      - currency
    error_message:
      type: object
      properties:
        errors:
          type: object
          properties:
            code:
              type: string
              enum:
              - parameter_invalid
              - parameter_missing
              - resource_not_found
              - not_found
              - forbidden
              - invalid_ip
              - invalid_key
              - header_invalid
              - expired_key
              - conflict
              - too_many_requests
            message:
              type: string
            parameter:
              type: string
      required:
      - errors
    routing_detail_create_request:
      type: object
      properties:
        routing_number:
          type: string
          description: The routing number of the bank.
        routing_number_type:
          type: string
          enum:
          - aba
          - au_bsb
          - br_codigo
          - ca_cpa
          - chips
          - cnaps
          - dk_interbank_clearing_code
          - gb_sort_code
          - hk_interbank_clearing_code
          - hu_interbank_clearing_code
          - id_sknbi_code
          - il_bank_code
          - in_ifsc
          - jp_zengin_code
          - mx_bank_identifier
          - my_branch_code
          - nz_national_clearing_code
          - pl_national_clearing_code
          - se_bankgiro_clearing_code
          - sg_interbank_clearing_code
          - swift
          - za_national_clearing_code
          description: The type of routing number. See https://docs.moderntreasury.com/platform/reference/routing-detail-object for more details.
        payment_type:
          type: string
          enum:
          - ach
          - au_becs
          - bacs
          - book
          - card
          - chats
          - check
          - cross_border
          - dk_nets
          - eft
          - gb_fps
          - hu_ics
          - interac
          - masav
          - mx_ccen
          - neft
          - nics
          - nz_becs
          - pl_elixir
          - provxchange
          - ro_sent
          - rtp
          - se_bankgirot
          - sen
          - sepa
          - sg_giro
          - sic
          - signet
          - sknbi
          - stablecoin
          - wire
          - zengin
          nullable: true
          description: If the routing detail is to be used for a specific payment type this field will be populated, otherwise null.
      required:
      - routing_number
      - routing_number_type
    routing_detail:
      type: object
      properties:
        id:
          type: string
          format: uuid
        object:
          type: string
        live_mode:
          type: boolean
          description: This field will be true if this object exists in the live environment or false if it exists in the test environment.
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        discarded_at:
          type: string
          format: date-time
          nullable: true
        routing_number:
          type: string
          description: The routing number of the bank.
        routing_number_type:
          type: string
          enum:
          - aba
          - au_bsb
          - br_codigo
          - ca_cpa
          - chips
          - cnaps
          - dk_interbank_clearing_code
          - gb_sort_code
          - hk_interbank_clearing_code
          - hu_interbank_clearing_code
          - id_sknbi_code
          - il_bank_code
          - in_ifsc
          - jp_zengin_code
          - mx_bank_identifier
          - my_branch_code
          - nz_national_clearing_code
          - pl_national_clearing_code
          - se_bankgiro_clearing_code
          - sg_interbank_clearing_code
          - swift
          - za_national_clearing_code
          description: The type of routing number. See https://docs.moderntreasury.com/platform/reference/routing-detail-object for more details.
        payment_type:
          type: string
          enum:
          - ach
          - au_becs
          - bacs
          - book
          - card
          - chats
          - check
          - cross_border
          - dk_nets
          - eft
          - gb_fps
          - hu_ics
          - interac
          - masav
          - mx_ccen
          - neft
          - nics
          - nz_becs
          - pl_elixir
          - provxchange
          - ro_sent
          - rtp
          - se_bankgirot
          - sen
          - sepa
          - sg_giro
          - sic
          - signet
          - sknbi
          - stablecoin
          - wire
          - zengin
          nullable: true
          description: If the routing detail is to be used for a specific payment type this field will be populated, otherwise null.
        bank_name:
          type: string
          description: The name of the bank.
        bank_address:
          $ref: '#/components/schemas/address'
      additionalProperties: false
      minProperties: 11
      required:
      - id
      - object
      - live_mode
      - created_at
      - updated_at
      - discarded_at
      - routing_number
      - routing_number_type
      - payment_type
      - bank_name
      - bank_address
    virtual_account_update_request:
      type: object
      properties:
        name:
          type: string
          nullable: true
        counterparty_id:
          type: string
          format: uuid
        ledger_account_id:
          type: string
          format: uuid
          description: The ledger account that you'd like to link to the virtual account.
        metadata:
          type: object
          additionalProperties:
            type: string
  parameters:
    metadata_query:
      name: metadata
      in: query
      schema:
        type: object
        additionalProperties:
          type: string
      style: deepObject
      explode: true
      required: false
      description: For example, if you want to query for records with metadata key `Type` and value `Loan`, the query would be `metadata%5BType%5D=Loan`. This encodes the query parameters.
  securitySchemes:
    basic_auth:
      type: http
      scheme: basic