Simulate a Payment Order Failure

Overview

Before making requests, you will need your API Key and Organization ID. To find these, you can follow this guide: Retrieve your API Key.

In the sandbox, you may want to simulate workflows where you have originated a Payment Order that fails. This guide walks you through how to simulate these workflows so you can build the end-to-end experience in your application.

Currently, you can simulate payment order failures for the following payment types: ACH, Wires, RTP, and Checks.

For ACH, Wires, and RTP there is a Counterparty titled Lucius (General Failure) within the Sandbox environment that you can create Payment Orders to in order to simulate these failures.

For Check payment orders, we have a different Counterparty titled Bellatrix (Check Failure) that you can use to simulate check failures.

The difference between these counterparties is that the account number in Lucius (Automatic Failure) is used to identify failure payment orders, while the address line in Bellatrix (Check Failure) is used instead. This also allows you to create your own test counterparties and retain the capability to simulate payment order failures.

How Payment Orders are failed for a Counterparty

The only requirement to fail a general payment order is to send it to a Counterparty with an account number 11111111X...X (eg. 111111110). The only requirement to fail a check payment order is to send it to a Counterparty with a specified address line of 1111 Azkaban Unit 321.

If these counterparties do not exist, you can create it within the sandbox, either through the API or within the web application.

For information on the lifecycle of a payment order, see this reference.

1. Retrieve your Internal Account ID

To get an Internal Account ID, you can pick one from your accounts page. Any of the IDs will work for testing, though you can refer to Internal Accounts to see the differences in how the test banks process payments.

If you want to get all the internal accounts using the API , you can issue the following request:

curl --request GET \
  -u ORGANIZATION_ID:API_KEY \
  --url https://app.moderntreasury.com/api/internal_accounts

2. Retrieve the Counterparty External Account ID

Out of the default counterparties within Sandbox, you will need to select the appropriate counterparty for your situation. Lucius (General Failure) is the counterparty to simulate payment order failures for ACH, Wires, and RTP while Bellatrix (Check Failure) is specifically for Check failures.

You can fetch the Counterparty external account ID by going to the counterparties page, navigating to Lucius' counterparty detail page, and selecting the ID of one of the bank accounts. Note: this is not the Counterparty id, but rather the id of one of its external accounts.

3. Create a Payment Order

Now that you have both the Internal Account ID and the Counterparty External Account ID, you can create the payment order.

The originating_account_id will be your Internal Account ID, and the receiving_account_id will be the Counterparty External Account ID you retrieved earlier. Specify the other details accordingly to your preference.

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

4. Monitor for Webhook Events

Synchronous payment types like RTP will trigger the correct webhook events as soon as you create the Payment Order. Batchable payment types such as Wires and ACH will have a delay of at least 1 minute before the payment order finishes its failure state lifecycle.

Following the reference for Payment Order states and events, you will see these events in order: approved, begin_processing and then failed. Dependent on whether you are using the asynchronous or synchronous endpoint to create Payment Orders, you may also see the created webhook before the Payment Order is approved.