Omnibus Reconciliations

Overview

Linking to an external balance to calculate buying power can be enabled for DriveWealth Partners that have a store of value, and either custody or have the ability to touch customer funds. By utilizing this method customers are able to place trades instantly based upon Partner calculated buying power and settle those trades 2 business days later (T+2)

DriveWealth provides a settlements API for Partners to obtain the total customer activity over a given day, and thus reconcile their books and initiate payment for trades. The reconciliation API is a ledger that keeps track of daily transactions across a Partners universe of clients.

General workflows

At a high level, net settlement is simply the process of offsetting opposing side transactions (buy vs. sells) and moving money in a way to satisfy the total amount to settle for a given day.

Settlement date credit vs. debit

When net settling, a Partner is either going to be receiving money from DriveWealth (credit) or sending money to DriveWealth (debit). The balance to be sent is always determined on the settlement date, which is Trade Date + 2 business day. For example, if a client trades on Friday those transactions would then settle on Tuesday.

🚧

It's critical that money arrives at DriveWealth no later than 11am EST on settlement date

The total amount to settle is not set in stone until the settlement date, after the corporate action processing is completed. This generally occurs around 7am EST.

By using the reconciliation endpoint, a Partner is able to determine which direction money will be moving. The following examples explain in further detail how to make the appropriate determination.

{
    "id": "32c7e6e0-3ad7-4d6d-a5aa-8ae7356da4a4_20190326",
    "date": "2019-03-26",
    "status": "Pending",
    "statusComment": "Created from aggregator service",
    "totalAmount": 2126.75,
    "created": "2019-03-22T10:50:15.459Z",
    "updated": "2019-03-22T11:54:45.459Z",
    "updatedBy": "SYSTEM AGGREGATOR JOB"
  }

In the above example, totalAmount is a positive balance meaning that DriveWealth is to send funds on the date property value to the Partner.

{
    "id": "32c7e6e0-3ad7-4d6d-a5aa-8ae7356da4a4_20190325",
    "date": "2019-03-25",
    "status": "Pending",
    "statusComment": "Created from aggregator service",
    "totalAmount": -131246.75,
    "created": "2019-03-20T15:40:22.143Z",
    "updated": "2019-03-20T21:45:08.143Z",
    "updatedBy": "SYSTEM AGGREGATOR JOB"
  }

In the above example, the totalAmount is a negative balance meaning that the Partner is to send the funds on the date property value to DriveWealth.

For additional detail on how the totalAmount is calculated Partners can take the id from the reconciliations endpoint and pass it into the reconciliation details endpoint. The response resembles the following:

{
  "id": "2e901d48-dd17-42fe-8225-32d2ca6b633e_20190322",
  "date": "2019-03-22",
  "status": "Successful",
  "statusComment": "All good",
  "amounts": {
    "total": -1263.56,
    "purchases": -1680.07,
    "sales": 416.51,
    "dividends": 0,
    "fees": 0,
    "other": 0
  },
  "reconciliationBreakdown": {
    "JSON": "https://d3k101jzh5wilt.cloudfront.net/reconciliation_2e901d48-dd17-42fe-8225-32d2ca6b633e_20190322.json?Policy=eyJTdGF0ddiOiBbeyJSZXNvdXJjZSI6Imh0dHBzOi8vZDNrMTAxanpoNXdpbHQuY2xvdWRmcm9udC5uZXQvcmVjb25jaWxpYXRpb25fMmU5ffdasdamA17ggVl6C40gHkKsr2HLfmjTd9BevcYRPh-QDKA1J~76INZ3nfada4ROS6OUR66A"
  },
  "batchID": "5bd0f205-2fa6-4ed5-8b76-6e99b95a9886",
  "created": "2019-03-22T18:00:00.385Z",
  "updated": "2019-03-22T18:04:52.031Z",
  "updatedBy": "97209cc8-8374-4ede-8842-53629390cd23"
}

Understanding reconciliation details

When getting additional details for a reconciliation there are a few properties that a Partner should take note of.

