Returns Overview

Returns are a normal course of business that will occur some small percentage of the time. A return can occur for various reasons and often results in your originating bank returning your funds and issuing a notification with additional details. These additional details generate a Return in the Modern Treasury system.

The Modern Treasury Returns object represents a rejection of a returnable. This returnable can be a Payment Order, Reversal, Incoming Payment Detail or a Paper Item. Returns can also be originated or received, indicated by the return.role field as originating orreceiving.

Return Webhooks

Return Webhooks corresponding to the return statuses can be received in varying orders depending on when you receive a return from the bank. Here are some important details on the returns lifecycle:

• A Payment Order will always transition to completed state before transitioning to returned.
• return.created, payment_order.completed, payment_order.returned, and return.completed webhooks may be received in various orders. See return webhooks and payment order webhooks for more information.
• A Return may be created before or after the Payment Order has already been completed, depending on how early a return file is received and the return code type. The Payment Order’s transition to returned is not affected by the Return’s status. A PO can be moved to returned even if the Return is pending, as long as the Payment Order itself has been completed. If the Return is created after the Payment Order is already completed, then the Payment Order will be immediately moved to returned.
• return.completed may be emitted either before or after payment_order.returned