--- updatedAt: 2025-12-11T22:20:26.000Z agentTools: projectIndex: https://developers.newline53.com/llms.txt --- # Transfers ## Quick Start: Make a Transfer! Below is a detailed guide on how to make a [Transfer](https://developers.newline53.com/newline/reference/transfers) 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](https://developers.newline53.com/newline/reference/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](https://developers.newline53.com/newline/docs/payment-rails-1) guides for more details. **Step 2: Initiate Transfer** Once you've identified your source and destination Synthetic Accounts, proceed to [initiate a Transfer](https://developers.newline53.com/newline/reference/post_transfers). **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](https://developers.newline53.com/newline/reference/get_transfers-uid) or [list Transfers](https://developers.newline53.com/newline/reference/get_transfers) endpoints. Newline also supports a message queue to notify Clients of state changes. ## Introduction: What is a Transfer? [Transfers](https://developers.newline53.com/newline/reference/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](https://developers.newline53.com/newline/docs/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](https://developers.newline53.com/newline/reference/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](https://developers.newline53.com/newline/reference/post_transfers) 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](https://newline-enterprise-group.readme.io/docs/transfer#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](https://developers.newline53.com/newline/reference/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](https://developers.newline53.com/newline/reference/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](https://developers.newline53.com/newline/docs/payment-rails-1) 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](https://developers.newline53.com/newline/reference/get_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](https://developers.newline53.com/newline/reference/get_synthetic-account-types-uid) 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](https://developers.newline53.com/docs/api-errors-1#synthetic-account-errors)) that provides the uid of the duplicate Synthetic Account. This allows for creating a Transfer without the [get](https://developers.newline53.com/newline/reference/get_synthetic-accounts-uid) or [list](https://developers.newline53.com/newline/reference/get_synthetic-accounts) 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](https://developers.newline53.com/newline/reference/post_transfers) ### 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](https://developers.newline53.com/newline/reference/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](https://developers.newline53.com/newline/reference/get_transfers-uid) or [list Transfers](https://developers.newline53.com/newline/reference/get_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](https://developers.newline53.com/newline/docs/overview) guides. ### Transfer Cancellation In the event you need to cancel a Transfer submitted, you can utilize the [cancel a Transfer](https://developers.newline53.com/newline/reference/put_transfers-uid-cancel) 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](https://developers.newline53.com/newline/docs/payment-rails)) to learn more about requirements and implemented features. * [Wire](https://developers.newline53.com/newline/docs/wire) * [ACH](https://developers.newline53.com/newline/docs/ach) * [Instant Payments](https://developers.newline53.com/newline/docs/instant-payments) 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](https://www.consumerfinance.gov/rules-policy/regulations/1005/) . **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](https://developers.newline53.com/newline/reference/post_transfers) 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](https://www.fincen.gov/resources/advisories/fincen-advisory-issue-3). 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