DocumentationImplementation Docs
API StatusLogin

Step 7 - Customer Reporting

Phase 4 - Reporting

Suggest Edits

API Reference

Minimum Required Endpoints

URL Reference

Customer Reporting Portal

SQS Reference

Task R1 Build Customer Reporting Screens

  • Build the Portfolio Section of the Platform to include Data Retrieval, Validation, and Testing

  • SubTask 1- Customer's brokerage account number is visible and can be located within their portfolio on the platform

  • SubTask 2- Balance Check (customer) for Accuracy- Cash, Total Equity, (if Trade Settlement; Debit is not displayed)

  • SubTask 3- Transaction History is accessible and reflects all transactions types (ex: orders, deposits, withdrawals, dividends, stock splits (corporate actions) etc.)

  • SubTask 4- (If necessary) - Validate the calculation being used to display performance figures

Account Summary

  • When building the portfolio section of the platform you will use the "GET Account Summary" Request

  • The account summary provides the partner a real time look into a customer’s cash balances, security positions, recent transactions, and pending orders. In addition to the account summary orders and recent transactions have their own specific API endpoint that should be used to display these attributes to the customer.

  • The Summary Endpoint should be used when the customer is on the platform and makes requests; it should not be called continuously

  • The values displayed in the Response will be current as of the name/value pair: updatedWhen

  • The customer can query an order:

    • In the orders object, extract orders.orderID to allow the "GET Order Status Request" to relay back to the orders section

  • The account summary allows the partner to filter information provided to the customer

Cash Balances

  • Buying Power
  • Available for Withdrawal
  • Cash Settlement (Dates and Amounts)

Security Positions

  • Ticker and DW internal Instrument Identifier
  • DW instrumentID streamlines the API workflow for the partner to retrieve fundamental data (52week High/Low, div yield, etc.), description of the security, and security logo
    • Open Quantity (Number of shares owned)
    • Cost Basis and Market Value
    • Prior Close
    • Average Price (Dollar Cost Average price)
    • Unrealized P/L (since inception of position), Unrealized Day P/L Percent, and Unrealized Day P/L

All Pending Orders (Includes GTC)

  • Timestamp of Creation
    • Important for GTC orders
  • Symbol
  • Order Identifier and Order Number
    • Able to use either of these identifiers to retrieve order specific information
  • Key Identifiers
    • Order Status (NEW, PARTIAL_FILL)
    • Symbol
    • Executed Price (Only for partial fills)
    • Order Type (Market, Limit, etc…)
    • Quantity
      • Cumulative amount executed
      • Total Requested
    • Side

Recently Executed Transactions

  • Order Identifier and Order Number
    • Able to use either of these identifiers to retrieve order specific information
  • Key Identifiers
    • Order Status - Completed or Rejected
    • Symbol
    • Executed Price
    • Order Type (Market, Limit, etc..)
    • Order Quantity
      • Cumulative amount executed
      • Total Requested
    • Side

Account Performance

  • DriveWealth provides Partners the ability to generate, on a daily basis, customer performance. The API provides the following information:

*Realized P/L: The actual (realized) profit or loss
Unrealized Day P/L: The current daily profit or loss on all open position
Cumulative Realized P/L: The aggregate realized P/L from inception of the account, each day adds to previous days

  • In addition to the above profit and loss figures, DriveWealth provides, again on a daily basis:

Equity: The total invested equity (excluding cash)
Cash: The total cash balance (settled and unsettled)
Deposits: The total amount of deposits calculated from 4pm ET of previous day until current time
Withdrawals: The total amount of withdrawals calculated from 4pm ET of previous day until current time
Fees: Total amount of fees calculated from 4pm ET of previous day until current time

Important Portfolio Calculations

  • Total Value of A Customer Portfolio = cashBalance + equityValue

  • Total unrealized P/L for a Given Day at Time of Request = Loop and SUM (equityPositions.unrealizedDayPL)

  • Total unrealized P/L since Account Inception = Loop and SUM (equityPositions.unrealizedPL)

  • The account summary endpoint provides a real-time snapshot of:

