Transfers

Quick Start: Make a Transfer!

Below is a detailed guide on how to make a Transfer using the Newline platform. In this guide, we go through each step, the API and endpoints utilized, and any best practices when originating payments.

However, for those familiar with payments and eager to kick off their first transfer, we've provided a short list of steps to get money moving fast.

Step 1: Determine Source and Destination Synthetic Accounts

Identify your source (i.e., debited party) and destination (i.e., credited party) Synthetic Accounts. If you have not established either, utilize the POST endpoints.

NoteDifferent payment rails require different fields for counterparties, so be sure to review the fields provided to determine if they satisfy said requirements.

See our Payment Rails guides for more details.

Step 2: Initiate Transfer

Once you've identified your source and destination Synthetic Accounts, proceed to initiate a Transfer.

NoteRemember, Transaction and Transfer types are determined by your provided destination Synthetic Account, and this impacts payment execution SLAs.

Step 3: Review Status

After the expected execution time has elapsed, you'll want to pull details on the enacted Transfer to ensure it's been successfully sent. You can utilize either the get a single Transfer or list Transfers endpoints. Newline also supports a message queue to notify Clients of state changes.

Introduction: What is a Transfer?

Transfers are the basis for payments originated through Newline's API platform. We've designed Transfers to be simple and easy to initiate, with the majority of setup housed in other key API constructs.

Before we dive into the business of payments, let's talk through those complimentary constructs.

APIUsage
Synthetic AccountsSynthetic Accounts are used to represent both Customers accounts and external accounts. These external accounts can represent accounts held at other institutions by the same Customer, or they can represent another entity, be it another individual or business.
CustomersWhile not directly impacted by making a Transfer, Customers are required during origination to specify the sending (or initiating) party. Optionally, you can also supply a destination Customer, if appropriate.
TransmittersTransmitters are the parties who have requested the Transfer in question. When the Transmitter and Customer are the same party, Newline pulls origination information from the created Customer record. When the Transmitter and Customer are not the same party, it's the Client's responsibility to provide that information when making a Transfer.

Transmitters are only required for the wire and instant_payment types (see the wire_transmitter and instant_payment_transmitter objects in the Initiate a Transfer reference). Client's should also take note of the initiator_type field, which dictates from where Transmitter information is pulled.
TransfersAs described above, Transfers are payments. Transfers are a subset of Transactions, and their specific Transaction Statuses and Transaction Types are determined by the source and destination Synthetic Accounts selected.
TransactionsTransactions are the umbrella construct that define any financial activity, recorded by Newline, against a Synthetic Account. Transactions can be produced by Transfers or represent activity on an account originated outside of Newline; however, Transactions originated outside of Newline will not have a associated Transfer.

How are Transfer type and direction determined?

One of the key items to determine before executing a payment is the counterparty. Might seem obvious to point out, but determining your counterparty also determines what type of transfer will be executed.

In addition, certain Transfer types, like ach, allow for a counterparty to be debited, rather than credited. This is often referred to as the direction of a Transfer. To send a debit Transfer, simply place the counterparty's Synthetic Account as the source_synthetic_account on the Transfer, and the Customer's account information as the destination_synthetic_account.

Creating a Synthetic Account

The Synthetic Account represents two major roles within Newline's Transfer origination flow: the source (also known as payor or originator) and the destination (also known as payee or beneficiary). Through the Synthetic Accounts API, users can create new Synthetic Accounts and set the type using the synthetic_account_type_uid, which would set the synthetic_account_category. The synthetic_account_category governs if a Synthetic Account can be used as a source, a destination or the payment rail used when creating a Transfer.

However, when creating an external Synthetic Account and the intent is to use a specific payment rail, you'll need to provide certain information to successfully execute the payment. For instance, when creating a wire transfer, the following fields are supported. Please note those listed as required.

FieldContextRequired/Optional
counterparty_addressThe address associated with your designated counterparty. This will include fields to supply a full mailing address, including country.Optional
counterparty_nameThis is the name of the counterparty (consumer or business entity).Required
account_numberThe account number of the counterparty in question. For example, this will be the account credited by the outbound wire originated.Required
routing_numberThe routing number of the Bank (or Financial Institution) at which the counterparty's account is maintained.Required

For details about counterparty requirements with different payment types, see our Payment Rails guides. Additionally some payments types, like book_transfers, don't require counterparty details because the originating and counterparty entities are the same.

If all the following fields have been appropriately populated, you'll receive a success response detailing the newly created uid (i.e., unique id) attributed to the Synthetic Account.

Retrieving Synthetic Accounts

Similarly, if you already have a Synthetic Account created that you'd like to utilize as a counterparty, then you can utilize its specific uid. To retrieve the unique ids of Synthetic Accounts previously created, you can list Synthetic Accounts by providing the corresponding customer uid.

Remember, the Synthetic Account type determines what type of Transfer will be initiated when enacted, so you may want to confirm the Synthetic Account's type. This can be accomplished using the get a Single Synthetic Account Type endpoint.

Handling Duplicate External Synthetic Accounts

If you attempt to create a Synthetic Account that has already been created, Newline will respond with an error (code 2002) that provides the uid of the duplicate Synthetic Account. This allows for creating a Transfer without the get or list Synthetic Accounts endpoints. Since Newline provides the uid in the response, storing is optional.

Let's make a Transfer!

At this point, you've done all the pre-work to create a Transfer, great job! The next steps are as follows:

Step 1: Designate the source and destination Synthetic Accounts

Step 2: Designate the initiating Customer

Step 3: Make a request to initiate a Transfer

Additional fields for Client Usage

Newline supports fields that can be provided at the point of origination that assist in Client reporting and payment tracking. In this section, we quickly cover these fields and their proposed uses, but more in depth information can be sourced directly from the API reference.

FieldContext
external_uidThis is an external uid provided by the client. For example, if your product issues internal uids for each transaction initiated on your platform, you could provide said uid in this field as a reference. This can help with reconciliation and payment operations as Customer requests flow through multiple layers of technology before any payment is originated.
destination_customer_uidThis field is required for peer-to-peer (i.e., Customers within the same Client Program) Transfers, and is optional for all other Transfer types. Its express purpose and benefit is auditing destination, that way appropriate reconciliation and balance checks can be performed on the respective debited and credited Synthetic Accounts.

Transfer Statuses and Workflow

Once your transfer is executed, it'll move through a number of states before eventually reaching a resting or end state. You can review the supported Transfer Statuses in our API reference. This workflow is also how you'll be able to verify that a Transfer is complete. You'll want to utilize either the get a single Transfer or list Transfers endpoints to retrieve existing Transfers and their respective states.

Transfer Notifications

Newline will support a message queue (Newline Message Queue or NMQ) that will allow Clients or Customers to receive updates about Program or Customer level events. In the context of Transfers, Newline supports topics on Transfer initiation and status change. For more information about NMQ, please read our Message Queue guides.

Transfer Cancellation

In the event you need to cancel a Transfer submitted, you can utilize the cancel a Transfer endpoint. Cancellation is only available if your Transfer is still in a queued or pending state. A pending state cancellation is not guaranteed as this state also includes payment execution. At that stage, a cancel request will result in an error.

Transfer Rails and Limitations

Newline supports the following payment rails. Please see each payments' respective guide (starting with our Payment Rails) to learn more about requirements and implemented features.

During your onboarding process, we'll discuss the different layers of controls around Transfers, specifically what types of Transfers are support for your Program and what inherent Transfer limits exist as part of payment controls (as mandated by Fifth Third Bank).