Simulate a Return

When creating a payment order through Gringotts, it is possible to set up the payment so that it will trigger a return. Currently, you can trigger returns for ACH, Wires and EFT payment orders by sending them to their respective Sandbox Counterparty.

This is different from originating a return. By simulating a return, you receive the return rather than initiating it.

If you do not have any of the default Counterparties, you can create them following the instructions below or using code snippets we have provided.

To simulate ACH returns, 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 EFT returns, you must create a payment order that is sent to a Counterparty who has a bank account number as 101XX where XX is the EFT return code you wish to trigger.

To simulate Wire returns, 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 code specified.

Simulated returns will be posted within minutes after the original payment orders have been sent to the bank. This mirrors how returns work in the real world, since your bank will mark the payment order as completed but any returns will come after the fact.

# 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"
}'

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