Credit Passport Quickstart Guide

Introduction

This quickstart guide provides information on how to integrate with Nova Credit and use the API to retrieve a Credit Passport®. Nova Credit provides a secure, plug and play module called NovaConnect to make integrating quick and easy.

NovaConnect is secure, quick to integrate, and easy to use.

Your applicants can use NovaConnect to authenticate with a foreign credit bureau and authorize Nova Credit to fetch their report. Nova Credit takes care of customizing the form and handling errors with each bureau so that you don't have to. The Credit Passport® data includes, but is not limited to, the applicant's credit history, current tradelines, payments, inquiries, and credit scores.

Once a user has successfully gone through the NovaConnect flow, you can use the Nova Credit Dashboard to retrieve the applicant's Nova Credit Passport®. You can also use the optional server-side integration to retrieve reports automatically.

Credentials & Identifiers

Account Keys

The NovaConnect and server-side API keys are accessible from your Nova Credit Dashboard.

publicId [string] Used when integrating NovaConnect to identify your account.
clientId [string] Your Nova Credit API identifier. You will use this to programmatically access resources.
secretKey [string] Your Nova Credit API key (keep this secret). You will use this to programmatically access resources.

Programmatically generated tokens

publicToken [string] Identifies a specific Credit Passport®.
accessToken [string] Used to authorize server-side requests (keep this secret). You will use generate an accessToken each time you fetch a Credit Passport®.

Sandbox & Production Environments

Nova Credit provides two environments: one suitable for developing and testing your integration and one for production requests. The former provides a safe place for you to access Nova Credit's resources and test different response types using dummy data.

Both environments have their own endpoint, publicId, clientId, secretKey, publicTokens, and accessTokens. Please be sure to use the correct endpoint and credentials for the resource's environment you are requesting. Using the wrong endpoint, credentials, or tokens for the specified environment usually leads to errors such as UNKNOWN_CUSTOMER.

Available environments

sandbox Suitable for development and testing.
production Use for production-level interactions with applicants and suppliers.

There are two URLs that may be used to access API calls: api.sandbox.novacredit.com for sandbox testing, and api.novacredit.com for production data. Note that the examples in the docs use the production URL, so this should be changed to the sandbox URL for development and testing.

X-ENVIRONMENT header (Deprecated)

The sandbox and production environments may also be accessed by using the api.novacredit.com URL and providing an X-ENVIRONMENT header set to either sandbox or production. However, this behavior is deprecated and it is encouraged to use the separate URLs above without including this header.

Client-Side Integration

Step 1: Product configuration

Applicants use NovaConnect as part of an application process for one of your product offerings, be it a property lease at a specific building, a credit card or an auto insurance product. To help you identify which product an applicant has applied for, you first have to create a productId using your Nova Credit Dashboard account.

To create a product, login to your Nova Credit Dashboard account, click on the Products tab and click 'Add a Product'. Once you have created your products, you can view their productIds by clicking the Developer tab and Product IDs.

Step 2: Add NovaConnect to your page

See below for a minimal code example of how to configure NovaConnect.

<html>
<head>
    <script src="https://static.novacredit.com/connect/v2/init.js"></script>
</head>
<body>
    <div id="nova-embed"></div>

    <script>
        window.Nova.register({
          env: 'sandbox',
          publicId: 'your_sandbox_public_id',
          productId: 'your_sandbox_product_id',
        });
    </script>
</body>
</html>

Let's walk through this.

Firstly, you will need to add init.js, a script-tag that should be loaded inside your HTML's <head></head>.

Secondly, you will need an unstyled div in which NovaConnect can render. Add this div where you would like the NovaConnect button or widget to appear, and give it one of the following ids:

nova-embed Use this div id to render the NovaConnect widget inline, as an embedded widget. Nova Credit will appear alongside other elements of your application.
nova-button Use this div id to render the NovaConnect "Import Credit Report" button. Nova Credit will fill the entire screen.

Lastly, you will need to add a script that configures and initiates the rendering of the NovaConnect experience at the bottom of your HTML body. The relative order of the div and scripts placements is important.

Custom Trigger Version

Alternatively, NovaConnect can be triggered using a custom element. NovaConnect will render as a modal that will appear on top of your application. For this alternate experience, the relevant code is provided below.

<html>
<head>
    <!-- Other head files here -->
    <script src="https://static.novacredit.com/connect/v2/init.js"></script>
</head>
<body>
    <!-- Button or embedded widget placement div -->
    <button onclick="window.Nova.fire()">Open NovaConnect</div>

    <script>
        window.Nova.register({
          env: 'sandbox',
          publicId: 'your_sandbox_public_id',
          productId: 'your_sandbox_product_id',
          useManualFire: true
        });
    </script>
</body>
</html>

There are two notable differences in this snippet as compared to the embedded version of NovaConnect:

<div id="nova-embed"></div> is replaced by a button on your application page. This styling and content of the button can be configured to meet your needs as long as it calls window.Nova.fire() when clicked.
Pass an additional useManualFire: true as a parameter to window.Nova.register to signal to NovaConnect that a custom button is being used to launch the experience.

NovaConnect Required Parameters

env [string] Either sandbox or production.
productId [string|function] See Step 1.
publicId [string] Specific to your account. Found on the Nova Credit Dashboard.

You can dynamically set values for the required parameters if you pass a function to any suitable parameter but make sure to resolve with the expected variable type.

NovaConnect Optional Parameters

country [string|function] Provide an ISO country code to load NovaConnect with a pre-specified country.
externalId [string] Pass in the unique applicant identifier fom your system. This will be returned to you in our webhook call and in the API JSON response. You can use this identifier to match the Nova Credit public token (Nova Credit report identifier) with the applicant in your system. Note that this MUST be unique and MUST NOT include any consumer PII.
language [string|function] Specify the language NovaConnect should open with as a 639-1 language code. (Applicants also have the ability of changing the language themselves within NovaConnect). Note that not all languages are available for all countries. Contact your Nova Credit representative to learn more.
prefill [object|function] Prefill specific fields for the applicant by passing an object which maps keys to string values. See Available Prefill Keys below.
userArgs [string|function] Any additional metadata you'd like to associate with the report. This will be returned to you in our webhook call and in the API JSON response.

