### **API Reference**

**Plaid Integration**

  • [Introduction for Plaid Integration](🔗)

  • [**POST** Recurring Deposits using bankAccountID](🔗)

  • [**GET** Recurring Deposit Schedule By ID](🔗)

  • [**GET** Recurring Deposits by userID](🔗)

  • [**PATCH** Recurring Deposit](🔗)

  • [**DELETE** Recurring Deposit](🔗)

  • [**GET** Deposit Details](🔗)

  • [**GET** List all Deposits by userID](🔗)

  • [**GET** List all Deposits by accountID](🔗)

**Redemptions**

  • [**POST** Create A Redemption/Withdrawal](🔗)

  • [**GET** Redemption Details](🔗)

  • [**GET** List All Redemptions](🔗)

  • [**GET** List all Redemptions by accountID](🔗)

  • [**GET** List all Redemptions by userID](🔗)

**SQS Reference**

  • [Deposit Events](🔗)

  • [Withdrawal Events](🔗)

  • [Linked Bank Account Events](🔗)

## **Task F1** - Review Deposit Workflow

  • _Review Deposit Workflow - After establishing a US brokerage account, the next phase of steps involves funding the account, this will enable trading. For individual funding, the most common method and what is recommended by DriveWealth is ACH for Partners that are domiciled in the US_

  • Each customer will fund their individual DriveWealth brokerage account. This can be achieved multiple ways; US Customers can use DriveWealth’s Deposit API to initiate ACH transfers from the customer's bank account to the customers individual brokerage account. For non US Partners, customers may fund their accounts via an FX provider, or Wire

  • **For non US partners, all accounts funds must be converted to USD prior to landing in the customers DriveWealth brokerage account **

  • **Regular status checks for Plaid integration (or another banking link) are required**

  • **DriveWealth requires a Balance check prior to each funding instruction to identify if customer has enough money in their bank account to cover the deposit amount or not**

  • If not integrating with Plaid leverage the bank account number and routing number provided back from your vendor and pass through the endpoint

    • The Bank Accounts API does not validate bank account numbers or routing numbers, it will accept any input provided by the third-party bank data aggregator

\-It is possible for the customer to have multiple bank accounts associated with their user

  • **All `bankAccountNumber’s` must be 9 digits in length**

  • **Store the value from the Response for `bankAccountID`**

  • **IF NOT USING INSTANT FUNDING** - RARELY USED

    • **Pre-Funding **- The customer must fund their individual DriveWealth brokerage account prior to trading. Buying power of the customer will only be increased once funds settle in their brokerage account. Once the funds are settled, the customer can use these funds to trade on the platform.

### Individual Funding Money Movement Matrix

Domestic Partner (USA)Individual funding options
**Yes**- ACH - Wire - Money transmitter
**No (International Partner)** - Wire - Money transmitter

### ACH Information

  • U.S. Partners most frequently use the Automated Clearing House (“ACH”) system, for electronic customer money movement

    • The Automated Clearing House (ACH) Network is an electronic funds-transfer system run by NACHA, formerly the National Automated Clearing House Association, since 1974. This payment system provides ACH transactions for use with payroll, direct deposit, tax refunds, consumer bills, tax payments, and many more payment services in the United States.

  • **ACH is NOT Available for Non-U.S. Partners**

  • Settlements - Typically takes 2-3 days to complete. If using Instant trading mechanism `buyingPower` is increase immediately but ACH still needs up to 3 days for settlement

  • Cost - Materially lower than wire transfer costs

  • Certainty - ACH transfers can be reversed, and have a higher rate of failure than other deposit methods

  • Withholding period - This can be adjusted by counter-party, DriveWealth suggests a 30-day holding period to mitigate fraudulent activities by customers

  • Customer bank - If DriveWealth is pulling the ACH on the customer bank record the name of the entity can be modified to be that of the Partner

  • ACH Failure Treatment - **Can occur and counter-parties are charged ACH failure fees for processing**

    • Most common “Not Sufficient Funds (“NSF”)”

    • A NSF triggers [Money Flow Events] which immediately notify the PartnerOtherwise, the

    • Partner may also use the "Get Deposit Details"