• total - indicates the amount of the settlement
• purchases - total notional value of all buy orders
• sales - total notional value of all sell orders
• dividends - total notional value of all dividends paid out on settlement date
• fees - Schedule B fee's such as ACAT transfer and similar
• other - total notional value of all other fees such as the SEC and TAF fees
• date - the settlement date
• reconciliationBreakdown.JSON - a full JSON response of all transactions that make up the settlement broken down by account

The reconciliationBreakdown.JSON can be used to reconcile internal systems and get a full understanding of precisely which transactions occurred on a given trade date. The breakdown also includes corporate action activity meaning that Partners can also find transactions from settlement date included. The link has a 15 minute TTL, and a new request must be made if the original link expires in order to get the breakdown details.

Transactions within the breakdown follow the standard DriveWealth transaction types (finTranTypeID in 200 response) and can be exampled such as:

[
    {
        "accountID": "7742f65b-13e7-457d-8010-79677d284c4f.1547749204654",
        "accountNo": "DWDF000075",
        "userID": "7742f65b-13e7-457d-8010-79677d284c4f",
        "amount": -1264.40,
        "partnerID": "2e901d48-dd17-42fe-8225-32d2ca6b633e",
        "transactions": [
            {
                "amount": 196.06,
                "finTranCode": "SSAL",
                "finTranID": "GC.4e90e420-eb54-4ebb-b3e4-9142208cde4f",
                "created": "2019-03-22T00:16:07.498Z"
            },
            {
                "amount": 25.98,
                "finTranCode": "SSAL",
                "finTranID": "GC.282b51a7-722e-4e60-8bdd-8d2108f301ec",
                "created": "2019-03-22T00:15:59.295Z"
            },
            {
                "amount": -60.62,
                "finTranCode": "SPUR",
                "finTranID": "GC.f3f9ee22-e2b0-4da5-a043-fb7df504104d",
                "created": "2019-03-22T00:15:39.616Z"
            },
            {
                "amount": -1229.76,
                "finTranCode": "SPUR",
                "finTranID": "GC.cb9ae6ae-8fc0-475f-9721-94c4fdf7be2d",
                "created": "2019-03-22T00:15:15.377Z"
            },
            {
                "amount": -196.06,
                "finTranCode": "SPUR",
                "finTranID": "GC.1ec1b8e6-78a7-469b-8fb7-8d03557c95a1",
                "created": "2019-03-22T00:12:51.187Z"
            }
        ]
    },
    {
        "accountID": "9837436c-6337-4a7c-8ceb-a2345c2d8495.1527255625766",
        "accountNo": "DWBQ000059",
        "userID": "9837436c-6337-4a7c-8ceb-a2345c2d8495",
        "amount": 0.84,
        "partnerID": "2e901d48-dd17-42fe-8225-32d2ca6b633e",
        "transactions": [
            {
                "amount": 194.47,
                "finTranCode": "SSAL",
                "finTranID": "GC.fd98db51-6fa1-4ad0-a18a-4090016b268a",
                "created": "2019-03-21T16:07:48.116Z"
            },
            {
                "amount": -193.63,
                "finTranCode": "SPUR",
                "finTranID": "GC.beec65a4-5365-4319-b450-fbd8eee2060e",
                "created": "2019-03-21T16:07:04.913Z"
            }
        ]
    }
]

When to use the reconciliation API

DriveWealth recommends that Partners utilize the reconciliations endpoint a few times through the lifecycles of a settlement. Below is a table that examples when the appropriate time to make those requests would be.

📘

The reconciliation API details have been built to update every 15 minutes throughout the trading day.

Determining when to debit / credit client wallet

Debiting (buy orders)

In the net trade settlement structure Partners are responsible for calculating client buying power, and thus must ensure the client does not overspend the total amount available in their wallet. Explained in the below section Rules of engagement Partners should utilize notional based order types, or other types that allow for the calculation of final amount owed prior to execution.