Available Prefill Keys (optional)

You may dynamically provide values for some or all of these keys, and their values will be automatically entered in NovaConnect. Applicants will still have the ability to change the values, in case their information is different in their country of origin.

firstName [string] The first name of the applicant.
lastName [string] The last name of the applicant.
dob [string] The date of birth of the applicant in YYYY-MM-DD format.
email [string] The email address of the applicant.
city [string] The most recent city where the applicant has lived in the foreign country.

You may also choose to contact your Nova Credit account manager to lock the values provided for the following keys, restricting the applicant from making any changes to these PII values and ensuring uniformity of data across their applications and preventing any potential fraudulent activities.

firstName The first name of the applicant.
lastName The last name of the applicant.
dob The date of birth of the applicant in YYYY-MM-DD format.
email The email address of the applicant.

Using Client-Side Hooks (optional)

You may use the onSuccess, onError, and onExit client-side hooks to know when an applicant has finished their interactions with NovaConnect. As examples, you may use these hooks to alter content on your application page or route the applicant elsewhere when the applicant finishes NovaConnect.

onSuccess

onSuccess() gets called when the applicant completes the entire NovaConnect journey and attempts to pull their

. onSuccess is called with the parameters (publicToken, status).

onExit

onExit() is called when the applicant voluntarily closes NovaConnect, whether or not they completed the entire NovaConnect journey. onExit is called with the parameter (publicToken), if it exists. This hook will not be fired if the applicant navigates away from your application page without closing NovaConnect.

onError description & error types

onError() gets called when there was an internal error or an applicant was unable to complete the entire NovaConnect journey. onError is called with the parameters (publicToken, errorType). Public token is the Nova report unique identifier for this applicant.

Error types will be one of the following; if no error type is provided (null or undefined), this implies an internal Nova error:

Error	Description
`BUREAU_UNRESPONSIVE`	The request to the bureau is nonresponsive.
`DUPLICATE_EXTERNAL_ID`	The specified External ID is already in use by another report for the customer.
`INTERNAL_ERROR`	Nova encountered an error internally.
`INVALID_PREFILL_DOB`	The date of birth provided is invalid.
`INVALID_PREFILL_EMAIL`	The email address provided does not follow the required format.
`INVALID_PREFILL_FIRST_NAME`	The first name provided does not follow the required format.
`INVALID_PREFILL_FULL_NAME`	The full name provided does not follow the required format.
`INVALID_PREFILL_LAST_NAME`	The last name provided does not follow the required format.
`INVALID_PRODUCT`	The productId does not match any products for the customer.
`REQUEST_TIMEOUT`	The request to the server has timed out.
`UNKNOWN_CUSTOMER`	The publicId provided does not match a valid customer.
`UNSUPPORTED_COUNTRY`	The applicant entered a country that Nova does not support. They are unable to complete the Nova flow as a result.

Example HTML file that utilizes the full list of configuration options:

<html>
<head>
    <script src="https://static.novacredit.com/connect/v2/init.js"></script>
</head>
<body>
    <script>
        window.Nova.register({
                env: 'sandbox',
                publicId: '7292265cd901306dd78e13e8c09ec269c872ad863aff6c15af9799d9de6c02ds',
                productId: 'e7fb80e3-8623-4a76-bcc7-f681bcbdf875',

                country: 'IND',
                externalId: '5645cbfc-5331-4d3d-aee3-0d5e27463c4f',
                userArgs: 'your_applicant_id',
                useManualFire: true,
                language: 'fr',
                prefill: {
                    firstName: 'Raj',
                    lastName: 'Du',
                    dob: '1993-01-25',
                    email: 'rajdu@email.com',
                    city: 'New Delhi',
                },
                onSuccess: function (publicToken, status) {
                    // Applicant has completed NovaConnect and a webhook will be called
                    console.log(publicToken);
                },
                onExit: function () {
                    // Applicant exited the NovaConnect widget
                    console.log('Applicant exited NovaConnect');
                },
                onError: function (publicToken, error) {
                    // Applicant was unable to complete NovaConnect
                    console.log(publicToken);
                    console.log('Applicant encountered an internal error', error);
                }
            }
        );
    </script>
    <!-- Button to open the NovaConnect widget -->
    <button onclick="window.Nova.fire()">Open Widget</button>
</body>
</html>

Server-Side Integration

Step 1: Set-up your webhooks

As an applicant goes through the NovaConnect flow, Nova Credit will automatically POST to your provided callback endpoint to update you on the status of the Credit Passport® tied to the publicToken.

For example, if the applicant completes NovaConnect and Nova Credit is able to successfully compile a report, Nova Credit will make a POST API call to your endpoint.

You must set your webhook callback url and webhook subscriptions in the Nova Credit Dashboard via the Developer tab.

For security, the Credit Passport® is not provided directly in the callback; instead, the callback provides a unique identifier called a public token, which you will use to retrieve a Credit Passport® in a separate call. ‍ For more information regarding the webhook body, please view the API Docs.

Step 2: Get an access token

If the webhook status was SUCCESS, you should now make a request to Nova Credit's servers to retrieve the Credit Passport®. In order to do so, you will need to first fetch an access token using your Nova Credit client id and secret key. Access tokens are time-scoped to prevent malicious usage should someone obtain one. You should retrieve a new access token each time you intend to retrieve a Credit Passport®.

GET https://api.novacredit.com/connect/accesstoken

Required headers

Authorization Basic Auth, containing the strict base-64 encoded string of your client_id:secret_key (ensure you use the corresponding client id and secret key to the environment you define).