### Wire Information

  • Wires are most frequently used when transferring large amounts of money. A customer initiates a wire to DriveWealth’s customer receipts account. Wires are supported in the U.S. and are also a funding option across a network of banks around the world

  • Customer funds are pushed by a direct wire transfer from the customer’s DriveWealth brokerage account to the Customer’s 3rd party bank account.

  • Outside the US, Partners will establish a relationship with a Foreign Exchange (F/X) provider who can sell USD and buy local currency. The Partner will then allocate the local currency to the customers local bank account

  • Settlements - Typically takes 1 business day

  • Cost - Can be Expensive

  • Certainty - Difficult to pull back a wire

  • Jurisdiction - Available for Domestic and International Partners

  • Withholding period - None

  • Customer bank - Customer funds are pushed by a direct wire to the customer’s DW brokerage account. Note: Customers using wires must include their DriveWealth investment account in the wire details/comments field

  • Non US Partners - Partners will establish a relationship with a provider who can execute local currency F/X and remit USD to DW with an aggregated wire that can be allocated to customer accounts

### Third Party providers

_CurrencyCloud or Other FX Broker/Provider_ – DriveWealth offers established methods for foreign counter-parties to fund their customer’s brokerage accounts. Counter-parties can elect to utilize these funding channels, or secure other relationships with locally registered F/X brokers to process F/X and transfer activities to DriveWealth’s investment account.

_Western Union and Transferwise_ – Provide similar services at CurrencyCloud or other counter-party specific money transmitters.

## **Task F2** - Create a deposit via API

  • **2 Methods:**

    • **PRIMARY **- "Create Deposit" API is used to pull customer money (Customer provides instruction to DriveWealth, via API – acting on that instruction and with the information the customer has provided, DriveWealth will initiate an ACH pull from the customer’s bank account)

    • _RARELY USED_ - 3rd Party - A counter-party initiates a deposit to DW directly from their banking account, providing DriveWealth’s recipients account information as the destination. This process utilizes a 3rd party such as Stripe or Dwolla to initiate. Customers' account numbers and banks routing numbers may be retrieved from the Accounts API which the partner may utilize to create a better payment flow experience through 3rd party API’s

  • Customers may link their bank account(s) to their DriveWealth brokerage account to make recurring or ad hoc deposits into their brokerage account

  • Customers can also pay brokerage subscription fees to the Partner on a regularly scheduled basis. All bank information stored at DriveWealth is tokenized for security purposes

  • **INSTANT BUYING POWER**

  • **AFTER successfully tokenizing bank account details request an ACH deposit in the customers account**

    • Clients can immediately place orders after the posting of a deposit in place of waiting 1 to 2 business days for ACH settling; this creates a more real-time experience for end-users by enabling order placement without ACH processing delays

    • Funds are credited for buying power instantly `cashAvailableForTrade` will go up upon ACH placement. **Cash available for withdrawal must wait for receipt of funds** - `cashAvailableForWithdrawal` will not increase until the holding period has concluded.`cashBalance` (settled +unsettled cash) will not increase until the funds have settled with our bank

  • **Deposits are sent to the bank at 9:00 PM EDT daily,** meeting the bank defined cutoff time for next day funding

    • Deposits will automatically change deposit values or “statuses” from **STARTED**, to **PENDING**, to **APPROVED**, and to **SUCCESSFUL**

**ACH FAILURE**

  • If a Deposit is Rejected - ACH RETURNS:\* the status changes to **RETURNED** (status number 5) and **Account status** moves to **OPEN_NO_NEW_TRADES** (account can only create sell orders, liquidate only)

  • A SQS deposits.updated event will alert you to the return Examples: insufficient funds, bank account closed, invalid routing number, etc.

  • If a deposit is returned, a negative Financial Transaction will be posted to the customer’s account; the comment will include the reason returned by the contra bank/ financial institution. For example, you may see a comment of R08- Payment Stopped, providing greater insight into failed transactions and monitoring.

  • **When an ACH return is processed and the customer had made an investment, it's possible a debit balance is created based upon the liquidation of the stock held. The Partner is responsible for covering that debit balance if the customer does not create any further deposits**

    • Note: DriveWealth reserves all rights in regard to when it takes these actions

    • All monetary loss from any ACH failure will be charged back to the partner

    • DriveWealth’s next steps depend on whether or not the customer used the funds to purchase securities

    • No - the funds will be debited from the customer account, zeroing out the customer. The Partner will be charged an ACH return fee

    • Yes - DriveWealth will liquidate the securities positions that used the ACH funds in the partner’s error account; the customer or counter-party will be charged for the return processing fee