Current Positions
- Ticker and DriveWealth internal identifier (symbol, id)
- Total Number of Shares Owned (openQty)
- Cost Basis of the Security (costBasis)
- Total Value of Position (marketValue)
- Average Price of Position (averagePrice)
- Unrealized Profit or Loss since Inception (unrealizedPL, unrealizedDayPL)

Cash Balances
- Buying Power (cashAvailableForTrade)
- Total for Withdrawal (cashAvailableForWithdrawal)
- Total Unsettled + Settled Cash (cashBalance)
- Cash Settlement Amounts and Dates (cashSettlement array)

Pending Orders
- When Order was Created (timestamp)
- Symbol (symbol)
- Order Identifier / Number (orderID, orderNo)

Key Identifiers of Pending Orders
- Status of Order (status)
- Executed Price for Partially Executed
- Type of the Order (orderType)
- Quantity (cumulativeQuantity, quantity)
- Side of the order (side)

Task R2 Incorporate Customer Statements

  • 3 API endpoints comprise the Reporting Section - Account Statements, Trade Confirmations, Tax Documents *- the retrieval methodology works the same for all statements

  • It is US regulatory requirement for all investors to receive the following statements; they must be made available to clients through your platform

  • Recommendation: Partners include all 3 within a Reports Center in their platform (simplifying document generation)

Customer Notifications

  • DriveWealth does not send out direct notifications to customers when these official documents are made available
    • Partners can take advantage of the Amazon SQS Statement events; they can then be consumed and published back out through the Partner's platform in anyway seen fit
    • Generally when sending a notification to a customer that their document has been made available, the physical document is not included in that notification to protect customer PII. Instead, a link to the reports section within the platform is given for customers to access

Trade Confirmation

  • Is a required notification of a securities transaction. These are made available T+1. The customer must receive this document prior to the completion of the settlement cycle and details:
    • Name and symbol of the security
    • Number of securities purchased or sold
    • Price of the security
    • Amount owed or due
    • DriveWealth’s execution capacity (Agent / Principal)
    • Trade date and settlement for the transaction
    • A backer highlighting the transaction terms

Month-End Account Statement

  • The month-end account statement details customer activity during the month, and are uploaded to customer accounts the first weekend of every month; no later than the 10th of the month
    • Deposit/withdrawals/dividends/Corporate Actions and other activity
    • Asset value between time periods
    • Cash sweep activity
    • A backer highlighting account statement terms

Tax Reporting

  • DriveWealth does not provide personal tax services for filing individuals personal tax returns. Any applicable tax planning and fillings pertaining to realized gain or loss, should be handled by the customer or their respective Tax Professional. Taxes will be withheld from dividends, capital distributions, and any further taxable events subject to US Tax Treaty Rates for W-8BEN customers. Backup withholding (“TEFRA” tax) may be applied in the event of an IRS B-Notice for any Name/TIN mismatches for customer accounts. DriveWealth will not provide tax advice of any kind. Any tax advice must be obtained from a Tax Professional. DriveWealth will supply amended tax documents in the event of reportable changes, as well as support any questions as to the generation of the document(s).

  • During the customer on boarding process, DriveWealth utilizes the information sent through the "create user" request to generate either a W9, or W-8BEN tax form. As part of the DriveWealth customer agreement that the customer acknowledges under penalty of perjury that the information that they provided for W8 or W9 purposes is accurate

  • Upon successful account creation DriveWealth will generate a W9 (US) or W-8BEN (non-US) tax form.Tax Certifications (W9 or W-8) are available for each established account. The form can be retrieved with a query of the API[List All Physical Documents for a User]

Domiciled or Citizen of the US, or US Resident Alien

  • W9
  • 1099-Consolidated (1099-B, DIV, INT, MISC)
  • 1099-R and 5498 (For IRA accounts)