Possible responses‍‍

200 (OK) Both accessToken and exp will be returned
403 (Forbidden) Unauthorized request. Your client_id or secret_key was incorrect, or you did not correctly base-64 encode it.
400 (Bad Request) Malformed request, headers or missing required parameters. Error will be one of MALFORMED_HEADERS or MALFORMED_BODY.

The response body will be a JSON containing the following keys:

accessToken The access token you can now use to retrieve a Credit Passport® with
exp When the access token will expire, provided as a unix timestamp. Access tokens have a lifetime of 5 minutes. If you do not retrieve the Credit Passport® before the access token expires, you will need to request a new access token.

Example request

require('request').request(
    {
        url: 'https://api.novacredit.com/connect/accesstoken',
        method: 'GET',
        headers: {
            Authorization: 'Basic ' + Buffer.from('<Your client_id>:<Your secret_key>').toString('base64'),
        },
    },
    function (err, res, body) {
        const { accessToken } = body;
        // See bellow for next steps to fetch the report
    },
);

Example response

{
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3MjMyNTQwNjksImV4cCI6MTcyMzI1NDM2OSwiY2xpZW50X2lkIjoiNjFhNDdiMDQtZWIyMy00YWNlLWE2OWQtYzg4OWI5YjExYTRjIiwiZW52Ijoic2FuZGJveCJ9.HVlHgidZdi2-qY92zhE-MmLYNNqnuIBAoRapA6rbM78",
    "exp": 1526077901
}

Step 3: Request a Credit Passport®

Now you can use the access token and public token to retrieve the report.

GET https://api.novacredit.com/connect/passport/v4/json
- The JSON endpoint will return the Credit Passport® directly in the response body. Depending on your web application framework, you may need to convert the response body into a JSON object, such as JSON.parse(res.body).
GET https://api.novacredit.com/connect/passport/v4/pdf
- The PDF endpoint will return the Credit Passport® directly in the response body with content type: application/pdf; you don't need to do any explicit encoding/decoding on your own, as your web application framework should know how to interpret the data given the content type. Both streaming and using a (multi-part) blocking GET request that receives the full content should work and in both in cases, you're able to simply write the response body to disk and it will render a pdf if saved with the pdf suffix.

Required headers

One of the following identifiers:
- X-PUBLIC-TOKEN The unique identifier of the report you are retrieving, provided to you via webhook.
- X-EXTERNAL-ID The unique applicant identifier from your system that was sent to Nova Credit.
  - X-PUBLIC-ID is a required header if you choose to use X-EXTERNAL-ID as an identifier and are making this request using a Parent account. This value is the public_id of the child account that owns the report found on your Nova Credit Dashboard.
Authorization Bearer Auth, containing the strict base-64 encoded string of the valid accessToken you retrieved in Step 2.

Optional headers

Accept-Language If you are a customer based in Canada, you can pass in fr-CA for the /pdf endpoint to get a French Canadian version of the PDF.

Example request

require('request').request(
    {
        url: 'https://api.novacredit.com/connect/passport/v4/json',
        method: 'GET',
        headers: {
            Authorization: `Bearer ${Buffer.from('eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3MjMyNTQwNjksImV4cCI6MTcyMzI1NDM2OSwiY2xpZW50X2lkIjoiNjFhNDdiMDQtZWIyMy00YWNlLWE2OWQtYzg4OWI5YjExYTRjIiwiZW52Ijoic2FuZGJveCJ9.HVlHgidZdi2-qY92zhE-MmLYNNqnuIBAoRapA6rbM78').toString('base64')}`,
            'X-PUBLIC-TOKEN': '829de2f0-fe06-405b-a18f-3d31641ccb3b',
        },
    },
    function (err, res, body) {
        // Parse Credit Passport®
    },
);

View our API Docs for details and examples of the contents of the report.

Encrypted Payload Implementation

In addition to securing endpoints with TLS/SSL, some of Nova Credit's endpoints offer payload encryption.

Customer generates a Content Encryption Key (aka “CEK” or “session key”), which is an AES 256-bit key.
The request body JSON (aka the “payload” or “plaintext”), is encrypted using the Content Encryption Key.
The Content Encryption Key is encrypted using Nova Credit's RSA public key.
The encrypted payload is sent with the encrypted CEK and parameters in the JWE Compact Serialization Format.

GET /connect/jwkset

Nova Credit uses the JSON Web Keys (JWK) format to publish our public encryption keys for Encrypted Payloads. Note that this endpoint should be called each time a payload is to be encrypted, since we will regularly rotate keys.

GET https://api.novacredit.com/connect/jwkset

Required headers‍

Content-Type application/json.

Possible responses‍‍

200 (OK) Returns an array of keys
400 (Bad Request) Malformed request. Error will be one of MALFORMED_HEADERS or MALFORMED_BODY.

Example request

curl -X GET \
https://api.novacredit.com/connect/jwkset \
-H 'Content-Type: application/json' \

Example response

{
    "keys": [
        {
            "alg": "RSA-OAEP-256",
            "kid": "payloadEncrRsa",
            "kty": "RSA",
            "use": "enc",
            "n": "7kZDkQB78iYrQOhW7BZrtrnUNbYQMuEwrLXtLLCmH4WJjPyccZuOAHQJIgS3qluXnJbVZKwF52P73nF3v7AB8L1MVqRp94t5QlA5ysHscvDa_lXjcN6DSREY66LzQkita-zU0de9_6v1DVfbjn7OiPA_gbQVKMM3vPzToYInz6RnSJTG1bLbcRM_4YBDEqxphAJmEywP-E4xCwGn05Sdw5trJquWKIKPLMK9XWRiWifqeS8v2dZg_pbLjg_zPNXy0BcIIrci2K1TbuEXoAGFbjbuFN7WQPkclcP9dP2jE1OEWxMzg5FoSQo6QKCBIz3lkkPhqg4MQz_VhHgQvX_KrmO_pIHebvkc_473yf5J7YUOq5ze97OH67JflVSh0aFk7k6Yd8dgQCQID_6LaQHFTitTZScy3Cyl0gD34ifo8DnAX-BrbqBP92makSH1VuYQ0ejbMpz-Ayln4h1nGX-85XL_rgWF4bIPYlP2hnZKNpAr_Fa7uICH5mzsilnFybUIgQjDZ2KhKYe1ayNDPf7lvdPUw1SWAqdnz0glKfOC7CHQtSkU7n8sSBUl8KA24fZggNydKt9-VEL6si-wcR8OJ2IUfe2Ut5VE339V-C-zTh-iVoujinBGpmP-iIyJzRTTmHHwhOy7yRFRO1wQkVz02QFYi8f-sF7Mntm3rzC8RwM",
            "e": "AQAB"
        }
    ]
}

