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.
Note
Different 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.
Remember
Remember, Transaction and Transfer types are determined by the destination Synthetic Account you provided which 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 originating through Newline's API platform. We've designed Transfers to be simple and easy to initiate, with most setup housed in other key API constructs.
Before we dive into the business of payments, let's talk through those complimentary constructs.
| API | Usage |
|---|---|
| Synthetic Accounts | Synthetic 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. |
| Customers | While 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. |
| Transmitters | Transmitters 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. For more context on Transmitters, refer to the Payment Rail Regulation section below. |
| Transfers | As 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. |
| Transactions | Transactions 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.
| Field | Context | Required/Optional |
|---|---|---|
counterparty_address | The address associated with your designated counterparty. This will include fields to supply a full mailing address, including country. | Optional |
counterparty_name | This is the name of the counterparty (consumer or business entity). | Required |
account_number | The account number of the counterparty in question. For example, this will be the account credited by the outbound wire originated. | Required |
routing_number | The 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. 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.
| Field | Context |
|---|---|
external_uid | This 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_uid | This 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 many 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.
Payment Rails
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 supported for your Program and what inherent Transfer limits exist as part of payment controls (as mandated by Fifth Third Bank).
Payment Rail Regulation
As a platform maintained by a regulated, financial institution, Newline may require certain information on Transfer requests in order to begin processing. These requirements may also change depending on the payment rail chosen for a Transfer. In this section, we seek to detail out public regulations so that Clients understand their responsibilities when transacting with Newline.
Electronic Funds Transfer Act (Regulation E)
The Electronic Funds Transfer Act (enforced by and commonly referred to as "Regulation E" or "Reg E") establishes a set of protections for Consumer users of Electric Funds Transfers (or EFTs) that must be enforced and provided by the financial institutions and payment networks offering the EFT in question.
This often includes providing certain controls over access to a Consumer's funds. For example, ACH debit entries can only be programmatically executed by a company if they have received authorization from the Consumer in question.
For more information about Regulation E, check out the CFPB's detailed documentation .
Travel Rule
The objective of the Travel Rule is to require banks, and non-bank financial institutions to maintain high-quality records to aid FinCEN and other government agencies in criminal investigations when bad actors leverage fund transfers. The rule preserves the information trail on who is sending and receiving funds through transfer systems. Given that clients can maintain programs that involve multiple layers of funds management, Newline has created the concept of a transmitter to allow for easy submission of originator information.
The initiate a Transfer endpoint details the data requirements for both Wire and Instant Payments Transmitters.
FinCEN defines the different categories of Transfers, which can be found in their Advisory FAQ. Certain categories of Transfers are exempt from the Travel Rule, as many but not all are covered by Regulation E.
- ACH Transfers
- ATM Transactions
- Point of Sale (POS) Transactions
- Direct deposits or withdrawals
- Transfers initiated over the phone
- Transfers under $3,000 dollars
- Transfers between the same party or person (referred to as me-to-me Transfers)
- Transfers within the same financial institution
- Transfers between the following entities:
- A bank, or a U.S. subsidiary thereof
- A commodities or futures broker, or a U.S. subsidiary thereof
- The U.S. government; a state or local government
- A securities broker or dealer, or a U.S. subsidiary thereof
- A mutual fund
- A federal, state or local governmental agency or instrumentality
Updated about 2 months ago