Modern Treasury Return API

openapi: 3.2.0
info:
  title: Modern Treasury AccountCapability Return 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: Return
paths:
  /api/returns:
    get:
      summary: list returns
      tags:
      - Return
      operationId: listReturns
      description: Get a list of returns.
      security:
      - basic_auth: []
      parameters:
      - name: after_cursor
        in: query
        schema:
          type:
          - string
          - 'null'
        required: false
      - name: per_page
        in: query
        required: false
        schema:
          type: integer
      - name: internal_account_id
        in: query
        schema:
          type: string
        required: false
        description: Specify `internal_account_id` if you wish to see returns to/from a specific account.
      - name: counterparty_id
        in: query
        schema:
          type: string
        required: false
        description: Specify `counterparty_id` if you wish to see returns that occurred with a specific counterparty.
      - name: returnable_id
        in: query
        schema:
          type: string
        required: false
        description: The ID of a valid returnable. Must be accompanied by `returnable_type`.
      - name: returnable_type
        in: query
        schema:
          type: string
          enum:
          - incoming_payment_detail
          - payment_order
          - return
          - reversal
        required: false
        description: One of `payment_order`, `reversal`, or `incoming_payment_detail`. Must be accompanied by `returnable_id`.
      responses:
        '200':
          description: successful
          headers:
            X-After-Cursor:
              schema:
                type:
                - string
                - 'null'
              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
                - 'null'
              description: The current `per_page`.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/return'
        '401':
          description: unsuccessful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_message'
    post:
      summary: create return
      tags:
      - Return
      operationId: createReturn
      description: Create a return.
      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/return'
        '404':
          description: unsuccessful
          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/return_create_request'
  /api/returns/{id}:
    parameters:
    - name: id
      in: path
      schema:
        type: string
      description: The ID of an existing return.
      required: true
    get:
      summary: show return
      tags:
      - Return
      operationId: getReturn
      description: Get a single return.
      security:
      - basic_auth: []
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/return'
        '404':
          description: not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_message'