### Recurring Deposits

  • _Establish Recurring Deposits in a Test Account (if applicable)_

  • **The API does not support creating a one-off deposit at a future point in time**

  • **Start date for recurring deposits is based on when the API request is made; there will be a deposit initiated on that same day, and then again continuously at the recurring frequency**

  • The /funding/deposits endpoint facilitates recurring deposits. If a `frequency` attribute is added to the deposit request, DriveWealth will automatically generate the scheduled ACH deposit based the value:

    • DAILY - deposits processed daily

    • BIWEEKLY - deposits processed on every other Monday

    • MONTHLY_FIRST - deposits processed on the First of every month

    • MONTHLY_MIDDLE - deposits processed mid monthly, every month

    • QUARTERLY - deposits processed on the First, every 3 months

### 7 Day Holding Period Example Deposit and Timeline

  • **All ACH deposits carry a holding period to help reduce the adverse effects of a return occurring prior to ACH settlement. The typical holding period is set at 7 days, and does impact cash values in a customers account as identified below**

Sample DepositSample Timeline
**T+0: $100 ACH Deposit request submitted** - `cashAvailableForTrade`: $100 - `cashAvailableForWithdrawal`: $0 - `cashBalance`: $0 **T+0: Customer Purchases $50 of AAPL** - `cashAvailableForTrade`: $50 - `cashAvailableForWithdrawal`: $0 - `cashBalance`: $0 **T+2: Customer Sells $50 of AAPL, and ACH Funds Received** - `cashAvailableForTrade`: $100 - `cashAvailableForWithdrawal`: $0 - `cashBalance`: $100 **Cash received from bank+7: No further activity since T+2** - `cashAvailableForTrade`: $100 - `cashAvailableForWithdrawal`: $100 - `cashBalance`: $100**T+0 at 3:00 PM EDT - $100 ACH Deposit** - Customer receives $100 increase to `cashAvailableForTrading` **T+0 at 9:00 PM EDT** - DriveWealth includes deposit request in request sent to bank **T+1 Prior to Market Open** - DriveWealth creates a Deposit Transaction within customers account for $100, this will also trigger a `transactions.created` event

## **Task F3** - Review and Confirm (UX/UI) Deposit Data

  • _Review the 2 ways a customer may receive their Deposit Information and decide which one to add to the platform: Simple, or Extra Data_

**SIMPLE DATA: **

  • The "List all Deposits" endpoint in the API Reference will provide you the high level information of all deposits made across a specific customer account. The following information contained in the response should be included on the screen being provided to the customer:

    • `Amount`

    • `Status.message`

    • `Status.updated`

**EXTRA DATA**

  • If you wish to provide a more enhanced experience:

    • Include the simple list above on your first screen, then allow the customer to select the specific deposit

    • Capture the `id` associated with that specific deposit and use the "Get Deposit Details" endpoint; this returns more information: status timelines, failure reasons (if applicable), and account the ACH is being debited from

  • **There are 2 options in the screen flow when you can request the customer link their bank account**

    • The last stage of the onboarding process; or

    • As soon as they are redirected onto the platform - EXAMPLE - AFTER REDIRECT TO THE PLATFORM. The Banking section brings together linking a bank account, creating a deposit, and displaying recent transactions



  • After redirect from onboarding screens, you can prompt the customer to add Banking by selecting “add account” this begins the bank authentication process using Plaid or another provider

**EXAMPLE - PLAID - ADDING AN ACCOUNT**



  • After tokenizing and linking the account, the option for a deposit is presented, the **RECOMMENDATION IS TO KEEP THIS SIMPLE**

    • Cash Amount Requested

    • Will this be a Recurring Deposit (Y/N)?

**EXAMPLE - DEPOSIT REQUEST**



**EXAMPLE - EXTRA DEPOSIT DETAILS**



### Trading while Money is en-route and Display Screens

**Impacts to Account Summary**

  • When a customer places a trade while using money in transit it's important to note that the `cashBalance` decreases by the total purchase amount. When making a request to the account summary endpoint the response would be similar to the following if a customer deposited $100 and made a $25 investment

  • Example: "cash": { "cashAvailableForTrade": 75, "cashAvailableForWithdrawal": 0, "cashBalance": -25 }

  • Since a negative `cashBalance` should not be displayed to the customer, DriveWealth recommends:

    • Whether displaying buying power or cash balance the platform should be utilizing `cashAvailableForTrade` as this balance reflects both current balance and pending balance.

    • There are instances where displaying a negative cash balance can be beneficial, such as when a deposit is returned and a customer winds up in a debit balance. In an attempt to capture new money to recoup the debit balance a Partner can display a banner to the client indicating they need to deposit more money in order to make additional investments. The logic here would be

    • if `pendingDepositAmountAvailable` == 0 & `cashBalance` > 0 display banner.

