To launch NinjaFetch from your web application, include ninjafetch.js in the HTML and call NinjaFetchWidget.mount() from JavaScript.

1. Import ninjafetch.js

Add this line to your HTML code.

<script type='text/javascript'
src="https://ninjafetch.com/v1/ninjafetch.js"></script>

2. Add a container

You can apply custom styles to the container element to change the position of the widget.

<div id="widgetContainer"/>

3. Add JavaScript code

<script>
    function launch() {
        //Build consumer data
        var consumerData = {
            access_token: 'eyJhbGciOiJIUzI1NiJ9.eyJjbGllbnRf...',
            container_id: 'widgetContainer',
            consumer_data: {
                consumer_id: '123456', //the same that was used to generate the access token
                application_id: 'abc12345', //a unique identifier of the application, such as a loan id
                reference_date: '2023-03-14', //usually the current date
                first_name: 'John',
                middle_name: 'Edge',
                last_name: 'Smith',
                nickname: 'John',
                birth_date: '1995-01-01',
                ssn: '322-32-5345',
                full_address: '222 South Riverside Plaza Suite 200, Chicago, IL 60606',
                street_address: '222 South Riverside Plaza',
                street_address2: 'Suite 200',
                city: 'Chicago',
                state_code: 'IL',
                zip_code: '60606',
                home_phone: '855-646-5201',
                mobile_phone: '855-646-5201',
                email: '[email protected]',
                secondary_email: '[email protected]',
                employer_name: 'Edge LLC',
                secondary_employer_name: 'Edge LLC2',
                bank_name: 'Bank of America',
                routing_number: '000111449',
                account_number: '2302389238923',
                debit_card_number: '1234567890123456',
                additional_data: {
                    vantage_score: 500,
                    housing: 'rent'
                },
                partner_name: '<only applies to partners>'
            },
            data_pull_timeout: 300,

            //Optional timeout setting for data pulls. Default is 300 seconds (5 minutes)
            intent_url: 'myApp://',
            //required only for native mobile apps to handle OAuth callbacks
            onSuccess: (data) => {
                console.log(data)
                //NinjaFetchWidget.unmount()
            },
            onError: (data) => {
                //Handle Technical errors. 
                console.log(data)
                if (data.hasOwnProperty("isLastVendor") && data.isLastVendor) {
                    NinjaFetchWidget.unmount()
                }
            },
            onClose: (data) => {
                //Reserved for future features
                console.log(data)
            }
        }
        //Initialize widget
        try {
            NinjaFetchWidget.mount(consumerData)
        }
        catch (err) {
            //Handle mounting errors here
            console.log(err)
        }
    }
</script>

3.1 Supported Fields

4. Handle Initialization Errors

   //Initialize widget
   try{
       NinjaFetchWidget.mount(consumerData)
   }
   catch(err){
       //Handle mounting errors here
       console.log(err)
   }

The widget will validate the data and throw validation errors. The client application will need to correct the data being passed into the widget and retry.

Example

{
 "message": "Invalid data",
 "fields": {
 	<field 1>: <value 1>,
 	<field 2>: <value 2>
}

5. Handling Callbacks

The Widget will send results back through the three callback functions: onSuccess(), onError(), and onClose().

5.1 onSuccess()

The widget will invoke a first callback once the consumer successfully connects a bank. The callback will have the ibv_report_status value set to “initiated”. Clients who do not make real-time decisions should unmount the widget after the first callback, so the consumer does not need to wait while the NinjaFetch platform downloads transactions and creates the report.

The widget will invoke a second callback once the NinjaEdge report is complete. Ibv_report_status will be ”complete”. Clients who make real-time decisions based on the NinjaEdge report should wait for the second callback. The returned product_request_id is the unique identifier of the NinjaEdge report, available for download via backend APIs.

Example

{
    "product_request_id":"IBV9176637hhh77"
}

5.2 onError()

Called when a technical error occurs. The actual error message will be passed to the callback function.

There is a flag in the parameters called isLastVendor. Unmount the Widget and proceed to error handling only when isLastVendor is true. The consumer can attempt connections with a different IBV aggregator when isLastVendor is false.

{
    "message": "Network error",
    "isLastVendor": false
}

Possible error messages:

5.3 onClose()

Reserved for future features.

6. Handle Data Pull Timeout

After the Consumer connects their bank accounts, a backend process will start to download IBV data through the connection.

Usually, this step takes less than 2 minutes to complete. However, depending on the quality of the data aggregator’s bank connection, it may take a few tries and up to 30 minutes for the NinjaFetch platform to acquire the data. By default, the NinjaFetch widget will send a timeout callback to the onError() function and unmount itself after 5 minutes.

The Client can change the timeout by passing a custom data_pull_timeout value to the widget to optimize the user experience. The Client can either try to download the report at a later time (it is recommended to wait for at least 2 minutes before the next attempt), or implement Webhooks to receive updates from the NinjaFetch platform.

When the Client recognizes a timeout it may make any number of retry attempts, which should eventually lead to one of the following responses:

• IBV Report - HTTP 200
• IBV Report Pending - HTTP 202

7. Report download

After receiving the product_request_id from the widget, the Client application backend can retrieve the full report with a GET to the [/ibv/requests/{request id}](/ibv/requests/{request id}) endpoint. Refer to the IBV Product API Specification document for details about interacting with the API.