Modern Treasury Return API
The Return API from Modern Treasury — 2 operation(s) for return.
OpenAPI Specification
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