Prior to submitting any buy order the Partner should perform a real-time check of the available balance in the customer wallet, this becomes their buying power. Upon placing an order the Partner should not allow a customer to submit an order where buying power < amountCash (Create Order). If buying power is less than the amountCash the Partner should immediately reject this order and not attempt to send to DriveWealth.

Throughout the trading day, and overnight if allowing for pending orders, Partners should be using the events API to debit a customer wallet in real-time the moment an order is accepted. By consuming order events, upon the successful acceptance of an order the following event is sent to the queue:

{
    "id": "event_dcadb7df-a677-4ba6-8a06-15005d4a491d",
    "type": "orders.created",
    "timestamp": "2021-03-28T22:40:03.260922189Z",
    "payload": {
        "id": "GC.f7590a52-75c7-4f3a-92c7-6b03e02dc44f",
        "orderNo": "GCWS000039",
        "type": "MARKET",
        "side": "BUY",
        "status": "NEW",
        "symbol": "GE",
        "averagePrice": 0,
        "cumulativeQuantity": 0,
        "quantity": 0.46728971,
        "amountCash": 3,
        "fees": 0,
        "orderExpires": "2019-03-29T20:00:00.000Z",
        "createdBy": "b25f0d36-b4e4-41f8-b3d9-9249e46402cd",
        "userID": "b25f0d36-b4e4-41f8-b3d9-9249e46402cd",
        "accountID": "b25f0d36-b4e4-41f8-b3d9-9249e46402cd.1403540676095",
        "accountNo": "DWZR000001",
        "created": "2019-03-28T22:40:03.240Z"
        "preventQueuing": false
    }
}

Please take note of the payload.amountCash property as this will determine the total amount of money that has to be debited or set aside from the customers wallet.

❗️

Its possible that the final amount after execution is less than the amountCash value, but will never be more.

Due to the above call out, in addition to the orders.created event DriveWealth recommends listening to orders.completed events. The orders.completed event contains the final payload.amountCash that has to be held aside for settlement. Please take note of other order workflow and edge cases to act accordingly to the status received.

Crediting (sell orders)

Partners have the option to immediately credit back funds to the customer after a sell order has been successfully FILLED. Although generally speaking the amount is to always be returned on settlement date there could be a rare event whereby the money does not settle and is not included in settlement date figures. This then introduces risk to the Partner, however minuscule that may be.

Alternatively, Partners can wait until settlement date to return the funds back to the customers wallet that were a result of a sell. This reduces risk even further and does not require the Partner to "front" any cash to the customers wallet.

Throughout the trading day, and overnight if allowing for pending orders, Partners should be using the events API to determine the final amount that will be credited back to the customers wallet. By consuming order events, upon the successful acceptance of an order the following event is sent to the queue:

{
    "id": "event_281bdd42-0acf-4b72-a7ca-e6f472c24bd7",
    "type": "orders.updated",
    "timestamp": "2020-03-03T21:00:29.660071586Z",
    "payload": {
        "id": "HC.8b05ffea-e152-49ef-b6cd-d7c05ce24c79",
        "orderNo": "HCDA001512",
        "type": "MARKET",
        "side": "SELL",
        "status": "FILLED",
        "symbol": "MSFT",
        "averagePrice": 164.71,
        "totalOrderAmount": 329.42,
        "cumulativeQuantity": 2,
        "quantity": 2.4,
        "fees": 0,
        "orderExpires": "2019-03-29T20:00:00.000Z",
        "createdBy": "b25f0d36-b4e4-41f8-b3d9-9249e46402cd",
        "userID": "b25f0d36-b4e4-41f8-b3d9-9249e46402cd",
        "accountID": "b25f0d36-b4e4-41f8-b3d9-9249e46402cd.1403540676095",
        "accountNo": "DWZR000001",
        "created": "2019-03-28T22:40:03.240Z"
        "preventQueuing": false
    }
}

Please take note that for sell side orders Partners want to use the payload.totalOrderAmount property as not all sell side orders are submitted in amountCash quantities. There may also be fees associated with orders, that are described in the SEC / TAF Fees section.