NovaConnect Initialization

The initialization endpoint may be used as an alternative way to pass prefill data to Nova Credit instead of passing it on the client-side.

Step 1: Call the initialization endpoint

POST https://api.novacredit.com/connect/initialization

Required headers‍

X-PRODUCT-ID The product_id associated with the product the applicant is applying for.
X-PUBLIC-ID Your Nova Credit public_id, found on your Nova Credit Dashboard.
Authorization Basic Auth, containing the base-64 encoded string of your client_id:secret_key.
Content-Type application/json.

‍Required body parameters

token [string] Must be set to "JWT" to indicate to us that a token should be returned
prefill [object] An object representing the applicant
- prefill.firstName [string] The first name of the applicant. Less than 255 characters and contain only alphabetical, unicode, dots, apostraphes and dashes.
- prefill.lastName [string] The last name of the applicant. Less than 255 characters and contain only alphabetical, unicode, dots, apostraphes and dashes.
- prefill.email [string] The email address of the applicant. Max length 100 characters.

Optional body parameters

country [string] Provide an ISO country code to load NovaConnect with a pre-specified country.
prefill.dob [string] The applicant's date of birth, in the format YYYY-MM-DD.
prefill.city [string] The city where the applicant lives. Max length 100 characters.
externalId [string] Pass in a unique internal identifier for your own records. It will be provided in our webhook call and can be used to retrieve the report

Possible responses‍‍

200 (OK) Both a publicToken and a token will be returned associated with this application
403 (Forbidden) Unauthorized request. Your client_id or secret_key was incorrect, or you did not correctly base-64 encode it.
400 (Bad Request) Malformed request, headers or missing required parameters. Error will be one of MALFORMED_HEADERS or MALFORMED_BODY.

Example request

curl -X POST \
https://api.novacredit.com/connect/initialization \
-H 'Content-Type: application/json' \
-H 'X-PRODUCT-ID: 3c2da600-17ee-11e8-8a0e-5158039db37e'
-H 'X-PUBLIC-ID: aa2eebe1-c02a-11e6-88fa-fbe350f5820f'
-H 'Authorization: Basic YWU2Y2VkNjktOGFmOC00N2M5LWE5YTItZjI3NjA4OWI0ZjBlOmY4OGRiNzViODNkOWYwMDhkODJhNTRmOWRkODkwOTdkM2ZkM2Y4OWRlYzFjOTZiMTJkNzFjZjQyNjRhMmE0ZTY='
-d '{
    "token": "JWT",
    "prefill": {
        "firstName": "Raj",
        "lastName": "Du",
        "dob": "1990-12-01",
        "email": "raj@email.com",
        "city": "San Francisco"
    },
    "country": "IND",
    "externalId": "0a78c605-e97c-461a-a400-63d53d882a47"
}'

Example response

{
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3MjEwODIzMTEsImV4cCI6MTcyMTA4MjkxMSwiYXBwbGljYXRpb25JZCI6ImM1NzBlMDE0LTA4YWEtNGU0MC05M2QwLTAyMDQxMDMzNGRiZCIsInZpc2l0SWQiOiJiZDYzYTFiOS1kMzcyLTQ1ZjEtYWJmNS0wMmQwZGE0M2MyZTYifQ.Xu-xlKn7DdAsTk8_QrwP7uRjMTap543A0k8w87w8o4Q",
    "publicToken": "1455ad79-8b1e-4efd-a851-9507f61aa240"
}

Step 2: Pass the initialization token to NovaConnect

Instead of passing in the prefill or externalId fields into the Nova.register function, only pass through the token parameter. Note that passing in both prefill and token will result in an INVALID_TOKEN error.

window.Nova.register({
    env: 'sandbox',
    publicId: 'f84cd30a5e31b318f88ef1b9334b8a472585394763ab3dc594be4c654b4ba232',
    productId: '3c2da600-17ee-11e8-8a0e-5158039db37e',
    token: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3MjEwODIzMTEsImV4cCI6MTcyMTA4MjkxMSwiYXBwbGljYXRpb25JZCI6ImM1NzBlMDE0LTA4YWEtNGU0MC05M2QwLTAyMDQxMDMzNGRiZCIsInZpc2l0SWQiOiJiZDYzYTFiOS1kMzcyLTQ1ZjEtYWJmNS0wMmQwZGE0M2MyZTYifQ.Xu-xlKn7DdAsTk8_QrwP7uRjMTap543A0k8w87w8o4Q',
});

NovaConnect Initialization - Encrypted Payload

Alternatively, the initialization endpoint can be called with an encrypted payload for additional security. This can be sent in the JWE Compact Serialization Format which is the concatenation of:

BASE64URL(UTF8(JWE Protected Header)) || '.' ||
BASE64URL(JWE Encrypted Key) || '.' ||
BASE64URL(JWE Initialization Vector) || '.' ||
BASE64URL(JWE Ciphertext) || '.' ||
BASE64URL(JWE Authentication Tag)

Step 1: Encryption of payload

