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, 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"
}