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, paper_item, eft, 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.

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

Some returns may include additional information from the bank. In these cases, this string will be present.

reference_numbers
array

An array of Payment Reference objects.

{
  "id": "08c251e1-4cba-4706-8faa-9c2df2682aa3",
  "object": "return",
  "returnable_id": "641f5b0d-c92b-4952-82b2-097c00217d05",
  "returnable_type": "payment_order",
  "transaction_line_item_id": "c3e5412c-6e70-4df6-8c90-a7c9dad7dc72",
  "transaction_id": "4f898a70-6aeb-41f8-9b98-82e42f54cad8",
  "type": "ach",
  "status": "pending",
  "amount": 20000,
  "currency": "USD",
  "code": "R01",
  "reason": "Insufficient Funds",
  "role": "receiving",
  "additional_information": null,
  "live_mode": true,
  "created_at": "2019-11-09T00:11:07Z",
  "updated_at": "2019-11-09T00:11:07Z"
}