Non-US domiciled or citizen, non - US Resident Alien

  • W-8BEN - The IRS requires that a customer updates their W-8BEN every 3 years, after the date of account creation. To facilitate the change in information, DriveWealth makes available two methods:
    • A hosted website: https://client.drivewealth.com/login
    • User Update API Call
    • The primary points of information that need to be either confirmed or changed include:
      • Full Legal Name
      • Address
      • Tax Identification Number
      • 1042-S

IRA Tax Processing

  • Both ROTH and TRADITIONAL Individual Retirement Accounts (IRA's) receive a 1099-R and 5498 during tax season that covers:
  • Distributions (1099-R)
  • Contributions (5498)
  • These forms are not made available to the customer electronically, when available they are mailed to the address provided by the customer during the onboarding process

Retrieving Documents

  • When a Customer (end client) wants to retrieve a tax document: The partner can use the following API to list all Tax documents:
  • Pass in the accountID and date range; this will display all tax documents within the given range (tax docs will be dated dec 31) API returns a list of fields
  • End customer decides which documents they want to view
  • Partner makes a request with the proper fileID and is given a secureURL
  • Partner serves up that URL for the end customer
  • The tax-form-created Amazon SQS Event eliminates the need for steps 1-3 as it pushes the fileIDs to the Partner. Partners can store the IDs in a DB to have them ready for steps 4 and 5

It's important to note that Not all customer accounts receive an end of year tax form. To understand if a customer qualifies for a tax form generation they must meet the following threshold by form type:

  • Form 1099-R
    • Form is used to report distributions from IRAs or if there was withholding on the account.
  • Form 1099-Consolidated (1099-B, 1099-DIV, 1099-INT, and 1099-MISC)
    • Sub form 1099-B - used to report proceeds from broker and barter exchange transactions if there are sales or redemptions of $0.01 or more, or federal withholding on the sales proceeds.
    • Sub form 1099-DIV - used to report dividends and distributions of $10 or more (such as dividends, capital gains, or nontaxable distributions that were paid in stock or cash), $600 or more for liquidation distributions, or federal withholding taxes applied to the dividends.
    • Sub form 1099-INT - used to report interest income (including tax-exempt interest) of $10 or more in client accounts or federal withholding taxes applied to the interest.
    • Sub form 1099-MISC - used to report royalties and substitute dividends or interest of $10 or more in client accounts or federal withholding taxes applied to the income. Other income of $600 or more.
  • Form 1042-S (nonresident aliens and non-US entities) - used to report certain US sourced income received by nonresident aliens or non-US entities and federal tax withholding. It does not include account trading activity. US sourced/reportable payment generally includes dividends and interest, and income subject to withholding.
  • Form 5498 (IRA contributions) - used to report IRA contribution information if there are individual or rollover contributions to Traditional or Roth IRA accounts. It’s not required for filing taxes.

Customer Reporting Portal

  • https://client.drivewealth.com/login

  • DriveWealth additionally offers a Customer Reporting Portal that can be accessed directly through a DriveWealth hosted webpage. If a customer were to close their account halfway through the year they will still be able to retrieve their documents

  • The Customer Reporting Portal will serve the following documents to customers

    • Trade Confirmations
    • Month-End Account Statements
    • End of Year Tax Forms - Customers can also update their tax form information through the portal

Example Statement: Partner Brand can replace DriveWealth Brand

  • The Partner can brand these documents with their logo, and support contact detail if desired

End of Year Processing

  • All tax forms are calculated based upon the US tax season which generally includes income received between January 1st, and December 31st. No exceptions are made to this Internal Revenue Service (IRS) procedure, and DriveWealth will not calculate returns based upon any other jurisdictional timeframe.
    Generally before the end of February, all tax forms are submitted by DriveWealth to the IRS for processing and acceptance. The day in which end of year forms (highlighted below) are made available to end customers varies each year:

  • 1099-R forms are made available on or by January 31st

  • 1099-Consolidated forms are made available on or by February 15th

  • 1042-S forms are made available on or by March 15th

  • 5498 forms are made available on or by May 31st

  • Dates above reflect the IRS tax form issue by date and if that date falls on a Saturday, Sunday, or legal U.S. holiday, the IRS deadline is moved to the next business day.

CAT Reporting

Account Statement Retrieval 2 API requests

  • Obtain the fileKey

FILE KEY INSTRUCTIONS

  • Account Statements are typically available the first weekend (monthly), a date range needs to be provided to make a successful request

  • Example: customer selects July 2020 to September 2020

  • The following goes in the header:

  • “from” : “2020-07-01T05:00:00.000Z”,

  • “to” : “2020-09-01T05:00:00.000Z”

SAMPLE JSON RESPONSE: 

{
  “displayName”: “Jul 28, 2020 Statement”,
  “fileKey”: “2020042802"
},{
  “displayName”: “Aug 31, 2020 Statement”,
  “fileKey”: “2020053102"
}
  • Generate the Document
    • Take the fileKey for viewing the customer document and pass into: "GET Statement File"
    • The response will contain the field url which links the PDF version of the account statement; this is a temporary URL and will expire after 5 minutes
    • The above methodology works exactly the same for trade confirmations and tax forms
    • The document creation will generate an event notification in your SQS queue

Trade Confirmations

  • Transaction data provides your customer a view into all past modifications to either their cash balance or share balances:

    • Deposits
    • Withdrawals
    • Orders
    • Corporate actions such as dividends
    • Fees that are charged to the account.

  • You can filter through a user provided time range and return all individual transactions contained between the dates; each transaction can be attributed to its own specific type, for example:

    • CSR == deposit
    • SPUR == Purchase (Buy order)

  • While the API does not specifically allow you to filter by the finTranTypeID you can implement a front-end filter to allow the customer to view only certain types of transactions (see Transaction Type Ids)

  • For a successful response provide accountID and time range (from, to)

  • Key points of information that need to be displayed to the customer - EXAMPLE - a typical transaction view within the platform will contain the following details:

    -Timestamp of the transaction
    -The type of transaction
    -The dollar amount of the transaction
    -The final balance after the transaction occurred**

  • For Orders and Corporate Actions transactions:

    • Comment
    • Fill quantities
    • Fee’s (if applicable)
    • Dividend object
    • MergerAcquisition object

UX/UI Reporting Screens

  • Example - The following screenshots show a mocked up version of an application that can be used to gain ideas as to how you want this information to be displayed

  • The following screenshot has been built by using the account summary to obtain customers' current balance invested, current holdings, and the profit or loss of those positions

EXAMPLE - SUMMARY PAGE

  • EXAMPLE - If a customer selects a specific position, such as Starbucks you can redirect them to the stock card page:

  • Primary information provided here includes:

    • Total value of the position
    • Shares owned
    • Percent of profit and loss
    • You can give the customer the ability to close out of their position on this screen as well

EXAMPLE - STOCK CARD FOR SBUX

  • Reporting center on the platform - Recommendation - KEEP SIMPLE - the main purpose of this page is to give the customer the option of which report to download

EXAMPLE REPORTING SCREENS CONTINUED

  • After selecting a document type you can display all available documents since inception, or, give the customer the ability to select a date range

  • When showing transactions you can choose to show everything over a customer specified time frame, or filter the results for specific transaction types

Task R3 Final Testing - SQS Events

  • Partner has confirmed receipt of all relevant Amazon SQS events in UAT and the queue is functioning as expected to include all Corporate Action Events

Task R4 Final Testing - Demo Accounts

  • Test all requirements in accounts suited for final UAT demoing to the DW team(user creation, account creation, funding, order testing, ability to download 3 primary Customer Statements / DW Recommendation: Build Historical Data in the UAT environment in at least two accounts to better test market data, orders, and performance presentation

Updated 8 months ago