components:
  schemas:
    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.
    payment_reference:
      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
        reference_number:
          type: string
          description: The vendor reference number.
        reference_number_type:
          type: string
          enum:
          - ach_original_trace_number
          - ach_trace_number
          - bankprov_payment_activity_date
          - bankprov_payment_id
          - blockchain_transaction_hash
          - blockchain_transaction_index
          - bnk_dev_prenotification_id
          - bnk_dev_transfer_id
          - bny_mellon_transaction_reference_number
          - bofa_end_to_end_id
          - bofa_neft_clearing_reference_number
          - bofa_transaction_id
          - check_number
          - chips_uid
          - citibank_reference_number
          - citibank_worldlink_clearing_system_reference_number
          - column_fx_quote_id
          - column_reversal_pair_transfer_id
          - column_transfer_id
          - cross_river_card_trace_number
          - cross_river_core_transaction_id
          - cross_river_fed_batch_id
          - cross_river_payment_id
          - cross_river_retrieval_reference_id
          - cross_river_service_message
          - cross_river_transaction_id
          - currencycloud_conversion_id
          - currencycloud_payment_id
          - dc_bank_transaction_id
          - eft_trace_number
          - evolve_core_batch
          - evolve_core_file_key
          - evolve_core_seq
          - evolve_transaction_id
          - fake_vendor_payment_id
          - fedwire_imad
          - fedwire_omad
          - first_republic_internal_id
          - goldman_sachs_collection_request_id
          - goldman_sachs_end_to_end_id
          - goldman_sachs_payment_request_id
          - goldman_sachs_request_id
          - goldman_sachs_unique_payment_id
          - interac_message_id
          - jpmc_ccn
          - jpmc_clearing_system_reference
          - jpmc_customer_reference_id
          - jpmc_end_to_end_id
          - jpmc_firm_root_id
          - jpmc_fx_trn_id
          - jpmc_p3_id
          - jpmc_payment_batch_id
          - jpmc_payment_information_id
          - jpmc_payment_returned_datetime
          - jpmc_transaction_reference_number
          - lob_check_id
          - other
          - partial_swift_mir
          - paxos_crypto_withdrawal_id
          - paxos_fiat_withdrawal_id
          - paxos_group_id
          - paxos_orchestration_id
          - paxos_transfer_id
          - pnc_clearing_reference
          - pnc_instruction_id
          - pnc_multipayment_id
          - pnc_payment_trace_id
          - pnc_request_for_payment_id
          - pnc_transaction_reference_number
          - rbc_wire_reference_id
          - rtp_instruction_id
          - signet_api_reference_id
          - signet_confirmation_id
          - signet_request_id
          - silvergate_payment_id
          - svb_end_to_end_id
          - svb_payment_id
          - swift_mir
          - swift_uetr
          - umb_product_partner_account_number
          - usbank_payment_application_reference_id
          - usbank_payment_id
          - usbank_pending_rtp_payment_id
          - usbank_posted_rtp_payment_id
          - wells_fargo_end_to_end_id
          - wells_fargo_payment_id
          - wells_fargo_trace_number
          - wells_fargo_uetr
          - western_alliance_payment_id
          - western_alliance_transaction_id
          - western_alliance_wire_confirmation_number
          description: The type of the reference number. Referring to the vendor payment id.
      additionalProperties: false
      minProperties: 7
      required:
      - id
      - object
      - live_mode
      - created_at
      - updated_at
      - reference_number
      - reference_number_type
    ledger_transaction_create_request:
      type: object
      properties:
        description:
          type:
          - string
          - 'null'
          description: An optional description for internal use.
        status:
          type: string
          enum:
          - archived
          - pending
          - posted
          description: To post a ledger transaction at creation, use `posted`.
        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
        effective_at:
          type: string
          format: date-time
          description: The timestamp (ISO8601 format) at which the ledger transaction happened for reporting purposes.
        effective_date:
          type: string
          format: date
          description: The date (YYYY-MM-DD) on which the ledger transaction happened for reporting purposes.
        ledger_entries:
          type: array
          items:
            $ref: '#/components/schemas/ledger_entry_create_request'
          description: An array of ledger entry objects.
        external_id:
          type: string
          description: A unique string to represent the ledger transaction. Only one pending or posted ledger transaction may have this ID in the ledger.
        ledgerable_type:
          type: string
          enum:
          - expected_payment
          - incoming_payment_detail
          - payment_order
          - return
          - reversal
          description: If the ledger transaction can be reconciled to another object in Modern Treasury, the type will be populated here, otherwise null. This can be one of payment_order, incoming_payment_detail, expected_payment, return, or reversal.
        ledgerable_id:
          type: string
          format: uuid
          description: If the ledger transaction can be reconciled to another object in Modern Treasury, the id will be populated here, otherwise null.
      required:
      - ledger_entries
    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
    return:
      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
          - 'null'
          format: date-time
        returnable_id:
          type:
          - string
          - 'null'
          format: uuid
          description: The ID of the object being returned or `null`.
        returnable_type:
          type:
          - string
          - 'null'
          enum:
          - incoming_payment_detail
          - payment_order
          - return
          - reversal
          description: The type of object being returned or `null`.
        code:
          type:
          - string
          - 'null'
          enum:
          - '901'
          - '902'
          - '903'
          - '904'
          - '905'
          - '907'
          - '908'
          - '909'
          - '910'
          - '911'
          - '912'
          - '914'
          - C01
          - C02
          - C03
          - C05
          - C06
          - C07
          - C08
          - C09
          - C13
          - C14
          - R01
          - R02
          - R03
          - R04
          - R05
          - R06
          - R07
          - R08
          - R09
          - R10
          - R11
          - R12
          - R13
          - R14
          - R15
          - R16
          - R17
          - R18
          - R19
          - R20
          - R21
          - R22
          - R23
          - R24
          - R25
          - R26
          - R27
          - R28
          - R29
          - R30
          - R31
          - R32
          - R33
          - R34
          - R35
          - R36
          - R37
          - R38
          - R39
          - R40
          - R41
          - R42
          - R43
          - R44
          - R45
          - R46
          - R47
          - R50
          - R51
          - R52
          - R53
          - R61
          - R62
          - R67
          - R68
          - R69
          - R70
          - R71
          - R72
          - R73
          - R74
          - R75
          - R76
          - R77
          - R80
          - R81
          - R82
          - R83
          - R84
          - R85
          - currencycloud
          description: The return code. For ACH returns, this is the required ACH return code.
        reason:
          type:
          - string
          - 'null'
          description: Often the bank will provide an explanation for the return, which is a short human readable string.
        date_of_death:
          type:
          - string
          - 'null'
          format: date
          description: If the return code is `R14` or `R15` this is the date the deceased counterparty passed away.
        additional_information:
          type:
          - string
          - 'null'
          description: Some returns may include additional information from the bank. In these cases, this string will be present.
        data:
          type:
          - object
          - 'null'
          description: The raw data from the return file that we get from the bank.
        corrections:
          type:
          - object
          - 'null'
          properties:
            account_number:
              type:
              - string
              - 'null'
              description: The updated account number that should replace the one originally used on the outgoing payment.
            company_id:
              type:
              - string
              - 'null'
              description: The updated company ID that should replace the one originally used on the outgoing payment.
            company_name:
              type:
              - string
              - 'null'
              description: The updated company name that should replace the one originally used on the outgoing payment.
            individual_identification_number:
              type:
              - string
              - 'null'
              description: The updated individual identification number that should replace the one originally used on the outgoing payment.
            routing_number:
              type:
              - string
              - 'null'
              description: The updated routing number that should replace the one originally used on the outgoing payment.
            transaction_code:
              type:
              - string
              - 'null'
              description: The updated account type code that should replace the one originally used on the outgoing payment.
          description: Only relevant for ACH NOC returns. This is an object containing all of the new and corrected information provided by the bank that was previously incorrect on the original outgoing payment.
        reconciliation_status:
          type: string
          enum:
          - unreconciled
          - tentatively_reconciled
          - reconciled
          description: One of `unreconciled`, `tentatively_reconciled` or `reconciled`.
        status:
          type: string
          enum:
          - cancelled
          - completed
          - failed
          - pending
          - processing
          - returned
          - sent
          description: The current status of the return.
        transaction_line_item_id:
          type:
          - string
          - 'null'
          format: uuid
          description: The ID of the relevant Transaction Line Item or `null`.
        transaction_id:
          type:
          - string
          - 'null'
          format: uuid
          description: The ID of the relevant Transaction or `null`.
        internal_account_id:
          type:
          - string
          - 'null'
          format: uuid
          description: The ID of the relevant Internal Account.
        type:
          type: string
          enum:
          - ach
          - ach_noc
          - au_becs
          - bacs
          - book
          - check
          - cross_border
          - eft
          - gb_fps
          - interac
          - manual
          - sepa
          - wire
          - zengin
          description: 'The type of return. Can be one of: `ach`, `ach_noc`, `au_becs`, `bacs`, `eft`, `interac`, `manual`, `paper_item`, `wire`.'
        amount:
          type: integer
          description: Value in specified currency's smallest unit. e.g. $10 would be represented as 1000.
        currency:
          $ref: '#/components/schemas/currency'
          description: Currency that this transaction is denominated in.
        failure_reason:
          type:
          - string
          - 'null'
          description: If an originating return failed to be processed by the bank, a description of the failure reason will be available.
        role:
          type: string
          enum:
          - originating
          - receiving
          description: The role of the return, can be `originating` or `receiving`.
        current_return:
          $ref: '#/components/schemas/return'
          description: If the return's status is `returned`, this will include the return object's data that is returning this return.
          example: null
        reference_numbers:
          type: array
          description: An array of Payment Reference objects.
          items:
            $ref: '#/components/schemas/payment_reference'
        ledger_transaction_id:
          type:
          - string
          - 'null'
          format: uuid
          description: The ID of the ledger transaction linked to the return.
      additionalProperties: false
      minProperties: 25
      required:
      - id
      - object
      - live_mode
      - created_at
      - updated_at
      - discarded_at
      - returnable_id
      - returnable_type
      - code
      - reason
      - date_of_death
      - corrections
      - reconciliation_status
      - status
      - transaction_line_item_id
      - transaction_id
      - internal_account_id
      - type
      - amount
      - currency
      - failure_reason
      - role
      - current_return
      - reference_numbers
      - ledger_transaction_id
    ledger_entry_create_request:
      type: object
      properties:
        amount:
          type: integer
          description: Value in specified currency's smallest unit. e.g. $10 would be represented as 1000. Can be any integer up to 36 digits.
        effective_at:
          type: string
          format: date-time
          description: The timestamp (ISO8601 format) at which the ledger transaction happened for reporting purposes.
        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`.
          _x-stainless-modelDefPath: $shared.transaction_direction
        ledger_account_id:
          type: string
          format: uuid
          description: The ledger account that this ledger entry is associated with.
        lock_version:
          type:
          - integer
          - 'null'
          description: Lock version of the ledger account. This can be passed when creating a ledger transaction to only succeed if no ledger transactions have posted since the given version. See our post about Designing the Ledgers API with Optimistic Locking for more details.
        pending_balance_amount:
          type:
          - object
          - 'null'
          additionalProperties:
            type: integer
          description: Use `gt` (>), `gte` (>=), `lt` (<), `lte` (<=), or `eq` (=) to lock on the account’s pending balance. If any of these conditions would be false after the transaction is created, the entire call will fail with error code 422.
        posted_balance_amount:
          type:
          - object
          - 'null'
          additionalProperties:
            type: integer
          description: Use `gt` (>), `gte` (>=), `lt` (<), `lte` (<=), or `eq` (=) to lock on the account’s posted balance. If any of these conditions would be false after the transaction is created, the entire call will fail with error code 422.
        available_balance_amount:
          type:
          - object
          - 'null'
          additionalProperties:
            type: integer
          description: Use `gt` (>), `gte` (>=), `lt` (<), `lte` (<=), or `eq` (=) to lock on the account’s available balance. If any of these conditions would be false after the transaction is created, the entire call will fail with error code 422.
        show_resulting_ledger_account_balances:
          type:
          - boolean
          - 'null'
          description: If true, response will include the balance of the associated ledger account for the entry.
        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
      required:
      - amount
      - direction
      - ledger_account_id
    return_create_request:
      type: object
      properties:
        returnable_id:
          type:
          - string
          - 'null'
          format: uuid
          description: The ID of the object being returned or `null`.
        code:
          type:
          - string
          - 'null'
          enum:
          - '901'
          - '902'
          - '903'
          - '904'
          - '905'
          - '907'
          - '908'
          - '909'
          - '910'
          - '911'
          - '912'
          - '914'
          - C01
          - C02
          - C03
          - C05
          - C06
          - C07
          - C08
          - C09
          - C13
          - C14
          - R01
          - R02
          - R03
          - R04
          - R05
          - R06
          - R07
          - R08
          - R09
          - R10
          - R11
          - R12
          - R13
          - R14
          - R15
          - R16
          - R17
          - R18
          - R19
          - R20
          - R21
          - R22
          - R23
          - R24
          - R25
          - R26
          - R27
          - R28
          - R29
          - R30
          - R31
          - R32
          - R33
          - R34
          - R35
          - R36
          - R37
          - R38
          - R39
          - R40
          - R41
          - R42
          - R43
          - R44
          - R45
          - R46
          - R47
          - R50
          - R51
          - R52
          - R53
          - R61
          - R62
          - R67
          - R68
          - R69
          - R70
          - R71
          - R72
          - R73
          - R74
          - R75
          - R76
          - R77
          - R80
          - R81
          - R82
          - R83
          - R84
          - R85
          - currencycloud
          description: The return code. For ACH returns, this is the required ACH return code.
        reason:
          type:
          - string
          - 'null'
          description: An optional description of the reason for the return. This is for internal usage and will not be transmitted to the bank.”
        date_of_death:
          type:
          - string
          - 'null'
          format: date
          description: If the return code is `R14` or `R15` this is the date the deceased counterparty passed away.
        additional_information:
          type:
          - string
          - 'null'
          description: Some returns may include additional information from the bank. In these cases, this string will be present.
        data:
          type:
          - object
          - 'null'
          description: The raw data from the return file that we get from the bank.
        corrections:
          type:
          - object
          - 'null'
          properties:
            account_number:
              type:
              - string
              - 'null'
              description: The updated account number that should replace the one originally used on the outgoing payment.
            company_id:
              type:
              - string
              - 'null'
              description: The updated company ID that should replace the one originally used on the outgoing payment.
            company_name:
              type:
              - string
              - 'null'
              description: The updated company name that should replace the one originally used on the outgoing payment.
            individual_identification_number:
              type:
              - string
              - 'null'
              description: The updated individual identification number that should replace the one originally used on the outgoing payment.
            routing_number:
              type:
              - string
              - 'null'
              description: The updated routing number that should replace the one originally used on the outgoing payment.
            transaction_code:
              type:
              - string
              - 'null'
              description: The updated account type code that should replace the one originally used on the outgoing payment.
          description: Only relevant for ACH NOC returns. This is an object containing all of the new and corrected information provided by the bank that was previously incorrect on the original outgoing payment.
        reconciliation_status:
          type: string
          enum:
          - unreconciled
          - tentatively_reconciled
          - reconciled
          description: One of `unreconciled`, `tentatively_reconciled` or `reconciled`.
        returnable_type:
          type: string
          enum:
          - incoming_payment_detail
          description: The type of object being returned. Currently, this may only be incoming_payment_detail.
        ledger_transaction:
          $ref: '#/components/schemas/ledger_transaction_create_request'
          description: Specifies a ledger transaction object that will be created with the return. If the ledger transaction cannot be created, then the return creation will fail. The resulting ledger transaction will mirror the status of the return.
      required:
      - returnable_id
      - returnable_type
  securitySchemes:
    basic_auth:
      type: http
      scheme: basic