Receive RTP Payments with Virtual Reference Numbers

Create and register a Virtual Reference Number (VRN) to receive RTP payments through its mapped Synthetic Account.

Prerequisites

Complete these steps before you create a VRN for RTP payment acceptance:

1. Confirm that your Client or Customer has access to the Instant Payments rail.
2. Create a general Synthetic Account. VRNs can only be mapped to general Synthetic Accounts; they cannot be mapped to external Synthetic Account types.
3. Configure either Message Queue or Webhook notifications if you plan to use asynchronous registration.

Create and Register a VRN

1. Call Create a new Virtual Reference Number.
2. Provide the required synthetic_account_uid for the general Synthetic Account that will receive payments.
3. Choose how to register the VRN for Instant Payments:
   • Use synchronous registration when your integration can wait for registration to complete before sending subsequent requests.
   • Use asynchronous registration when you need the VRN uid immediately. Monitor Message Queue or Webhook events for the registration result.

Registration with the RTP network may take several seconds. A VRN can receive RTP payments only after its Instant Payment rail registration status is registered.

Check Registration Status

Review the VRN's Instant Payment rail registration status before using it to receive RTP payments.

For the complete status definitions, see Virtual Reference Number Statuses.

Monitor Asynchronous Registration

When you select asynchronous registration, the create-VRN request returns the VRN uid before RTP network registration is complete. Subscribe to the appropriate event channel and continue processing registration updates until the VRN reaches a final status:

• registered
• unregistered
• failed

Use Message Queue Topics or Webhook Topic Definitions to configure the event delivery method used by your integration.

Receive and Reconcile RTP Payments

After the VRN status is registered, provide the VRN to the party sending the RTP payment. Newline maps payments received by the VRN to the associated general Synthetic Account.

Use the VRN as part of your reconciliation process to distinguish payments that are mapped to the same Synthetic Account. To review transaction data, use the List Transactions or Get a single Transaction endpoint.

Optional: Test Registration Failures in Sandbox

Test how your integration handles a failed asynchronous registration:

1. Create a VRN with synchronous_registration set to false.
2. Set the name field to a value that starts with instant payment fail.
3. Monitor the registration outcome through your integration.

For the full sandbox behavior, see Testing Error Scenarios.

Related Resources

• Virtual Reference Numbers (VRNs)
• Create a new Virtual Reference Number
• Virtual Reference Number Statuses
• Message Queue
• Webhook