Return Webhooks

Event

Description

created

A return has been created.

begin_processing

A return has begun processing. Originating returns only

finish_processing

A return has finished processing and been sent to the bank. Originating returns only

tentatively_reconciled

A return has been tentatively reconciled to a pending transaction. See the guide for more information.

Does not change the return's state.

reconciled

A return has been reconciled to a posted transaction. In most cases, you will get this at the same time as the completed webhook. However, there is a case where you only receive the reconciled webhook. This would occur if you received a return for an originating return before the transaction posted. In this case, we don't send the completed webhook since the originating return will be in the terminal returned state.

completed

A return has been reconciled to a posted transaction.

returned

An originated return has been returned.

failed

A return has failed due to an error.

unreconciled

A return has been unreconciled from a transaction.

linked_entity

A return has been linked to another entity (note the different data schema)

unlinked_entity

A return has been unlinked from another entity (note the different data schema )

These are the statuses a return may have:

Status

Description

pending

This is the initial state for a new return.

processing

This is a very short state where Modern Treasury is preparing the return to be sent to the bank. Originating returns only

sent

The return has been sent to the bank. It may remain in this state for up to a few days, depending on the type of return. Originating returns only

completed

The return has been reconciled to a posted bank transaction. At this point, we know the return was successful, and your account will have been debited or credited.

returned

The originated return was returned by the RDFI.
Originating returns only

failed

This status is rare but may happen if there is an error at the bank.

{
  "event": "created",
  "data": {
    "id": "59981d98-7573-4e82-981e-acb1aaf4801e",
    "object": "return",
    "status": "pending",
    "returnable_id": "0383a613-1439-4ff8-992c-5e8691dfcc19",
    "returnable_type": "payment_order",
    "transaction_line_item_id": null,
    "transaction_id": null,
    "type": "ach",
    "amount": 20000,
    "currency": "USD",
    "code": "R03",
    "reason": "No Account/Unable to Locate Account",
    "role": "originating",
    "created_at": "2019-12-12T23:15:49Z",
    "updated_at": "2019-12-12T23:15:49Z"
  }
}
{
  "event": "linked_entity",
  "data": {
    "id": "21bfd337-5d13-4c9a-8f9e-2409023d9627",
    "entiy_a_id": "1bbc5c0e-fdee-4a4b-b16f-d8164444861f",
    "entity_a_type": "return",
    "entiy_b_id": "22ccfb02-fdee-4a4b-b16f-d8164444861f",
    "entity_b_type": "payment_order",
    "created_by_actor_id": "b45c5b0e-fdee-4a4b-b16f-d8164444861f",
    "created_by_actor_type": "user",
    "created_by_actor_name": "Some Name",
    "live_mode": true,
    "created_at": "2019-11-09T00:11:07Z",
    "updated_at": "2019-11-09T00:11:07Z"
	}
}