Clients may also receive dividends and other corporate action activities that result in a cash balance being applied to the account on settlement date. These transaction types can immediately be applied to a clients wallet balance because they settle same day and are always included in same day settlement balance. In the event of a dividend a Partner would receive the following event message:

{
  "id": "event_a1acdf71-17d2-4e38-81ce-871a86374b40",
  "type": "transactions.created",
  "timestamp": "2019-04-05T19:25:14.711707573Z",
  "payload": {
    "accountID": "b25f0d36-b4e4-41f8-b3d9-9249e46402cd.1491330741850",
    "accountNo": "DWEF000010",
    "userID": "b25f0d36-b4e4-41f8-b3d9-9249e46402cd",
    "transaction": {
      "accountAmount": 2.29,
      "accountBalance": 128195.27,
      "comment": "BPY dividend, $0.3043/share",
      "finTranID": "GF.861e931d-e7aa-47c8-b87a-b1e55acf3862",
      "wlpFinTranTypeID": "e8ff5103-ad40-4ed9-b2ee-fd96826bf935",
      "finTranTypeID": "DIV",
      "feeSec": 0,
      "feeTaf": 0,
      "feeBase": 0,
      "feeXtraShares": 0,
      "feeExchange": 0,
      "instrument": {
        "id": "476b40ee-3ff9-46af-85af-fec572d13d23",
        "symbol": "BPY",
        "name": "Brookfield Property Partners L.P."
      },
      "dividend": {
        "type": "CASH",
        "amountPerShare": 0.3043,
        "taxCode": "NON_TAXABLE"
      }
    }
  }
}

Where payload.transaction.accountAmount indicates the cash value that resulted as part of the dividend transaction.

❗️

For Non-US tax paying individuals, an additional transactions.created message is sent for the processing of the dividend withholding amount. In these instances only the Net amount should be applied to the clients wallet

Transaction types to ignore

When the reconciliation status is updated to SUCCESSFUL all underlying transactions for that given trade date are reconciled. This produces both deposit (CSR) and withdrawal (CSD) transactions.created events which MUST be ignored.

The reason behind this is that by consuming orders.* events all transactions that result in a movement of money are accounted for, and by consuming the deposit and withdrawal transactions the client would have duplicated entries. For example:

Handling dividends and corporate actions

There are effectively two ways to handle the receiving of funds that were a result of a dividend or other corporate action payout. It's important to note that all corporate actions, including dividends, are paid out same day meaning they are included in the settlement date balances.

For Partners that are able to settle with DriveWealth same day, the total amount of dividends and other corporate action funds can be netted against the total amount owed or included in the total amount sent.

For Partners that are NOT able to settle same day with DriveWealth, the only option is to have DriveWealth send an individual wire transfer back to the Partner for the total amount of the dividend and other corporate action payout. This occurs regardless of a net settlement date credit or debit.

Rules of engagement

Ability to debit a wallet

In order to successfully link to an external balance the first step is identifying whether or not the Partner can debit spendable funds in the clients wallet immediately following an executed buy order. This is critical to ensure that the client has enough money in their wallet in order to satisfy the total amount needed to settle the buy order 2 business days later.

Order types

An important factor for using an external balance for trading is that Partners only allow their customers to place orders in which the final executed amount is known prior to execution. This includes order types such as:

• Notional based market orders
• Market-if-touched orders
• GTC or GTD limit orders

Since these order types allow a Partner to quantify the approximate executed dollar amount, they are then able to more accurately determine if the customer has enough buying power in their wallet to settle the buy order. For example, by submitting a $50 notional order to purchase BRK.A DriveWealth's fractional share technology ensures execution up to $50 but never more.

🚧

The only time in which this logic changes is on sell orders. For customers that are expecting to liquidate an entire position, the Partner is required to submit an order with the exact quantity of shares the customer holds. Submitting a notional based order for a full liquidation will result in remaining fractional shares in the clients account