The following is an example of how to use the default Node crypto library to put together the JWE.

First, define the JOSE. Note that the following three properties must be set.

const joseHeader = {
    alg: 'RSA-OAEP-256', // CEK is encrypted using the RSAES-OAEP to produce the JWE Encrypted Key
    enc: 'A256GCM', // Authenticated encryption performed on payload using AES GCM with a 256-bit key
    kid: 'payloadEncrRsa',
};

const jweProtectedHeader = Buffer.from(JSON.stringify(joseHeader), 'utf8').toString('base64url');

Generate the Content Encryption Key or "CEK" (AES 256-bit key) and corresponding Initialization Vector or "IV":

const crypto = require('crypto');
const contentEncryptionKey = crypto.randomBytes(32); // 256-bit Buffer
const initializationVector = crypto.randomBytes(32);

const cipher = crypto.createCipheriv('aes-256-gcm', contentEncryptionKey, initializationVector);
cipher.setAAD(jweProtectedHeader);

Use the generated CEK and IV to encrypt the payload you intend to send to the /connect/initialization endpoint.

const payload = {
    token: 'JWT',
    prefill: {
        firstName: 'Raj',
        lastName: 'Du',
        email: 'raj@email.com',
        // other prefill fields here
    },
    externalId: '0a78c605-e97c-461a-a400-63d53d882a47',
};

const cipherText = Buffer.concat([cipher.update(JSON.stringify(payload)), cipher.final()]);
const authenticationTag = cipher.getAuthTag();

Use the GET /connect/jwkset endpoint to retrieve Nova Credit's public keys. Use the payloadEncrRsa key to encrypt the CEK.

const novaJwk = keys.find(key => key.kid === 'payloadEncrRsa');

const encryptedCek = crypto.publicEncrypt(
    {
        key: crypto.createPublicKey({ key: novaJwk, format: 'jwk' }),
        oaepHash: 'sha256',
        padding: crypto.constants.RSA_PKCS1_OAEP_PADDING,
    },
    contentEncryptionKey,
);

Put together the final JWE Compact Serialization Format.

const jweEncryptedKey = Buffer.from(encryptedCek).toString('base64url');
const jweIv = Buffer.from(initializationVector).toString('base64url');
const jweCipherText = Buffer.from(cipherText).toString('base64url');
const jweAuthTag = Buffer.from(authenticationTag).toString('base64url');
const encryptedValue = `${jweProtectedHeader}.${jweEncryptedKey}.${jweIv}.${jweCipherText}.${jweAuthTag}`;

Using a third party library

You could also use a library like jose to do these steps for you.

const jose = require('jose');
// use the `novaJwk` and `joseHeader` defined in the example above

const publicKey = await jose.importJWK(novaJwk, 'PS256');
const encryptedValue = await new jose.CompactEncrypt(new TextEncoder().encode(JSON.stringify(payload)))
    .setProtectedHeader(joseHeader)
    .encrypt(publicKey);

Step 2: Call the initialization endpoint

POST https://api.novacredit.com/connect/initialization

Required headers‍

X-PRODUCT-ID The product_id associated with the product the applicant is applying for.
X-PUBLIC-ID Your Nova Credit public_id, found on your Nova Credit Dashboard.
Authorization Basic Auth, containing the base-64 encoded string of your client_id:secret_key.
Content-Type application/json.

‍Required body parameters

encryptedValue [string] Contains the JWE Compact Serialization Format

Possible responses‍‍

200 (OK) Both a publicToken and a token will be returned associated with this application
403 (Forbidden) Unauthorized request. Your client_id or secret_key was incorrect, or you did not correctly base-64 encode it.
400 (Bad Request) Malformed request, headers or missing required parameters. Error will be one of MALFORMED_HEADERS or MALFORMED_BODY.

Example request

curl -X POST \
https://api.novacredit.com/connect/initialization \
-H 'Content-Type: application/json' \
-H 'X-PRODUCT-ID: 3c2da600-17ee-11e8-8a0e-5158039db37e'
-H 'X-PUBLIC-ID: aa2eebe1-c02a-11e6-88fa-fbe350f5820f'
-H 'Authorization: Basic YWU2Y2VkNjktOGFmOC00N2M5LWE5YTItZjI3NjA4OWI0ZjBlOmY4OGRiNzViODNkOWYwMDhkODJhNTRmOWRkODkwOTdkM2ZkM2Y4OWRlYzFjOTZiMTJkNzFjZjQyNjRhMmE0ZTY='
-d '{
    "encryptedValue": "eyJhbGciOiJSU0EtT0FFUC0yNTYiLCJlbmMiOiJBMjU2R0NNIiwia2lkIjoicGF5bG9hZEVuY3JSc2EifQ.Nx-l5_kRwzd3da0Z1GbHozkADsb_vK1-lKAvAsGJkW9rUyI_bu6lyk0yO5sPpvKqUcjDwRSx42TQSe8JlBzlm5WSWmMslatDjOPuTudO5m7K_4-2L2NDeT7VUdkfpE4Dx4hpHTzEhL-uf5A5AMULWCI8RyQA_1pgY20yFmfs92JRnJVZYfIX7q96lMBspu6Y83AoPxLoK54sNChyB1qVbM-oJTP2xpZHl2nRqPXV-Gm-hBzhsHGPDsv8d9rgmZ6PrlnLH-UNn6dO0N_BG4pqTEZ1r8gT9ZLZhuCljS8sAGgQY6HiroxVDGnTLFBhLcX4tSeC4RI0_XUxbVOlVr5s_OOEaCNPD3mtFsS2ec3o64iV7NqqLZghuupj-hUQ0XcbmKc_-zaMnJ-4ZNIitVAeHmejY83rWgfQeq0UZBeCKS0kjaf9sRXQ9bauAqKY55NFaf-DYjyqSu6WVR7wh2pSMzZJMdCU67m-htcGPgNgz--4dO9CIsHOYi00xEC8zWS_F2AumrtxrCpr6Fau5GGHrfV638XvmC6cBkEsxGCRLVQpbV3x53ZQMt7X15058w_yKXZnKqETU8tZwjgHf82eaez9Bmr3_cXbsPz5dr1CZZFy4IzwL1mUzr796AdI2aEqNedFNXDn0dmDJPWOZuZUcc_WzkXrprL7iM_uD4fZBZ0.h2l7VfToM_5ToXjMGpcA1Vo_Sh2dQOHtZCVVKuEqhrg.iOr5l1JkWEJW4V_WbzteWdyUx0ak_GDCIA4PZ5amuXyyZhTPufhJ8K3hPg0TTu91roIaVxLBsJQyfKM03l_aeMubarFCzgDKscRLS8MAJ7RoRxSaiQKrjoGbyMdnhv_rseFJp-U5z6Lg4078cFA_jTRNi574LHjrY--pBGBI.6Dmrf6rGJMkTt4a41LGMAQ"
}'

