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:

Attribute	Description
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`, `eft`, `interac`, `manual`, `paper_item`, `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 personally identifiable information (PII) 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"
}