Hello! My name is Ben Gentry and I’m a software engineer here at Orum.

As you saw a few weeks ago, we recently launched v2 of our API! While we’ve given a broad overview, I’d like to walk you through some of the technical aspects of our new design.

Motivation and approach

This new API version comes after 6 months of battle-testing by our customers and greatly simplifies our API by providing a more intuitive interface.

API design, much like code structure, is difficult to scope correctly right off the bat. For instance, you can’t be sure of all future use cases and functionality, so it’s impossible to know all possible types of end users.

Once we went through the feedback loop with customers, our product team had a better understanding of the use cases from our MVP phase, and our engineering team found a way to make the API more intuitive without any major re-architecting on the backend.

We settled on a facade pattern enabling us to map parties from the new API design to our backend models. This allowed us to completely restructure our API resources at the edges of our product, while supporting  continuous improvements and feature additions on the backend with little interruption to the existing architecture and data modeling.

Status reasons

Along with the simplified restructuring of the API design, we also added several new features to improve the integration and the user experience. 

The first was status reasons. Status reasons provide reporting on why a transfer or customer did not reach the intended status by aggregating status codes from our third party integrations.

We also elected to return the raw processor status codes to support end users interested in the maximum level of detail. For example, a failed transfer will return the rail, network code, and message returned by the processing bank. For customers who prefer a simpler explanation, we also return an Orum-generated error code and message to provide a higher level categorization of the failure. 

One use case where this might be useful is an account to account transfer where the source account does not have enough funds for the transfer. In this case, we would return the following information asynchronously via webhooks, which allows for communication with the end user so that they can update their account and retry the transfer request.

Estimating funds delivery

Finally, we added a feature to estimate the day that the transfer funds will be reflected in the receiver’s bank account. Estimating this date can be tricky since this is partially up to how and when the receiving bank opts to present the funds. 

For an account-to-account transfer, we have to factor in the time to pull funds from the source account, with confidence the funds will not be returned, as well as estimate when the destination account will see funds available in their account. 

The complexity needed to calculate this date is all worth it to ensure that customers have visibility into when their money will arrive. For transfers made using the RTP network, the delivery date might even be 2pm on a Sunday since RTP is working 24/7/365.

Moving forward

In the future, once we have additional feedback, we’ll be able to provide even more detailed reasons as to why a transfer was not successful, as well as more accurate estimates for exactly when funds will be available. We will continue to engage with the feedback loop and learn which features will have the biggest impact for our customers. Since launching v2, we’ve already drastically enhanced our API error messages to include not only detailed descriptions of the issue, but also next steps to help you get unblocked.

We’re excited to hear more of your feedback and to be your partner in creating an intuitive, comprehensive payments program! On average, customers go live with Momentum in a single sprint, so reach out if you’re interested in hearing how you can integrate an end-to-end payments platform with a single API. In the meantime, our docs are available here for your viewing pleasure.