Example response

{
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3MjEwODIzMTEsImV4cCI6MTcyMTA4MjkxMSwiYXBwbGljYXRpb25JZCI6ImM1NzBlMDE0LTA4YWEtNGU0MC05M2QwLTAyMDQxMDMzNGRiZCIsInZpc2l0SWQiOiJiZDYzYTFiOS1kMzcyLTQ1ZjEtYWJmNS0wMmQwZGE0M2MyZTYifQ.Xu-xlKn7DdAsTk8_QrwP7uRjMTap543A0k8w87w8o4Q",
    "publicToken": "1455ad79-8b1e-4efd-a851-9507f61aa240"
}

Step 3: Pass the initialization token to NovaConnect

window.Nova.register({
    env: 'sandbox',
    publicId: 'f84cd30a5e31b318f88ef1b9334b8a472585394763ab3dc594be4c654b4ba232',
    productId: '3c2da600-17ee-11e8-8a0e-5158039db37e',
    token: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3MjEwODIzMTEsImV4cCI6MTcyMTA4MjkxMSwiYXBwbGljYXRpb25JZCI6ImM1NzBlMDE0LTA4YWEtNGU0MC05M2QwLTAyMDQxMDMzNGRiZCIsInZpc2l0SWQiOiJiZDYzYTFiOS1kMzcyLTQ1ZjEtYWJmNS0wMmQwZGE0M2MyZTYifQ.Xu-xlKn7DdAsTk8_QrwP7uRjMTap543A0k8w87w8o4Q',
});

NovaConnect Invite Endpoint

The invite endpoint may be used to send an email inviting your applicant to fill out NovaConnect. The invitation is sent to the specified applicant's email address and includes a link to a pre-configured NovaConnect widget hosted on Nova Credit's domain. Once the applicant completes NovaConnect, their reports are accessible via the API.

POST https://api.novacredit.com/connect/invite

Required headers‍

X-PUBLIC-ID Your Nova Credit public_id, found on your Nova Credit Dashboard. (Unless using Managing multiple accounts method below.)
Authorization Basic Auth, containing the base-64 encoded string of your client_id:secret_key.
Content-Type application/json.

‍Required body parameters

applicantFirstName [string] The first name of the applicant.
applicantLastName [string] The last name of the applicant.
applicantEmail [string] The email address of the applicant.
productId [string] The product_id associated with the product the applicant is applying for. (Unless using Managing multiple accounts method below.)

If applicant billing is enabled:

chargeAmount [number] The amount to charge the applicant if a foreign credit report is found, in cents.
currency [string] The currency to charge your customer in. Currently, only USD is supported.

Using ID Aliases

To save you having to manage Nova Credit IDs in the form of product_id and public_id, where you are a Parent who manages multiple customers, you can substitute both IDs for your own providing they've been communicated to your Nova Credit Account Manager. Both parameters can be passed in the body. Please consult your Nova Credit Account Manager upon setting up.

productIdAlias [string] The ID you use internally to identify the product that the applicant is applying for
publicIdAlias [string] The ID that you use internally to identify each one of your Child customer accounts. This is used by Parents and is passed in the body. When a publicIdAlias is provided, you do not need to pass in X-PUBLIC-ID in the header

Managing multiple accounts

If you're a Parent account that is managing multiple Child accounts, you can reduce the upfront configuration work by simply passing in the account name and associated product name in the body of the request. To do so, you would add the following two fields.‍

productName [string] The external name of the product the applicant is applying for. When a productName is provided, you do not need to pass in productId in the body. Note that passing a productName that does not exist will create a new product that the applicant will apply for.
accountName [string] The name of the customer. This is used by Parents and is passed in the body. When an accountName is provided, you do not need to pass in X-PUBLIC-ID in the header, but productName becomes required. Note that passing an accountName that does not exist will create a new account that the applicant will apply for.

Optional body parameters

There are several optional parameters you may include in the request body. Some allow the NovaConnect widget to be prefilled based on information you already have about your applicant, so they don't need to enter it again. Others can be used to determine invite endpoint configurations.

applicantDateOfBirth [string] The applicant's date of birth, in the format YYYY-MM-DD. This should only be sent if you include it in enabledPrefills.
applicantSourceCountry [string] Provide an ISO country code to load NovaConnect with a pre-specified country. This must be one of your enabled countries. This should only be sent if you include it in enabledPrefills.
emailTemplate [string] See below 'Choosing an email template' for description
enabledPrefills [array] See below 'Enabling prefilling' for description
externalId [string] Pass in a unique internal identifier for your own records. It will be provided in our webhook call and can be used to retrieve the report
userArgs [string] Pass in an identifier for your own records. It will be provided in our webhook call if specified in the callback and in the API JSON response.

Enabling prefilling

To enable prefilling for NovaConnect widgets sent via the invite endpoint, include the enabledPrefills key in your request body. enabledPrefills should be an array that is a list of what you would like to prefill.

