Use Virtual Reference Numbers (VRNs) to route incoming ACH and domestic wire payments to a mapped Synthetic Account and associate receipts with your internal ledger.

Overview

A VRN is a receiving identifier that routes incoming payments to a mapped Synthetic Account. Multiple VRNs can map to the same Synthetic Account, allowing you to assign separate receiving identifiers for customers, payment types, business units, or other internal use cases without creating additional accounts.

This guide covers receiving ACH and domestic wire payments through VRNs. For Instant Payments (RTP), see Receive RTP Payments with Virtual Reference Numbers.

International ACH Transactions (IAT) are outside the scope of this guide.

VRNs have the following limitations:

• They can receive payments but cannot originate payments.
• They do not hold balances.
• They do not provide balance reporting.
• They map to Synthetic Accounts and should not be treated as balance-bearing accounts.

For background information, see Virtual Reference Numbers (VRNs).

Supported Receiving Methods

VRNs can be used to receive:

• ACH payments
• Domestic wire transfers
• Instant Payments (RTP), when your Client or Customer has Instant Payments rail access and the VRN's Instant Payment rail registration status is registered

VRNs cannot be used to:

• Originate ACH payments
• Originate wire transfers
• Hold balances
• Provide balance reporting

Prerequisites

Before you begin:

1. Identify the target Synthetic Account and record its synthetic_account_uid.
2. Obtain the ABA routing number associated with your VRN configuration.
3. Determine how you will associate VRNs with customers, payment purposes, or internal ledger records.
4. Review the Create Virtual Reference Number API Reference for current request requirements and validation rules.

Receiving Workflow

1. Create a VRN

Create a Virtual Reference Number and map it to the target Synthetic Account.

POST /api/v1/virtual_reference_numbers

Include the required x-trace-id request header and use a unique value for every request.

For request parameters, field definitions, validation requirements, and response examples, see the API reference.

After successful creation, record the VRN details for use in receiving and reconciliation workflows.

2. Store the VRN Mapping

Maintain a record of the relationship between:

• The VRN
• The mapped Synthetic Account
• The associated customer, business process, or ledger record
• Your external_uid, if used

Multiple VRNs can map to the same Synthetic Account. Your internal systems should maintain the mapping required to identify the intended recipient or purpose of each incoming payment.

3. Provide Receiving Instructions

Provide the sender with the appropriate routing information, including:

• The VRN
• The associated routing number

Payments sent to the VRN are routed to the mapped Synthetic Account.

Do not use a VRN to originate payments.

4. Monitor Incoming Transactions

Monitor incoming payment activity through your configured notification channel.

Newline supports notifications through:

• Webhooks
• Message Queue delivery

Use transaction notifications to:

• Identify newly received payments
• Track payment status changes
• Support reconciliation processes

For more information, see Notifications.

5. Reconcile Received Payments

Match incoming transaction activity to your VRN-to-customer or VRN-to-ledger mapping.

A typical workflow is:

Sender
  ↓
ACH Payment or Domestic Wire
  ↓
VRN
  ↓
Mapped Synthetic Account
  ↓
Transaction Notification
  ↓
Customer or Ledger Reconciliation

Use the VRN to identify the intended recipient, customer, or payment purpose. Use transaction activity to track individual payments, and use your internal ledgering processes to maintain balances and allocations.

For bring-your-own-ledger implementations, see Bring Your Own Ledger (BYOL) with EDAS.

Troubleshooting

Review the VRN Error Reference for common errors and remediation guidance.

Common examples include:

If a request fails, review the API response and returned error details before retrying.

Related Documentation

• Virtual Reference Numbers API Reference
• Virtual Reference Numbers (VRNs) Guide
• Receive RTP Payments with Virtual Reference Numbers