Modern Treasury PaymentOrder API

openapi: 3.0.1
info:
  title: Modern Treasury AccountCapability PaymentOrder 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: PaymentOrder
paths:
  /api/invoices/{id}/payment_orders/{payment_order_id}:
    parameters:
    - name: id
      in: path
      description: id
      required: true
      schema:
        type: string
    - name: payment_order_id
      in: path
      description: payment_order_id
      required: true
      schema:
        type: string
    put:
      summary: add payment_order_id to invoice
      tags:
      - PaymentOrder
      operationId: addPaymentOrderToInvoice
      description: Add a payment order to an invoice.
      security:
      - basic_auth: []
      responses:
        '200':
          description: successful
        '404':
          description: not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_message'
        '422':
          description: not unsuccessful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_message'
  /api/payment_orders/create_async:
    post:
      summary: create async payment order
      tags:
      - PaymentOrder
      description: Create a new payment order asynchronously
      operationId: createAsyncPaymentOrder
      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:
        '202':
          description: successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/async_response'
        '403':
          description: forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_message'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/payment_order_async_create_request'
  /api/payment_orders:
    get:
      summary: list payment orders
      tags:
      - PaymentOrder
      description: Get a list of all payment orders
      operationId: listPaymentOrders
      security:
      - basic_auth: []
      parameters:
      - name: after_cursor
        in: query
        schema:
          type: string
          nullable: true
        required: false
      - name: per_page
        in: query
        schema:
          type: integer
        required: false
      - name: type
        in: query
        schema:
          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
        required: false
      - name: priority
        in: query
        schema:
          type: string
          enum:
          - high
          - normal
        required: false
        description: Either `normal` or `high`. For ACH and EFT payments, `high` represents a same-day ACH or EFT transfer, respectively. For check payments, `high` can mean an overnight check rather than standard mail.
      - name: counterparty_id
        in: query
        schema:
          type: string
        required: false
      - name: originating_account_id
        in: query
        schema:
          type: string
        required: false
      - name: transaction_id
        in: query
        schema:
          type: string
        description: The ID of a transaction that the payment order has been reconciled to.
        required: false
      - name: external_id
        in: query
        schema:
          type: string
        required: false
      - name: status
        in: query
        schema:
          type: string
          enum:
          - approved
          - cancelled
          - completed
          - denied
          - failed
          - held
          - needs_approval
          - pending
          - processing
          - returned
          - reversed
          - sent
          - stopped
        required: false
      - name: direction
        in: query
        schema:
          type: string
          enum:
          - credit
          - debit
          _x-stainless-modelDefPath: $shared.transaction_direction
        required: false
      - name: reference_number
        in: query
        schema:
          type: string
        description: Query for records with the provided reference number
        required: false
      - name: effective_date_start
        in: query
        schema:
          type: string
          format: date
        required: false
        description: An inclusive lower bound for searching effective_date
      - name: effective_date_end
        in: query
        schema:
          type: string
          format: date
        required: false
        description: An inclusive upper bound for searching effective_date
      - name: created_at_start
        in: query
        schema:
          type: string
          format: date
        required: false
        description: An inclusive lower bound for searching created_at
      - name: created_at_end
        in: query
        schema:
          type: string
          format: date
        required: false
        description: An inclusive upper bound for searching created_at
      - name: process_after_start
        in: query
        schema:
          type: string
          format: date-time
        required: false
        description: An inclusive lower bound for searching process_after
      - name: process_after_end
        in: query
        schema:
          type: string
          format: date-time
        required: false
        description: An inclusive upper bound for searching process_after
      - $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/payment_order'
    post:
      summary: create payment order
      tags:
      - PaymentOrder
      description: Create a new Payment Order
      operationId: createPaymentOrder
      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/payment_order'
        '400':
          description: parameter_invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_message'
        '401':
          description: unsuccessful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_message'
        '403':
          description: forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_message'
        '409':
          description: conflict
          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/payment_order_create_request'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/payment_order_create_request'
  /api/payment_orders/{id}:
    parameters:
    - name: id
      in: path
      schema:
        type: string
      required: true
    get:
      summary: get payment order
      tags:
      - PaymentOrder
      description: Get details on a single payment order
      operationId: getPaymentOrder
      security:
      - basic_auth: []
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/payment_order'
        '404':
          description: not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_message'
    patch:
      summary: update payment order
      tags:
      - PaymentOrder
      description: Update a payment order
      operationId: updatePaymentOrder
      security:
      - basic_auth: []
      parameters: []
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/payment_order'
        '404':
          description: not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_message'
        '409':
          description: conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_message'
        '422':
          description: parameter_invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_message'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/payment_order_update_request'
