Invest Now Developer's Guide

Introduction

While the primary goal of the Invest Now investment process is to provide an easy way for issuers with little to no technical expertise to get their offering accepting investments via the web as quickly as possible, it's also become quite popular with developers for other reasons.

The first thing to understand about Invest Now is that the process makes use of FundAmerica's APIs with only minor modifications. What this means is that all the objects involved such as Offerings, Investments and Investor Entities are just like anything you'd be using if building your own system. They're also completely accessible via the API.

This gives developers the option to either use Invest Now as a stepping stone to hurry development while they build a custom integration or forego building their own investment process entirely.

Looking for something more?

Most of the functionality below has been added at the request of developers. We're constantly looking to make integration more flexible and better adaptable to your platforms. If you're considering developing your own investment process because Invest Now doesn't quite work the way you need it to, before getting out your flow charts and plan a sprint or two, contact our development team at tech-support@fundamerica.com and request a feature.

Invest Now 2.0

With the release of Invest Now 2.0, we've improved compatability with dynamic frameworks, such as AngularJS. We've also removed the URL manipulation that was used for knowing what current "step" the modal is on. This should help prevent any conflicts that may arise if your website was also using AngularJS or even TurboLinks for Ruby on Rails.

Styles

While most of the underlying markup and styling for Invest Now has not changed with the release of 2.0, there is one ID that has been removed from the modal. Previously the modal was wrapped in a div with an ID of "inModal". Any custom CSS you have will need to be changed from that to read #fa-invest-now-modal.

Referrers

You can now set a referrer for the investment in one of two ways. You can either set data-fa-invest-now-referrer as an attribute on the button or as a query string in the browser url with ?_fa_referrer=your_referrer.

So using the first option, your button would look like:

<input type="button" class="btn btn-lg " value="INVEST NOW!" data-fa-invest-now="xxx:xxx" data-fa-invest-now-referrer="your_referrer" />

AngularJS

If you're using the AngularJS framework then you'll need to do a little extra work to make Invest Now work on your website. You'll need to manually bootstrap your application -after- the point where you've included our Invest Now script tag. You'll generally want to include this just before the closing </body> tag of your page.

<script src="http://apps.fundamerica.com/cors/js/invest_now.min.js" id="fa-invest-now-launcher"></script>

<script>
  angular.element(document).ready(function() {
    angular.bootstrap(document.body, ['your-application-name']);
  });
</script>

Binding Invest Now Buttons

In the case of using a dynamic website that uses AJAX to load pages without doing a full page reload, you may need to create and dispatch the fa.investnow.bindButtons event in cases where the Invest Now script is already loaded but you dynamically load your Invest Now button on to the page later.

You can read more and see example markup at the bottom of the page.

Additional Webhook Functionality

The standard functionality of webhooks is to fire when certain objects are updated. The idea behind this being that when building an investment platform, the originating system is creating a new investor or investment therefore doesn't need a webhook telling the system a new object has been created. With Invest Now, because it creates a number of objects without using any host system, it makes sense to inform the host system that new objects have been created for the sake of syncing data.

Webhooks can be configured so that investments and entities will fire both when being created and updated. This can be done by going to API Docs & Key and setting Send on Create? to true.

Note: There is no reason to set webhooks to fire on create unless using Invest Now. Save all of our servers the unnecessary traffic and don't enable this feature if you don't need it.

Arbitrary Investment Data

A common use case when creating an investment is needing to track who the investment information (both the investment itself and the associatied investor) should be associated with on your system in the event you have your own authentication system. Investments have a data attribute which is just a collection of JSON data. By default, the URL where the investment is made is collected, however, any valid JSON data can be injected into this field.

This means that when a webhook fires informing your system that a new investment has been made, you can read back the data in data to determine who the investment should be associated with.

The simplest way to accomplish this is to attach an data-fa-invest-now-data attribute to your Invest Now button and set the value to valid JSON, like so:

<input type="button" class="btn btn-lg " value="INVEST NOW!" data-fa-invest-now="xxx:xxx" data-fa-invest-now-data='{"name":"John Johnson","id":"123ACB","ref":"Some Place"}' />

This data will be carried through the Invest Now investment process and sent to the Investment API when the client completes the process. It can be retrieved by using the Investment API. Any JSON included in the attribute will appear in the client_data key of the data object on the investment like so:

{
 "object":"investment",
 "id":"TdgCeoPCTruVp-D7zpIBpQ",
 "data":{
    "client_data":{
       "name":"John Johnson",
       "id":"123ACB",
       "ref":"Some Place"
    },
    "url":"http://www.example.com/invest_now/#/step-1"
  }
}

Additionally, this can be populated using the fa.investnow.update custom event listener.

JavaScript Events

The investment process provides four custom events that fire at various points during the investment process:

fa.investnow.open will fire when a user clicks on the Invest Now button to open the modal/popup.

fa.investnow.ready fires after the Invest Now script has loaded. If you want to assign some data before the modal has even been opened, this is what you would use.

fa.investnow.close fires whenever the investment modal is closed. There is currently no extra data being passed back on this event.

fa.investnow.success fires when the final step completes and an investment is created. This event will return a field named investment_id containing the ID of the investment object which can be used with the Investment API. Here's an example of capturing a new investment's ID:

document.addEventListener('fa.investnow.success', function(e){
  var InvestorInvestmentID = e.investment_id;
});

JavaScript Event Listeners

In addition to firing events, the Invest Now process also listens for events. These can be used to send data to the investment process.

Triggering fa.investnow.update along with valid JSON can be used to populate Arbitrary Investment Data.

First, create the event:

var updateEvent = document.createEvent('Event');
updateEvent.initEvent('fa.investnow.update', true, false);
updateEvent.detail = {
  "name":  "John Johnson",
  "id" : "123ACB",
  "ref" : "Some Place"
};

Then dispatch it:

document.body.dispatchEvent(updateEvent);

This gives you more control over what data you'd like to send in to the Invest Now process, and when, over using data-fa-invest-now-data.

Triggering fa.investnow.clearData will clear any data set by update (i.e. client_data is set to null).

Triggering fa.investnow.getData will return the current value of client_data.

Autofilling Investor Data

There are many instances where your system may have some or all of the investor data as a matter of a sign up or registration process. You may wish to autofill the investor fields with this data to prevent your investor for having to re-enter this data every time. A common use case is to store all data except the investor's TIN and then populate the form, having the investor simply confirm their TIN.

This is made possible by triggering the fa.investnow.autofill event in much the same way fa.investnow.update can be triggered. For example:

var autofillEvent = document.createEvent('Event');
autofillEvent.initEvent('fa.investnow.autofill', true, false);
autofillEvent.investor = {
      "type": 'company',
      "name": 'Johnson, Johnson, Johnson & Johnson',
      "tax_id_number": '999999999',
      "street_address_1": '800 Third Avenue',
      "street_address_2": '22nd Floor',
      "city": 'New York',
      "region": 'NY',
      "postal_code": '10022',
      "email": 'john@johnson.com',
      "phone": '202.582.9600',
      "contact_name": 'John Johnson',
      "region_formed_in": 'NY',
      "amount": '10000',
      "payment_method": 'ach',
      "financial_adviser_name": 'Jimmy Johnson'
    };
autofillEvent.associated_person = {
  "name": 'John Johnson',
  "tax_id_number": '0000000000',
  "date_of_birth": '01/01/1980',
  "street_address_1": '800 Third Avenue',
  "street_address_2": '22nd Floor',
  "city": 'New York',
  "region": 'NY',
  "postal_code": '10022',
  "email": 'john@johnson.com',
  "phone": '202.582.9600'
};

Then dispatch the fa.investnow.autofill event when the Invest Now script is ready:

document.addEventListener('fa.investnow.ready', function(e){
  document.body.dispatchEvent(autofillEvent);
});

or when the modal is opened:

document.addEventListener('fa.investnow.open', function(e){
  document.body.dispatchEvent(autofillEvent);
});

Most of the fields should look familiar if you've looked at the Investments and Investor Entities APIs.

The investor attribute can take all fields that an entity would take. Additionally, it takes a few fields from investments:

  • amount
  • financial_adviser_name
  • payment_method

Remember, the attributes differ slightly between a person and entites with a different type.

The associated_person attribute is required when the investor's type is company or custodial. Like investor it takes the same entity attributes with the exception of type. The associated person will always be a person.

Finally, joint accounts are also supported as in this example:

var autofillEvent = document.createEvent('Event');
autofillEvent.initEvent('fa.investnow.autofill', true, false);
autofillEvent.investor = {
      "type": 'person',
      "name": 'John Johnson',
      "tax_id_number": '0000000000',
      "date_of_birth": '01/01/1980',
      "street_address_1": '800 Third Avenue',
      "street_address_2": '22nd Floor',
      "city": 'New York',
      "region": 'NY',
      "postal_code": '10022',
      "email": 'john@johnson.com',
      "phone": '202.582.9600'
      "amount": '10000',
      "payment_method": 'ach',
      "financial_adviser_name": 'Jimmy Johnson',
      "joint_account": 'true',
      "joint_type": 'jtwros',
      "other_entities": [
        {
          "name": 'Jane Johnson',
          "tax_id_number": '111111111',
          "date_of_birth": '02/01/1980',
          "street_address_1": '800 Third Avenue',
          "street_address_2": '22nd Floor',
          "city": 'New York',
          "region": 'NY',
          "postal_code": '10022',
          "email": 'jane@johnson.com',
          "phone": '202.582.9600'
        }
      ]
    };

Joint accounts can only consist of people.

joint_account: This must be set to true if using a joint account.
joint_type: This accepts either jtwros or jtic. Consult your lawyer for details.
other_entities is an array of additional people that are part of the joint account. In general, this is either a married couple or a parent and child, but it is not limited to two people.

Note: This event does nothing once the investor has entered data on their own.

Clearing Investor Data

In some cases you may wish to clear the data an investor has entered before they have completed an investment. So long as they're on a page with our Invest Now script loaded and at the very least the fa.investnow.ready event has occurred, then the fa.investnow.clear event listener will be prepared to clear their data and send the form back to step 1.

Here's an example of how to create your fa.investnow.clear event and then trigger a clear when the Invest Now script is ready:

var clearEvent = document.createEvent('Event');
clearEvent.initEvent('fa.investnow.clear', true, false);

document.addEventListener('fa.investnow.ready', function(e){
  document.body.dispatchEvent(clearEvent);
});

Note: It's important to keep in mind when you might attempt to clear an investor's data because Invest Now is designed to allow someone to begin filling out the forms, but stop halfway through, and return later.

Binding Buttons

If you dynamically loaded a button on to the page when the Invest Now script is already loaded, you can create and dispatch the fa.investnow.bindButtons event to bind these buttons to open the Invest Now modal.

var bindButtonsEvent = document.createEvent('Event');
bindButtonsEvent.initEvent('fa.investnow.clear', true, false);

// Then dispatch this event from some kind
// of callback after your content is loaded
document.body.dispatchEvent(bindButtonsEvent);

Note: If you also dynamically load the Invest Now script, then triggering fa.investnow.bindButtons will not be needed.