Adding Widget to Application
Steps to Add the NinjaFetch Widget to your application
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
Name | Description | Example | Type | Format | Required |
---|---|---|---|---|---|
access_token | Received by calling the /auth/tokens endpoint | eyJjbGllbnR... | String | JWT | Yes |
container_id | ID of the container element added at step 2 | widgetContainer | String | Yes | |
consumer_id | A unique identifier provided by the client for each consumer. The same ID that was used to generate the access token | 123456 | String | Yes | |
application_id | Unique identifier for an application, such as a loan. Used to build data analytics reports. | loan12345 | String | No | |
first_name | First name of the consumer | John | String | Yes | |
last_name | Last name of the consumer | Smith | String | Yes | |
ssn | Social security number. | 322-32-5345 | String | DDD-DD-DDDD | No |
routing_number | Routing number of the account the consumer wants to use for IBV. Used to pre-select bank for verification | No routing number or 000111449 or 074000101. | String | /^\d{9}$/ | No |
account_number | Account number of the account specified by the consumer to use for IBV analysis | 523423512 | String | /^[0-9]*$/ | No |
birth_date | Date of birth | 1776-07-04 | String (Date) | YYYY-MM-DD | No |
street_address | Street number and name | 222 South Riverside Plaza | String | No | |
street_address2 | Address unit designator and number | Suite 2200 | String | No | |
city | City | Chicago | String | No | |
state_code | U.S. State Code | IL | String | No | |
zip_code | U.S. Postal Code (5-digit OR 9-digit) | 60606 | String | /^[0-9]{5}(?:-[0-9]{4})?$/ | No |
home_phone | Landline number | 855-646-5201 | String | DDD-DDD-DDDD | No |
Email address of the consumer. | [email protected] | String | /\A[^@\s]+@[^@\s]+\z/ | No | |
mobile_phone | Mobile phone number | 855-646-5201 | String | DDD-DDD-DDDD | No |
additional_data | Additional data for data analytics based on agreements | {“vantage_score”:500, “housing”:”rent”, “existing_customer”:true … | String | No | |
intent_url | URL for OAuth redirect in native mobile apps | myApp:// | String | Yes, native mobile apps only | |
partner_name | Name of the partner | Edge | String | Yes for partners only |
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.
{
“ibv_report”: “https://ninjafetch.com/api/v1/ibv/requests/IBVF15CE1FD5FADC7663604”,
“product_request_id”: “IBVF15CE1FD5FADC7663604",
“ibv_report_status”: “initiated”,
“ibv_connection_link”: “https://ninjafetch.com/connect/a06bbd625a”
}
The widget will invoke a second callback once the NinjaEdge report is complete. Ibv_report_status will be ”complete”. Only clients who make real-time decisioning 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.
{
“product_request_id”: “IBVF15CE1FD5FADC7663604",
“ibv_report”: “https://ninjafetch.com/api/v1/ibv/requests/IBVF15CE1FD5FADC7663604”,
“ibv_report_status”: “complete”
}
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:
Message | Description |
---|---|
Generation failed | Failed to generate features or scores due to corrupted data etc |
Pull process timed out | It’s taking longer than the timeout limit to download IBV data using the connection. Default timeout is 5 minutes. The backend will keep attempting data download for up to 30 minutes. |
Other Technical Message | Actual technical error message |
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.
Updated 4 months ago