The prefill options are:

applicantFirstName
applicantLastName
applicantEmail
applicantDateOfBirth
applicantSourceCountry

You may include one, multiple, or all of the available keys to prefill. Note that any keys you specify in enabledPrefills that you do not send data for will not be prefilled.

Choosing an email template

To determine an email template to be sent to the applicant, include the emailTemplate key in your request body. The value should be a string that matches one of the strings below, each representing a different email template that can be sent out.

Acceptable emailTemplate values:

INVITE: sends the default 'invite-style' template inviting someone to go through NovaConnect
OFFER: sends an 'offer-style' template with conditional approval language and an invitation to go through NovaConnect

The string is case-insensitive, but must match one of the values above. The default email template INVITE is sent out should you choose not to use the emailTemplate key.

Possible responses‍‍

200 (OK) The newly created application_id for the invite is returned. This is simply a reference to confirm that the invite was received and sent.
403 (Forbidden) Unauthorized request. Your client_id or secret_key was incorrect, or you did not correctly base-64 encode it.
400 (Bad Request) Malformed request, headers or missing required parameters. Error will be one of MALFORMED_HEADERS or MALFORMED_BODY.

Example request

curl -X POST \
    https://api.novacredit.com/connect/invite \
    -H 'Content-Type: application/json' \
    -H 'X-PUBLIC-ID: aa2eebe1-c02a-11e6-88fa-fbe350f5820f'
    -H 'Authorization: Basic YWU2Y2VkNjktOGFmOC00N2M5LWE5YTItZjI3NjA4OWI0ZjBlOmY4OGRiNzViODNkOWYwMDhkODJhNTRmOWRkODkwOTdkM2ZkM2Y4OWRlYzFjOTZiMTJkNzFjZjQyNjRhMmE0ZTY='
    -d '{
        "applicantFirstName": "Raj",
        "applicantLastName": "Du",
        "applicantEmail": "raj@email.com",
        "applicantSourceCountry": "IND",
        "chargeAmount": 6500,
        "productIdAlias": "3c2da600-17ee-11e8-8a0e-5158039db37e",
        "currency": "USD",
        "userArgs": "custom_id:3c2da600",
        "externalId": "internal_identifier",
        "enabledPrefills": ["applicantFirstName", "applicantLastName", "applicantEmail", "applicantDateOfBirth", "applicantSourceCountry"]
    }'

Example response

{
    "applicationId": "69de1309-6c0d-42a2-b2f1-3dff5bce10c1",
    "visitId": "1455ad79-8b1e-4efd-a851-9507f61aa240"
}

NovaConnect Invite Link Endpoint

The invite link endpoint is similar to the invite endpoint, and may be used to only generate a link that will redirect a user to NovaConnect, rather than sending an email to an applicant. The invitation link returned by the endpoint can be copied and pasted into a new brower tab to bring the applicant to a pre-configured NovaConnect widget hosted on Nova Credit's domain. Once the applicant completes NovaConnect, their reports are accessible via the API.

POST https://api.novacredit.com/connect/invite-link

Required headers‍

X-PUBLIC-ID Your Nova Credit public_id, found on your Nova Credit Dashboard. (Unless using Managing multiple accounts method below.)
Authorization Basic Auth, containing the base-64 encoded string of your client_id:secret_key.
Content-Type application/json.

‍Required body parameters

applicantFirstName [string] The first name of the applicant.
applicantLastName [string] The last name of the applicant.
applicantEmail [string] The email address of the applicant.
productId [string] The product_id associated with the product the applicant is applying for. (Unless using Managing multiple accounts method below.)

If applicant billing is enabled:

chargeAmount [number] The amount to charge the applicant if a foreign credit report is found, in cents.
currency [string] The currency to charge your customer in. Currently, only USD is supported.

Using ID Aliases

productIdAlias [string] The ID you use internally to identify the product that the applicant is applying for
publicIdAlias [string] The ID that you use internally to identify each one of your Child customer accounts. This is used by Parents and is passed in the body. When a publicIdAlias is provided, you do not need to pass in X-PUBLIC-ID in the header

Managing multiple accounts

productName [string] The external name of the product the applicant is applying for. When a productName is provided, you do not need to pass in productId in the body.
accountName [string] The name of the customer. This is used by Parents and is passed in the body. When an accountName is provided, you do not need to pass in X-PUBLIC-ID in the header, but productName becomes required.

Optional body parameters

applicantDateOfBirth [string] The applicant's date of birth, in the format YYYY-MM-DD. This should only be sent if you include it in enabledPrefills.
applicantSourceCountry [string] Provide an ISO country code to load NovaConnect with a pre-specified country. This must be one of your enabled countries. This should only be sent if you include it in enabledPrefills.
enabledPrefills [array] See below 'Enabling prefilling' for description
externalId [string] Pass in a unique internal identifier for your own records. It will be provided in our webhook call and can be used to retrieve the report
userArgs [string] Pass in an identifier for your own records. It will be provided in our webhook call if specified in the callback and in the API JSON response.

Enabling prefilling

The prefill options are:

applicantFirstName
applicantLastName
applicantEmail
applicantDateOfBirth
applicantSourceCountry

You may include one, multiple, or all of the available keys to prefill. Note that any keys you specify in enabledPrefills that you do not send data for will not be prefilled.

Possible responses‍‍

200 (OK) The newly created application_id for the invite is returned, as well as an inviteLink that hosts the NovaConnect widget.
403 (Forbidden) Unauthorized request. Your client_id or secret_key was incorrect, or you did not correctly base-64 encode it.
400 (Bad Request) Malformed request, headers or missing required parameters. Error will be one of MALFORMED_HEADERS or MALFORMED_BODY.

Example request

