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.
The only requirement to fail a general payment order is to send it to a Counterparty with an account number
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.
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 \
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.
Now that you have both the Internal Account ID and the Counterparty External Account ID, you can create the payment order.
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' \
Synchronous payment types like
RTP will trigger the correct webhook events as soon as you create the Payment Order. Batchable payment types such as
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:
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.
Updated about 2 months ago