Adding Payment Reference Webhooks

Customers are now able to receive webhook notifications for when a Payment Reference is assigned to an existing payment. Payment References objects can be created any time after a payment enters the processing state. Data from the webhook can be used to enrich internal payment order tracking with the trace numbers banks attach to a payment, for example Trace Numbers for ACH payments and IMAD/OMAD numbers for wire payments [1].

This webhook event can also be used in tracking the lifecycle of a payment order by marking that it has been sent to a bank and that the bank has acknowledged it as being ready to send. Note that payment references can be created after a payment order has been completed and therefore should be reviewed before relying on them for workflow processing.

Payment References are immutable, allowing customers to store payment references directly onto their records of payment orders. Payment references are available as a timeline event of the payment order and can be retrieved via the API.

You can also filter Payment Orders in the Modern Treasury web application by reference number.

Additionally, payment_reference webhook events can be filtered in the Events page in the Developers section of the web application.

With this update, the customer will have access to the reference number, reference type, and information about the associated payment in the body of the webhook. Read more about this update in our docs.

Example Use Case

Let's take a look at how these new payment reference webhooks and UI additions can be used to ease operations.

The ACH Trace Number

One of the most common tracking references in the US is the ACH Trace Number. This is a tracking number stamped onto the ACH payments by the originating bank as it transmits the payments onto the NACHA payment network; Modern Treasury receives these in the NACHA file the originating bank sends. That’s when we add a Payment Reference linking the ACH Trace Number to the Payment Order (this usually happens between the sent and completed payment states, but sometimes after completed).

ACH Trace Numbers are important for our customers to observe because it’s the best way to inquire about the status of a payment with the receiving bank. When would a customer want to do this?

How ACH Trace Numbers Help Payroll Operations

Payroll customers can use this in their operations, as explained to us by one of our customers who provides payroll services—let's call them Pete's Payroll Company.

Say Pete's sends payroll via ACH, but for whatever reason, one of the payments, to Ed Employee, isn't received. Ed now has a lot of questions about the status of a payment.

Pete's needs to look into it. The best way to find the status of a payment marked as sent or complete in Modern Treasury is by providing Ed the ACH Trace Number so they can ask their bank about the payment. Ed now has a unique ID they can use to look into it. Pete's uses these tracking references to annotate their record of payments in their system to service common customer support and operational questions about the status of a payment.

Before this change, customers would get payment order lifecycle webhooks—there was a field in the webhook for payment_references that we’d populate with the tracking information we had at the time we sent the webhook. If we received the tracking information from the bank after the completed event, there was no way for customers to learn about updated tracking information without polling the payment order repeatedly.

Now, we push payment_reference.created webhooks directly to the customer as soon as we learn about a new, unique piece of tracking information for a payment. Customers can ingest these webhooks and store the tracking numbers directly within their system—no polling needed. The UI changes to the timeline also illustrate the schedule on which we transmit, reconcile and annotate payments with tracking information more clearly.

If you want to learn more about this update, or are interested in streamlining your payment operations, reach out to us.