Virtual Reference Numbers (VRNs)

Quick Start: Create a Virtual Reference Number!

Talk about a quick guide, you can create a Virtual Reference Number in one API call!

Step 1: Create and map a VRN to a Synthetic Account

Using the POST create a new Virtual Reference Number endpoint, you can create a new Virtual Reference Number by supplying the only required field, a synthetic_account_uid. This allows Newline to easily map your requested Virtual Reference Number to the Synthetic Account in question.

Optional: Synchronously register your VRN for instant payment acceptance

NoteFor Virtual Reference Number (VRN) Instant Payment rail registration, this is dependent on the Client or Customer having purchased access to the Instant Payment rail. If a Client or Customer has not purchased access to Instant Payments, they can still utilize VRNs to receive ACH entries and Wire payments; however, their VRNs will, by default, have a rail registration status of unregistered.

Within the above API call, you can also specify if you'd like your newly created VRN to be synchronously registered with Newline for Instant Payment acceptance vs. having it registered asynchronously.

While the registration process is typically instant (no pun intended), it can take up to several seconds to complete. For this reason, Newline allows clients to choose to either wait for the process to complete with a long running request (i.e., synchronous registration) or allow the process to complete asynchronously. The main difference here is that the former choice will require the Client or Customer to hold any subsequent requests until it completes.

The asynchronous option will provide the VRN uid immediately, and Clients or Customers will be notified of Instant Payments registration via MQ events (see our Topics guide for more details).

Instant Payments acceptance is unique, compared to ACH and Wire acceptance, as the RTP network requires additional steps for registering a VRN before it is ready to use.

NoteYou can only map Virtual Reference Numbers to general Synthetic Accounts, not any Synthetic Account of an external type, meaning Wire, ACH, or Instant Payment types.

Introduction: What is a Virtual Reference Number (VRN)?

Virtual Reference Numbers (or VRNs) are virtualized account numbers. They are aliases to a Synthetic Account, and can form a many-to-one relationship with their parent Synthetic Account.

VRNs vs. Synthetic Accounts?

It's important to remember that VRNs are not actual accounts, rather pointers to accounts. That means that when comparing them against Synthetic Accounts, the have following key differences

  • VRNs do not hold balance or maintain any balance reporting.
  • VRNs cannot originate payments, only accept (or receive) payments.
  • VRNs are not a depository product, and therefore don't receive the same protections, like FDIC insurance.

VRN Use Cases

VRNs can be utilized in a number of use cases, and below are two detailed examples of common use cases.

External Ledger Alignment

Clients who have built stored funds product offerings (like a staged wallet) may already maintain the concept of a ledger. This external ledger maintains their needed reporting, performs reconciliation, and creates an auditable trail for financial activity. However, those stored funds products still need to be built off of a deposit account.

Newline can help form that connection by having the Client tie any stored funds product to a corresponding VRN. Payments can then be accepted, via the VRNs, and then originated through a Program Account opened on Newline, creating the classic bi-direction payments flow. This is commonly referred to as deposit program sponsorship.

Payment Acceptance and Controls

Clients and Customers will be able to utilize payment authorization logic to review and approve any received traffic to their managed VRNs. This easily establishes a control layer for payment acceptance, mitigating the risk of receiving an incorrect payment or debit.

Mitigating Fraud Risk

Clients and Customers can also utilize VRNs in for any one time payment acceptance need without providing an account number. This reduces fraud risk by not exposing account numbers to a large number of counterparties; in addition, if fraudulent activity is detected, VRNs can be archived without affecting parallel account operations.