Simulate a Return

Overview

When creating a Payment Order in Modern Treasury's Sandbox, it is possible to set up the payment so that it will trigger a Return. Currently, you can trigger Returns for ACH and Wire Payment Orders by sending them to a specific Sandbox Counterparty. You can also simulate Notification of Change (NOC) returns for ACH payments.

Simulating Returns for ACH and Wire

To simulate an ACH return, you must create a Payment Order that is sent to a Counterparty who has an account number as 100XX where XX is the ACH return code you wish to trigger. For example, if the receiving account number is 10001, you will receive an R01 return (Insufficient funds).

To simulate a Wire return, you can create a Payment Order to the same type of Counterparty as you would to simulate an ACH return. Therefore 100XX pattern applies for Wire returns. However it is important to note that there is no concept of a Wire return code so simulated Wire returns will not have a return code specified.

Payment Orders are relayed through the Modern Treasury PSP regularly in Sandbox, and simulated Returns will be posted within minutes after the original Payment Orders have been sent. The Payment Order lifecycle is simulated in the Sandbox but mirrors how the lifecycle for Payment Orders and Returns work in the real world.

# Creates a Counterparty to simulate ACH/Wire returns with the return code `R01`

curl --request POST \
  -u ORGANIZATION_ID:API_KEY \
  --url https://app.moderntreasury.com/api/counterparties \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "Kenner, Bach and Ledeen",
  "accounts": [
    {
      "account_type": "checking",
      "routing_details": [
        {
          "routing_number_type": "aba",
          "routing_number": "121141822"
        }
      ],
      "account_details": [
        {
          "account_number": "10001"
        }
      ]
    }
  ]}'

# Returns with an External Account with ID: 5acec2ef-987b-4260-aa97-b719eeb0a8d5
  
curl --request POST \
  -u ORGANIZATION_ID:API_KEY \
  --url https://app.moderntreasury.com/api/payment_orders \
  -H 'Content-Type: application/json' \
  -d '{
  "type": "ach",
  "amount": 1000,
  "direction": "credit",
  "currency": "USD",
  "originating_account_id": "0f8e3719-3dfd-4613-9bbf-c0333781b59f",
  "receiving_account_id": "5acec2ef-987b-4260-aa97-b719eeb0a8d5"
}'

Simulating ACH Notification of Change (NOC) Returns

To simulate an ACH NOC return, create a Payment Order sent to a Counterparty with an account number in the format 200XX, where XX corresponds to the NOC code you wish to trigger. For example, if the receiving account number is 20001, you will receive a C01 NOC return (Incorrect DFI Account Number).

The simulated NOC return will have:

A type of ach_noc
An amount of 0 (NOCs are advisory and do not move money)
A code matching the NOC code (e.g., C01)
Dummy correction data, which will also be used to automatically update the receiving External Account

The following NOC codes are supported for simulation:

Account Number	NOC Code	Description	Dummy Correction Data
`20001`	C01	Incorrect DFI Account Number	`corrected_account_number: "123456789"`
`20002`	C02	Incorrect Routing Number	`corrected_routing_number: "021000021"`
`20003`	C03	Incorrect Routing Number and Account Number	`corrected_account_number: "123456789"`, `corrected_routing_number: "021000021"`
`20005`	C05	Incorrect Transaction Code	`corrected_transaction_code: "27"`
`20006`	C06	Incorrect Account Number and Transaction Code	`corrected_account_number: "123456789"`, `corrected_transaction_code: "27"`
`20007`	C07	Incorrect Routing Number, Account Number, and Transaction Code	`corrected_account_number: "123456789"`, `corrected_routing_number: "021000021"`, `corrected_transaction_code: "27"`

📘
NOC codes not listed above (e.g., 20008 for C08) will still generate a NOC return but without any correction data.

# Creates a Counterparty to simulate an ACH NOC with the code `C01`

curl --request POST \
  -u ORGANIZATION_ID:API_KEY \
  --url https://app.moderntreasury.com/api/counterparties \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "NOC Test Counterparty",
  "accounts": [
    {
      "account_type": "checking",
      "routing_details": [
        {
          "routing_number_type": "aba",
          "routing_number": "121141822"
        }
      ],
      "account_details": [
        {
          "account_number": "20001"
        }
      ]
    }
  ]}'

# Returns with an External Account with ID: 5acec2ef-987b-4260-aa97-b719eeb0a8d5

curl --request POST \
  -u ORGANIZATION_ID:API_KEY \
  --url https://app.moderntreasury.com/api/payment_orders \
  -H 'Content-Type: application/json' \
  -d '{
  "type": "ach",
  "amount": 1000,
  "direction": "credit",
  "currency": "USD",
  "originating_account_id": "0f8e3719-3dfd-4613-9bbf-c0333781b59f",
  "receiving_account_id": "5acec2ef-987b-4260-aa97-b719eeb0a8d5"
}'

For more on NOC returns, see Notification of Change (NOC).

For more on ACH Return codes, see ACH Return/NOC Codes.

Overview

Simulating Returns for ACH and Wire

Simulating ACH Notification of Change (NOC) Returns

NOC codes not listed above (e.g., 20008 for C08) will still generate a NOC return but without any correction data.

NOC codes not listed above (e.g., `20008` for C08) will still generate a NOC return but without any correction data.