curl -X POST \
https://api.novacredit.com/connect/invite-link \
-H 'Content-Type: application/json' \
-H 'X-PUBLIC-ID: aa2eebe1-c02a-11e6-88fa-fbe350f5820f'
-H 'Authorization: Basic YWU2Y2VkNjktOGFmOC00N2M5LWE5YTItZjI3NjA4OWI0ZjBlOmY4OGRiNzViODNkOWYwMDhkODJhNTRmOWRkODkwOTdkM2ZkM2Y4OWRlYzFjOTZiMTJkNzFjZjQyNjRhMmE0ZTY='
-d '{
    "applicantFirstName": "Raj",
    "applicantLastName": "Du",
    "applicantDateOfBirth": "1990-12-01",
    "applicantEmail": "raj@email.com",
    "applicantAddress": "123 Main Street",
    "applicantCity": "San Francisco",
    "applicantState": "CA",
    "applicantZipCode": "12345",
    "emailTemplate": "INVITE_VOI",
    "productId": "3c2da600-17ee-11e8-8a0e-5158039db37e",
    "userArgs": "custom_id:3c2da600"
}'

Example response

{
    "applicationId": "69de1309-6c0d-42a2-b2f1-3dff5bce10c1",
    "visitId": "1455ad79-8b1e-4efd-a851-9507f61aa240",
    "inviteLink": "https://api.novacredit.com/r/12345"
}

NovaConnect Suppliers Endpoint

The suppliers endpoint can be used to retrieve a list of active data suppliers for your account.

GET https://api.novacredit.com/connect/suppliers

Required headers

Authorization Basic Auth, containing the base-64 encoded string of your client_id:secret_key.
Content-Type application/json.

Example request

curl -X GET \
  https://api.novacredit.com/connect/suppliers \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Basic YWU2Y2VkNjktOGFmOC00N2M5LWE5YTItZjI3NjA4OWI0ZjBlOmY4OGRiNzViODNkOWYwMDhkODJhNTRmOWRkODkwOTdkM2ZkM2Y4OWRlYzFjOTZiMTJkNzFjZjQyNjRhMmE0ZTY=' \

Example response

{
  "suppliers": [
    {
      "countryName": "India",
      "countryCode": "IND",
      "bureauName": "CRIF Highmark",
      "bureauCode": "IND_CHM"
    },
    {
      "countryName": "Mexico",
      "countryCode": "MEX",
      "bureauName": "Circulo de Credito",
      "bureauCode": "MEX_CDC"
    }
}

NovaConnect Browser Support

Desktop

Google Chrome - fully supported
Mozilla Firefox - Versions 29 & up
Safari - Versions 8 & up
Opera - Versions 42 & up
Microsoft Edge - Versions 14 & up

Mobile

Include the following script in your HTML's <head></head> tag to ensure that content scales correctly on smaller screens:

<meta name="viewport" content="width=device-width, initial-scale=1.0">

Nova Credit Dashboard Access

The Nova Credit Dashboard is used to manage your account, such as accessing your Account Keys and viewing applications.

Additionally, there is a "Request Report" feature to invite to your consumers which can be used instead of the Invite or Invite Link endpoints.

Optionally integrate with your SSO provider: Single Sign-On documentation

Change Log

2025 January

Updated references to X-ENVIRONMENT headers and added information about the new sandbox URL. Note that this header is backwards compatible, and therefore will still work.

Introduction​

Credentials & Identifiers​

Account Keys​

Programmatically generated tokens​

Sandbox & Production Environments​

Available environments​

X-ENVIRONMENT header (Deprecated)​

Client-Side Integration​

Step 1: Product configuration​

Step 2: Add NovaConnect to your page​

Custom Trigger Version​

NovaConnect Required Parameters​

NovaConnect Optional Parameters​

Available Prefill Keys (optional)​

Using Client-Side Hooks (optional)​

onSuccess​

onExit​

onError description & error types​

Example HTML file that utilizes the full list of configuration options:​

Server-Side Integration​

Step 1: Set-up your webhooks​

Step 2: Get an access token​

Step 3: Request a Credit Passport®​

Encrypted Payload Implementation​

GET /connect/jwkset​

NovaConnect Initialization​

Step 1: Call the initialization endpoint​

Step 2: Pass the initialization token to NovaConnect​

NovaConnect Initialization - Encrypted Payload​

Step 1: Encryption of payload​

Using a third party library​

Step 2: Call the initialization endpoint​

Step 3: Pass the initialization token to NovaConnect​

NovaConnect Invite Endpoint​

NovaConnect Invite Link Endpoint​

NovaConnect Suppliers Endpoint​

NovaConnect Browser Support​

Desktop​

Mobile​

Nova Credit Dashboard Access​

Change Log​

2025 January​

Introduction

Credentials & Identifiers

Account Keys

Programmatically generated tokens

Sandbox & Production Environments

Available environments

X-ENVIRONMENT header (Deprecated)

Client-Side Integration

Step 1: Product configuration

Step 2: Add NovaConnect to your page

Custom Trigger Version

NovaConnect Required Parameters

NovaConnect Optional Parameters

Available Prefill Keys (optional)

Using Client-Side Hooks (optional)

onSuccess

onExit

onError description & error types

Example HTML file that utilizes the full list of configuration options:

Server-Side Integration

Step 1: Set-up your webhooks

Step 2: Get an access token

Step 3: Request a Credit Passport®

Encrypted Payload Implementation

GET /connect/jwkset

NovaConnect Initialization

Step 1: Call the initialization endpoint

Step 2: Pass the initialization token to NovaConnect

NovaConnect Initialization - Encrypted Payload

Step 1: Encryption of payload

Using a third party library

Step 2: Call the initialization endpoint

Step 3: Pass the initialization token to NovaConnect

NovaConnect Invite Endpoint

NovaConnect Invite Link Endpoint

NovaConnect Suppliers Endpoint

NovaConnect Browser Support

Desktop

Mobile

Nova Credit Dashboard Access

Change Log

2025 January