Modern Treasury API Documentation

Welcome to Modern Treasury. You'll find comprehensive guides and documentation to help you start working with Modern Treasury APIs as quickly as possible, as well as support if you get stuck.

Send an ACH prenote

Overview

Modern Treasury supports the origination of ACH prenotes.

A prenote or prenotification is a $0 ACH payment order used to validate the account and routing information of a counterparty before sending live transactions. They are an alternative to using microdeposits, and do not require the counterparty to take any action during verification. The disadvantage of prenotes is that they take some time to complete validation.

Live payments can begin on the third banking day after the prenote has settled, provided no return has been received, and any Notification of Change (NOC) related to the prenote has been resolved.

In this guide, we will walk through an example of originating an ACH prenote.

1. Create the prenote

ACH prenotes are $0 ACH Payment Orders in Modern Treasury. The first step is to Create a $0 Payment Order.

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": 0,
    "direction": "credit",
    "currency": "USD",
    "originating_account_id": "0f8e3719-3dfd-4613-9bbf-c0333781b59f",
    "receiving_account_id": "5acec2ef-987b-4260-aa97-b719eeb0a8d5"
  }'

This API call will return a response that includes the payment order object.

{
    "id": "82171186-519f-44d9-a2dd-9c5de4054797",
    "object": "payment_order",
    "type": "ach",
    "amount": 0,
    "direction": "credit",
    "originating_account_id": "0f8e3719-3dfd-4613-9bbf-c0333781b59f",
    "receiving_account": {
        "id": "5acec2ef-987b-4260-aa97-b719eeb0a8d5",
        "object": "external_account",
        "account_type": "checking",
        "party_name": "John Smith",
        "party_type": null,
        "party_address": null,
        "account_details": [
            {
                "id": "3994463f-7652-4e4f-b9c6-9ee06427cccc",
                "object": "account_detail",
                "account_number": "333333334",
                "account_number_type": "other",
                "live_mode": true,
                "created_at": "2021-03-15T21:52:05Z",
                "updated_at": "2021-03-15T21:52:05Z"
            }
        ],
        "routing_details": [
            {
                "id": "c20c51e7-c4a7-4637-b6c9-8c0709667922",
                "object": "routing_detail",
                "payment_type": "sen",
                "routing_number": "021000021",
                "routing_number_type": "aba",
                "bank_name": "GOLIATH NATIONAL BANK",
                "bank_address": {
                    "id": "cc3cf074-00f6-456d-b3f8-e727de7f63f9",
                    "object": "address",
                    "line1": "36535 Nia Lane",
                    "line2": null,
                    "locality": "Watsicaview",
                    "region": "AR",
                    "postal_code": "93751-4071",
                    "country": "US",
                    "live_mode": true,
                    "created_at": "2021-03-15T21:52:05Z",
                    "updated_at": "2021-03-15T21:52:05Z"
                },
                "live_mode": true,
                "created_at": "2021-03-15T21:52:05Z",
                "updated_at": "2021-03-15T21:52:05Z"
            },
        ],
        "created_at": "2021-03-15T21:52:05Z",
        "updated_at": "2021-03-15T21:52:05Z",
        "name": null,
        "metadata": {},
        "live_mode": true,
        "verification_status": "unverified"
    },
    "receiving_account_id": "71fae619-afa6-45e6-8630-ce4d0b3d6387",
    "receiving_account_type": "external_account",
    "accounting_category_id": null,
    "accounting_ledger_class_id": null,
    "currency": "USD",
    "effective_date": "2021-04-02",
    "priority": "normal",
    "description": null,
    "statement_descriptor": null,
    "remittance_information": null,
    "metadata": {},
    "status": "approved",
    "counterparty_id": "928db55e-6552-4aaf-96d7-10c693922b1f",
    "transaction_ids": [],
    "charge_bearer": null,
    "foreign_exchange_indicator": null,
    "foreign_exchange_contract": null,
    "nsf_protected": false,
    "originating_party_name": null,
    "ultimate_originating_party_name": null,
    "ultimate_originating_party_identifier": null,
    "ultimate_receiving_party_name": null,
    "ultimate_receiving_party_identifier": null,
    "current_return": null,
    "reference_numbers": [],
    "live_mode": true,
    "created_at": "2021-04-02T02:35:00Z",
    "updated_at": "2021-04-02T02:35:00Z"
}

2. Monitor the prenote

Once the payment order has been created, it will be transmitted to the bank prior to the next cutoff. You may monitor the payment order's status via the API or by subscribing to the Payment Orders webhooks. Note that originated prenotes will not show up as transactions in Modern Treasury and the payment order object will remain in a sent status unless returned.

You can monitor for returns on the payment order by subscribing to the Returns webhooks.

  • If the payment order is returned, you must correct the error denoted by the return code and submit a new prenote.
  • If a Notice of Change (NOC) return is received, Modern Treasury will automatically update the counterparty data accordingly and you can begin live transmission.

You may begin live transmission on the third day following the payment order effective date if the payment order has not been returned.

Updated about 18 hours ago


Send an ACH prenote


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.