### Individual Withdrawals

**INTERNATIONAL **

  • A Partner utilizes DriveWealth’s "Create Redemptions API" to provides instruction to DriveWealth and initiate the withdrawal of customer money. DriveWealth will initiate a WIRE Transfer from our side into the customer’s bank account.

  • Non-US Partners can utilize Wire redemptions to withdraw money from their brokerage account at Drivewealth out to an external bank account or to a 3rd party money transmitter account as long as:

  1. The Primary Account Holder's name should match the Brokerage Account Holder's name

  2. There should be an Account# and SWIFT / ABA number associated with the Account

**DOMESTIC**

  • **ACH Withdrawals**

    • Individual withdrawals typically use ACH transfers out the DriveWealth Brokerage account into an external bank account.

    • The external bank account can be a 3rd party bank account or owned/operated by the Partner or any of their subsidiaries. Primary Requirements:

  1. The Primary Account Holder's name should match the Brokerage Account Holder's name.

  2. There should be an Account# and a routing number available for the external bank account.

  • "Create Redemptions API" to provides instruction to DriveWealth and initiate the withdrawal of customer money. DriveWealth will initiate an ACH push from our side into customer’s bank account.A Partner utilizes

    • _Storing Bank Account details via API makes it seamless to make withdrawals out of brokerage accounts without having to input bank details every time _

  • **WIRE Withdrawals**

  • US based Partners can also utilize Wire Redemptions to withdraw money out of DriveWealth Brokerage accounts. The process flow will be the same, however, fees associated with WIRE transfers need to be considered

  • **WITHDRAWAL FEES**

  • DriveWealth will charge the ACH or Wire fees directly to the customer or the Partner can choose to absorb full/part of the fees which will then be invoiced directly to the Partner on a monthly basis.

  • Typical ACH fees charged is $0.25/transaction (Refer your contract with DriveWealth)

  • Typical WIRE fees charged varies from $15-$35/transaction depending on the intermediary banks

##

## **Task F4** - Funding Workflow Testing and **Virtual Bank Accounts** - Review if applicable

**Funding Screen Flow (UX/UI) is complete to include testing in the Sandbox Environment:**

• Deposits • Withdrawals / Redemptions • Validate Cash balances

• Individual Funding - Virtual Bank Account Workflow has been incorporated at tested if applicable

  • Virtual Bank Account Workflow has been incorporated at tested if applicable

  • Partners can generate a virtual account that can be utilized while making deposit requests to reduce the number of transfers that wind up in suspense. Virtual accounts do not have the ability to hold customer funds, and will not operate as a full-fledged bank account. Simply put, this new product is to increase traceability of customer deposits, and reduces the time needed for the transfer to be processed through automation.

  • In order to take advantage of the virtual account structure Partners must use the [retrieve customer virtual account details](🔗) API within the platform to provide customers with the required banking details .

**Workflow**

  • Upon the first `GET` request made to the new endpoint, a virtual account will be created underneath that specific customer account, and identified by using the `id` property in the response body.

  • That newly created `bankAccountID` can be passed into the GET /bank-accounts API endpoint in order to query the bank account details again in the future.

  • When providing the banking details to the end customer make sure to provide them with the following properties from the response body:

wireDetails.bankAccountNumber wireDetails.bankRoutingNumber wireDetails.swiftCode wireDetails.bankName Full wireDetails.bankAddress wireDetails.beneficiaryName wireDetails.beneficiaryAddress

By using the above details when sending a wire transfer from their local bank, DriveWealth can then automatically tag the inbound deposit and once received move those funds into the customers brokerage account.

**FAQ**

**Q:** What are the details the user needs to provide to their bank/ 3rd party money transmitter ? **A:** The user should provide all the information received through GET /bank-accounts endpoint.

  • Wire receiving from Bank

    • The sender name should match with the DW account holder name.

  • Wire receiving from 3rd party Money Transmitter

    • The sender name should match with the DW account holder name.

    • If a partner is using any money transmitter to process the incoming wires, please notify the DriveWealth team in advance with the detailed field mapping. (i.e. Drivewealth requires account holder name in certain fields for appropriate validation.)

**Q:** What are the differences between Incoming Payment with wire type or ACH type ? **A:** When the money has been received through a 3rd party Money Transmitter, that transaction usually comes as ACH type. Due to that, it will have a seasoning period applied.

**Q:** What are the main reasons for wire rejection ? **A:** When the sender name does not match with DW account holder name, the incoming deposit will get rejected.