components:
  schemas:
    payment_order_subtype:
      type: string
      enum:
      - 0C
      - 0N
      - 0S
      - CCD
      - CIE
      - CTX
      - IAT
      - PPD
      - TEL
      - WEB
      - au_becs
      - bacs
      - base
      - chats
      - dk_nets
      - eft
      - ethereum
      - hu_ics
      - masav
      - mx_ccen
      - neft
      - nics
      - nz_becs
      - pl_elixir
      - polygon
      - ro_sent
      - se_bankgirot
      - sepa
      - sg_giro
      - sic
      - sknbi
      - solana
      - zengin
      nullable: true
      description: An additional layer of classification for the type of payment order you are doing. This field is only used for `ach` payment orders currently. For `ach`  payment orders, the `subtype`  represents the SEC code. We currently support `CCD`, `PPD`, `IAT`, `CTX`, `WEB`, `CIE`, and `TEL`.
      x-stainless-renameMap:
        bacs_new_instruction: 0C
        bacs_cancellation_instruction: 0N
        bacs_conversion_instruction: 0S
    external_account_type:
      type: string
      enum:
      - base_wallet
      - cash
      - checking
      - crypto_wallet
      - ethereum_wallet
      - general_ledger
      - loan
      - non_resident
      - other
      - overdraft
      - polygon_wallet
      - savings
      - solana_wallet
      description: Can be `checking`, `savings` or `other`.
    account_capability:
      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
        direction:
          type: string
          enum:
          - credit
          - debit
          description: One of `debit` or `credit`. Indicates the direction of money movement this capability is responsible for.
          _x-stainless-modelDefPath: $shared.transaction_direction
        identifier:
          type: string
          nullable: true
          description: A unique reference assigned by your bank for tracking and recognizing payment files. It is important this is formatted exactly how the bank assigned it.
        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
          description: Indicates the the type of payment this capability is responsible for originating.
      additionalProperties: true
      minProperties: 9
      maxProperties: 9
      required:
      - id
      - object
      - live_mode
      - created_at
      - updated_at
      - discarded_at
      - direction
      - identifier
      - payment_type
    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
    currency:
      type: string
      enum:
      - AED
      - AFN
      - ALL
      - AMD
      - ANG
      - AOA
      - ARS
      - AUD
      - AWG
      - AZN
      - BAM
      - BBD
      - BCH
      - BDT
      - BGN
      - BHD
      - BIF
      - BMD
      - BND
      - BOB
      - BRL
      - BSD
      - BTC
      - BTN
      - BWP
      - BYN
      - BYR
      - BZD
      - CAD
      - CDF
      - CHF
      - CLF
      - CLP
      - CNH
      - CNY
      - COP
      - CRC
      - CUC
      - CUP
      - CVE
      - CZK
      - DJF
      - DKK
      - DOP
      - DZD
      - EEK
      - EGP
      - ERN
      - ETB
      - ETH
      - EUR
      - EURC
      - FJD
      - FKP
      - GBP
      - GBX
      - GEL
      - GGP
      - GHS
      - GIP
      - GMD
      - GNF
      - GTQ
      - GYD
      - HKD
      - HNL
      - HRK
      - HTG
      - HUF
      - IDR
      - ILS
      - IMP
      - INR
      - IQD
      - IRR
      - ISK
      - JEP
      - JMD
      - JOD
      - JPY
      - KES
      - KGS
      - KHR
      - KMF
      - KPW
      - KRW
      - KWD
      - KYD
      - KZT
      - LAK
      - LBP
      - LKR
      - LRD
      - LSL
      - LTL
      - LVL
      - LYD
      - MAD
      - MDL
      - MGA
      - MKD
      - MMK
      - MNT
      - MOP
      - MRO
      - MRU
      - MTL
      - MUR
      - MVR
      - MWK
      - MXN
      - MYR
      - MZN
      - NAD
      - NGN
      - NIO
      - NOK
      - NPR
      - NZD
      - OMR
      - OP
      - PAB
      - PEN
      - PGK
      - PHP
      - PKR
      - PLN
      - PYG
      - PYUSD
      - QAR
      - RON
      - RSD
      - RUB
      - RWF
      - SAR
      - SBD
      - SCR
      - SDG
      - SEK
      - SGD
      - SHP
      - SKK
      - SLE
      - SLL
      - SOS
      - SRD
      - SSP
      - STD
      - STN
      - SVC
      - SYP
      - SZL
      - THB
      - TJS
      - TMM
      - TMT
      - TND
      - TOP
      - TRY
      - TTD
      - TWD
      - TZS
      - UAH
      - UGX
      - USD
      - USDB
      - USDC
      - USDG
      - USDP
      - USDT
      - UYU
      - UZS
      - VEF
      - VES
      - VND
      - VUV
      - WST
      - XAF
      - XAG
      - XAU
      - XBA
      - XBB
      - XBC
      - XBD
      - XCD
      - XCG
      - XDR
      - XFU
      - XOF
      - XPD
      - XPF
      - XPT
      - XTS
      - YER
      - ZAR
      - ZMK
      - ZMW
      - ZWD
      - ZWG
      - ZWL
      - ZWN
      - ZWR
      description: Three-letter ISO currency code.
    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:
      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
    address_request:
      type: object
      properties:
        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
    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
    internal_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
        account_type:
          type: string
          enum:
          - base_wallet
          - cash
          - checking
          - crypto_wallet
          - ethereum_wallet
          - general_ledger
          - loan
          - non_resident
          - other
          - overdraft
          - polygon_wallet
          - savings
          - solana_wallet
          nullable: true
          description: Can be checking, savings or other.
        party_name:
          type: string
          description: The legal name of the entity which owns the account.
        party_type:
          type: string
          enum:
          - business
          - individual
          nullable: true
          description: Either individual or business.
        party_address:
          $ref: '#/components/schemas/address'
          description: The address associated with the owner or null.
        name:
          type: string
          nullable: true
          description: A nickname for the account.
        account_details:
          type: array
          items:
            $ref: '#/components/schemas/account_detail'
          description: An array of account detail objects.
        account_capabilities:
          type: array
          description: An array of AccountCapability objects that list the originating abilities of the internal account and any relevant information for them.
          items:
            $ref: '#/components/schemas/account_capability'
        routing_details:
          type: array
          items:
            $ref: '#/components/schemas/routing_detail'
          description: An array of routing detail objects.
        connection:
          $ref: '#/components/schemas/connection'
          description: Specifies which financial institution the accounts belong to.
        currency:
          $ref: '#/components/schemas/currency'
          description: The currency of the account.
        metadata:
          type: object
          additionalProperties:
            type: string
          example:
            key: value
            foo: bar
            modern: treasury
          description: Additional data represented as key-value pairs. Both the key and value must be strings.
        parent_account_id:
          type: string
          format: uuid
          nullable: true
          description: The parent InternalAccount of this account.
        counterparty_id:
          type: string
          format: uuid
          nullable: true
          description: The Counterparty associated to this account.
        vendor_id:
          type: string
          format: string
          nullable: true
          description: The vendor ID associated with this account.
        legal_entity_id:
          type: string
          format: uuid
          nullable: true
          description: The Legal Entity associated to this account.
        status:
          type: string
          format: string
          nullable: true
          enum:
          - active
          - closed
          - pending_activation
          - pending_closure
          - suspended
          description: The internal account status.
        ledger_account_id:
          type: string
          format: uuid
          nullable: true
          description: If the internal account links to a ledger account in Modern Treasury, the id of the ledger account will be populated here.
        contra_ledger_account_id:
          type: string
          format: uuid
          nullable: true
          description: If the internal account links to a contra ledger account in Modern Treasury, the id of the contra ledger account will be populated here.
        external_id:
          type: string
          nullable: true
          description: An optional user-defined 180 character unique identifier.
      additionalProperties: false
      minProperties: 24
      required:
      - id
      - object
      - live_mode
      - created_at
      - updated_at
      - account_type
      - party_name
      - party_type
      - party_address
      - name
      - account_details
      - account_capabilities
      - routing_details
      - connection
      - currency
      - metadata
      - parent_account_id
      - counterparty_id
      - vendor_id
      - legal_entity_id
      - status
      - ledger_account_id
      - contra_ledger_account_id
      - external_id
    payment_order_create_request:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/payment_order_type'
        subtype:
          $ref: '#/components/schemas/payment_order_subtype'
        amount:
          type: integer
          description: Value in specified currency's smallest unit. e.g. $10 would be represented as 1000 (cents). For RTP, the maximum amount allowed by the network is $100,000.
        direction:
          type: string
          enum:
          - credit
          - debit
          description: One of `credit`, `debit`. Describes the direction money is flowing in the transaction. A `credit` moves money from your account to someone else's. A `debit` pulls money from someone else's account to your own. Note that wire, rtp, and check payments will always be `credit`.
        priority:
          type: string
          enum:
          - high
          - normal
          description: Either `normal` or `high`. For ACH and EFT payments, `high` represents a same-day ACH or EFT transfer, respectively. For check payments, `high` can mean an overnight check rather than standard mail.
        originating_account_id:
          type: string
          format: uuid
          description: The ID of one of your organization's internal accounts.
        receiving_account_id:
          type: string
          format: uuid
          description: Either `receiving_account` or `receiving_account_id` must be present. When using `receiving_account_id`, you may pass the id of an external account or an internal account.
        currency:
          $ref: '#/components/schemas/curre

# --- truncated at 32 KB (117 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/modern-treasury/refs/heads/main/openapi/modern-treasury-paymentorder-api-openapi.yml