openapi: 3.0.1 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 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 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 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/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: ledger_transaction_create_request: type: object properties: description: type: string description: An optional description for internal use. nullable: true 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 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 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 format: date-time nullable: true returnable_id: type: string format: uuid description: The ID of the object being returned or `null`. nullable: true returnable_type: type: string enum: - incoming_payment_detail - payment_order - return - reversal description: The type of object being returned or `null`. nullable: true code: type: string 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 nullable: true description: The return code. For ACH returns, this is the required ACH return code. reason: type: string nullable: true description: Often the bank will provide an explanation for the return, which is a short human readable string. date_of_death: type: string nullable: true format: date description: If the return code is `R14` or `R15` this is the date the deceased counterparty passed away. additional_information: type: string nullable: true description: Some returns may include additional information from the bank. In these cases, this string will be present. data: type: object nullable: true description: The raw data from the return file that we get from the bank. corrections: type: object nullable: true properties: account_number: type: string nullable: true description: The updated account number that should replace the one originally used on the outgoing payment. company_id: type: string nullable: true description: The updated company ID that should replace the one originally used on the outgoing payment. company_name: type: string nullable: true description: The updated company name that should replace the one originally used on the outgoing payment. individual_identification_number: type: string nullable: true description: The updated individual identification number that should replace the one originally used on the outgoing payment. routing_number: type: string nullable: true description: The updated routing number that should replace the one originally used on the outgoing payment. transaction_code: type: string nullable: true 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 format: uuid nullable: true description: The ID of the relevant Transaction Line Item or `null`. transaction_id: type: string format: uuid nullable: true description: The ID of the relevant Transaction or `null`. internal_account_id: type: string format: uuid nullable: true 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 nullable: true 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' nullable: true 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 format: uuid nullable: true 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 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_create_request: type: object properties: returnable_id: type: string format: uuid description: The ID of the object being returned or `null`. nullable: true code: type: string 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 nullable: true description: The return code. For ACH returns, this is the required ACH return code. reason: type: string nullable: true 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 nullable: true format: date description: If the return code is `R14` or `R15` this is the date the deceased counterparty passed away. additional_information: type: string nullable: true description: Some returns may include additional information from the bank. In these cases, this string will be present. data: type: object nullable: true description: The raw data from the return file that we get from the bank. corrections: type: object nullable: true properties: account_number: type: string nullable: true description: The updated account number that should replace the one originally used on the outgoing payment. company_id: type: string nullable: true description: The updated company ID that should replace the one originally used on the outgoing payment. company_name: type: string nullable: true description: The updated company name that should replace the one originally used on the outgoing payment. individual_identification_number: type: string nullable: true description: The updated individual identification number that should replace the one originally used on the outgoing payment. routing_number: type: string nullable: true description: The updated routing number that should replace the one originally used on the outgoing payment. transaction_code: type: string nullable: true 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 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. 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 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. nullable: true pending_balance_amount: type: object 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. nullable: true posted_balance_amount: type: object 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. nullable: true available_balance_amount: type: object 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. nullable: true show_resulting_ledger_account_balances: type: boolean description: If true, response will include the balance of the associated ledger account for the entry. nullable: true 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 securitySchemes: basic_auth: type: http scheme: basic