Returns

A return represents a rejection of a single payment order or paper item. This can occur for a variety of reasons and often results in your originating bank returning your funds as well as issuing a notification with additional details. These additional details result in a return being generated in the Modern Treasury system.

You can also create a return against a simulated incoming payment detail to mimic the return flow inside of sandbox.

Note that sometimes, banks will process a return prior to recording a transaction. This is why both transaction_id and transaction_line_item_id below may be null.

Related Guides:

AttributeDescription
id
string
Unique identifier for the return.
amount
int32
Value in specified currency's smallest unit. e.g. $10 would be represented as 1000.
currency
string
Currency that this transaction is denominated in.
type
string
The type of return. Can be one of: ach, ach_noc, au_becs, bacs, book, check, cross_border, eft, interac, manual, paper_item, sepa, wire.
status
string
The current status of the return. See the webhooks section for more on the different statuses.
code
string
The return code. For ach returns, see ACH Return Reason Codes.
reason
string
Often the bank will provide an explanation for the return, which is a short human readable string.
role
string
The role of the return, can be originating or receiving
transaction_line_item_id
string
The ID of the relevant Transaction Line Item or null.
transaction_id
string
The ID of the relevant Transaction or null.
returnable_id
string
The ID of the object being returned or null.
returnable_type
string
The type of object being returned or null.
current_return
object
If the return's status is returned, this will include the return object that is returning this return.
live_mode
boolean
This field will be true if this object exists in the live environment or false if it exists in the test environment.
additional_information
string
This field may contain sensitive information and is not included in API responses by default. Learn more about changing your settings here.

Some returns include additional information from the bank. If the banks include it, this string will be present.
reference_numbers
array
An array of Payment Reference objects.
internal_account_id
string
The ID of the relevant Internal Account.
date_of_death
date
If the return code is R14 or R15 this is the date the deceased counterparty passed away.
ledger_transaction_id
string
The ID of the ledger transaction linked to the return. See Linking to other Modern Treasury objects.
{
    "id": "de1d44ba-c904-4598-a62c-fe0b4fd75ac7",
    "object": "return",
    "live_mode": true,
    "status": "pending",
    "returnable_id": "744ac1c4-365a-4df9-b6d9-730e07df115a",
    "returnable_type": "payment_order",
    "transaction_line_item_id": "3768a9ad-98c0-4b77-a5f4-4e203af16e0f",
    "transaction_id": "2159755e-5600-47c2-935a-df9a83a31c07",
    "internal_account_id": "3cce4311-c57e-4e38-aff9-58dd9409a67f",
    "type": "ach",
    "amount": 20000,
    "currency": "USD",
    "code": "R01",
    "failure_reason": null,
    "reason": "Insufficient Funds",
    "role": "receiving",
    "date_of_death": null,
    "current_return": null,
    "reference_numbers": [],
    "ledger_transaction_id": null,
    "created_at": "2023-04-19T16:53:06Z",
    "updated_at": "2023-04-19T16:53:06Z"
}