Overview
If you are managing users, then they do not log in through the widget. Instead, you create your own registration screen utilizing our API. You can also create your own screens for the identity verification process (SMS one-time-code and identity quiz questions). You can merge the CRS registration & identity process with your own service's registration, but you have to adhere to the compliance guide for screens.
You can have screens for the identity verification process for SMS one-time-code and identity quiz questions. Also, it is possible to merge the CRS registration/identity process with your own service's registration, as long as you follow the compliance guide for these screens.
If a customer wants to create their own UI for the identity verification process, they simply need to continue the API steps in the "Getting Started" Postman Collections (Consumer Credit - Getting Started - New User.postman_collection.json and Consumer Credit - Getting Started - Returning User.postman_collection.json) with their custom screens until idpass is true, before they have the user's device redeem the preauth for the widget. If idpass is true for a user whose preauth token is redeemed using the widget, then the widget will render that user's credit dashboard (skipping the id verification process). If the user's device were to redeem the preauth token when idpass equals false, then the widget renders the built in widget screens for the identity verification process.
Simple Integration Guide
Web Integration Requirements:
- API Key
- Host Registration (eg your web site address)
- Integration Host & parameters
- Configuration Flags
- Primary Theme Color (six character hex, without #)
- Logo URL (URL of a logo to replace the CRS logo)
- Pre-auth token – optional if using postmessage configuration
Only the registered host can serve the UI with the designated API Key. Embed iFrame on a blank page under the registered host. Style the iFrame/page to suit your needs
To embed into HTML, create an iframe as shown in the following example with its src reflecting this color-coded URL:
"https://efx-dev.stitchcredit.com/api/users/start?key=[API-KEY]&token=[PREAUTH-TOKEN]&ocf=[FLAGS]&oct=[COLOR]&ocl=[LOGO-URL]"
Advanced Embedded Pages with Messaging
Using more advanced embedded pages with messaging can facilitate communication between your primary application and the embedded CRS application. This technique allows customer applications to react to changes and events in the CRS application.
The customer needs to implement AJAX preauth token generation function; the “getData” implementation shown in the Sample files only works in the testing environment and will not work in production. True user authentication and processing must be done server-side.
Sample files show possible usage and event handling.
API Process Flow
A token from /direct/login is required for all other Direct API end-points in yellow. It is a bearer authorization token.
Once you have a preauth token, returned from /direct/user-reg or /direct/preauth-token, pass it to the Web UI entry point in the embedded iFrame.
Be sure to save the ID returned from /direct/user-reg or you won’t be able to reauthorize the user when they return.
**The preauth token is only valid for 30 seconds
The Web Widget must perform the necessary exchange of information via the corresponding APIs. This diagram shows the API process flow.
eCredit Monitoring Communication & Token Flow
The diagram shows the communication exchange that must occur between the consumer, your servers (marked Customer Servers), CRS servers (marked CRS Tech Servers) and the Equifax Servers.
Webhook Integration
Webhooks are available to notify you when an alert (or other notifications) comes in so that you can message users in whatever fashion you wish to return to your site.
Please refer to additional details on Webhook Integration.
Web Messaging Integration
To interact with the Consumer Credit Widget, you will need to implement a structure using a window event listener.
Please refer to additional details on Web Messaging Integration.
Postman Collections
Access Credentials have been sent to you in a Postman Environment upon registration via email. The Postman Environment is pre-configured to allow you to use the scripts and walk through the Postman Scripts with minimal intervention to aid in understanding the API call structure.
Consumer Credit Postman Collections include pre-defined API calls to help you understand and develop your solution. See the Test API Postman Collection for additional documentation.
Samples
Here is an implementation of the Sample iFrame page with inline user token:
<html>
<head>
<title>eCredit Monitoring</title>
<meta name="description" content="StitchCredit Consumer Credit Reports"/>
<link rel="icon" href="/favicon.ico">
<style>
body { background: #F9FAFB; }
#sc-iframe { border: none; overflow: hidden; padding: 0px; margin: 0px; width: 100%; height: 100vh; z-index: 1; position: absolute; left: 0; top: 0; }
</style>
</head>
<body>
<iframe id="sc-iframe"
src=“https://efx-dev.stitchcredit.com/login-direct?key=[API-KEY]&token=[PREAUTH-TOKEN]&ocf=[FLAGS]&oct=[COLOR]&ocl=[LOGO-URL]”
width=“100%” height=“100vh” frameborder=“0”>
</iframe>
</body>
</html>
Here is a sample implementation of an advanced embedded page with messaging: the Tabbed User Interface with Dynamic Consumer Authentication integration (direct_sample.html):
<html>
<head>
<title>eCredit Monitoring</title>
<link rel="icon" href="/favicon.ico" />
<meta name="description" content="CRS Consumer Credit Reports" />
<meta
name="viewport"
content="minimum-scale=1, initial-scale=1, width=device-width"
/>
<style>
html,
body {
margin: 0;
padding: 0;
position: relative;
background: #eeeeee;
}
#sc-iframe {
margin: 0;
padding: 0;
z-index: 1;
width: 100%;
height: 100vh;
border: none;
overflow: hidden;
}
</style>
</head>
<body>
<iframe
id="sc-iframe" allowTransparency="true"
src="https://efx-dev.stitchcredit.com/login-direct?key=5a10e0d7-1dc8-4325-929f-d0d131990527&ocf=2039"
></iframe>
<script>
//this just throws in a default ID if one isn't provided on the query string
const id = document.location.search.length > 0 ? document.location.search.split('&')[0].split('=')[1] : '048741d2-3dcf-4892-8fb0-99930a540cc1';
console.log("ID: ",id);
console.log("Loading Message Listener...");
window.addEventListener("message", receiveMessage, false);
function receiveMessage(event) {
if(event && event.source && event.data) {
// You only need to implement the types that are important/relevant to your use case.
if(event.data.type === 'AUTH_REQUIRED') {
//The iframe clident will post this message when a valid preauth token does not exist.
//Posting a proper message with a preauth token in response allows the client to continue seemlessly.
//console.log("Auth Required Event Received");
const es = event.source;
//this code uses a test endpoint on the server to provide a preauth-token for any user ID without the usual hurdles.
//This is ONLY for testing and does not exist in the production environment.
getData("https://efx-dev.stitchcredit.com/api/test/preauth-token/"+id, function() {
const token = JSON.parse(this.responseText).token;
console.log("Status: ", this.status, ", token: ", token);
es.postMessage({type: 'PREAUTH', token: this.status == 200 ? token : null},"*");
});
}
else if(event.data.type === 'REG_STARTED') {
const es = event.source;
//only valid for full web implementation, Direct API already creates the customer, so this will never happen in those instances
// (new Date().valueOf()) - is used to generate a new email ID on the fly for testing purposes
es.postMessage({type: 'REG', data: {fname:"Gertrude", lname:"Harkenreadeo", email: "test+" + (new Date().valueOf()) + "@test.com"}},"*");
}
else if(event.data.type === 'IDENTITY_STARTED') {
const es = event.source;
//You could use this function to pre-populate the given fields. DoB and SSN will never be prepopulated as it violates compliance
// new Date().valueOf().toString() - generates a unique number for street2 to ensure each run goes through the full identity process, remove to test sequential sign up of the same user
es.postMessage({type: 'IDENTITY', data: {street1:"305 Linden Av", street2: new Date().valueOf().toString(), city: "Atlanta", state: "GA", zip: "30316", mobile: "0000000000"}},"*");
}
else if(event.data.type === 'LOGIN_SUCCESSFUL') {
console.log("User succesfully logged in");
}
else if(event.data.type === 'LOGIN_FAILED') {
//if you see this message more than a few times in a row, it's likely an issue
//typically this will only occur for full web implementations, not Direct API
console.log("User login failed");
}
else if(event.data.type === 'USER_ENROLLED') {
//User successfully completed identity and has been enrolled for consumer data
console.log("User enrollment successful");
}
else if(event.data.type === 'IDENTITY_FAILED') {
//Identity process failed, user is likely "stuck" as they cannot continue
console.log("User identity failure");
}
else if(event.data.type === 'SERVICE_FAILURE') {
//Identity process failed most likely due to a service outage, but the user is stuck as they cannot continue without passing identity
console.log("Identity service failure");
}
}
function getData(req, action) {
var xhr = new XMLHttpRequest();
xhr.responesType = 'json';
xhr.onload = action;
xhr.open("GET", req);
xhr.setRequestHeader("Content-Type", "application/json");
xhr.send();
}
}
</script>
</body>
</html>
Here is a sample implementation of an advanced embedded page with messaging: All-in-One User Interface with dynamic Consumer Authentication integration (aio_sample.html):
<html>
<head>
<title>eCredit Monitoring</title>
<link rel="icon" href="/favicon.ico" />
<meta name="description" content="CRS Consumer Credit Reports" />
<meta
name="viewport"
content="minimum-scale=1, initial-scale=1, width=device-width"
/>
<style>
html,
body {
margin: 0;
padding: 0;
position: relative;
background: #eeeeee;
}
#sc-iframe {
margin: 0;
padding: 0;
z-index: 1;
width: 100%;
height: 100vh;
border: none;
overflow: hidden;
}
</style>
</head>
<body>
<iframe
id="sc-iframe" allowTransparency="true"
src="https://efx-dev.stitchcredit.com/login-aio?key=5a10e0d7-1dc8-4325-929f-d0d131990527&ocf=2039"
></iframe>
<script>
//this just throws in a default ID if one isn't provided on the query string
const id = document.location.search.length > 0 ? document.location.search.split('&')[0].split('=')[1] : '988a6fd7-7297-4757-8b96-907daa14a1f6';
console.log("ID: ",id);
console.log("Loading Message Listener...");
window.addEventListener("message", receiveMessage, false);
function receiveMessage(event) {
if(event && event.source && event.data) {
// You only need to implement the types that are important/relevant to your use case.
if(event.data.type === 'AUTH_REQUIRED') {
// The iframe clident will post this message when a valid preauth token does not exist.
// Posting a proper message with a preauth token in response allows the client to continue seemlessly.
// console.log("Auth Required Event Received");
const es = event.source;
// this code uses a test endpoint on the server to provide a preauth-token for any user ID without the usual hurdles.
// This is ONLY for testing and does not exist in the production environment.
getData("https://efx-dev.stitchcredit.com/api/test/preauth-token/"+id, function() {
const token = JSON.parse(this.responseText).token;
console.log("Status: ", this.status, ", token: ", token);
es.postMessage({type: 'PREAUTH', token: this.status == 200 ? token : null},"*");
});
}
else if(event.data.type === 'REG_STARTED') {
const es = event.source;
// only valid for full web implementation, Direct API already creates the customer, so this will never happen in those instances
// (new Date().valueOf()) - is used to generate a new email ID on the fly for testing purposes
es.postMessage({type: 'REG', data: {fname:"Gertrude", lname:"Harkenreadeo", email: "test+" + (new Date().valueOf()) + "@test.com"}},"*");
}
else if(event.data.type === 'IDENTITY_STARTED') {
const es = event.source;
// You could use this function to pre-populate the given fields. DoB and SSN will never be prepopulated as it violates compliance
// new Date().valueOf().toString() - generates a unique number for street2 to ensure each run goes through the full identity process, remove to test sequential sign up of the same user
es.postMessage({type: 'IDENTITY', data: {street1:"305 Linden Av", street2: new Date().valueOf().toString(), city: "Atlanta", state: "GA", zip: "30316", mobile: "0000000000"}},"*");
}
else if(event.data.type === 'LOGIN_SUCCESSFUL') {
console.log("User succesfully logged in");
}
else if(event.data.type === 'LOGIN_FAILED') {
// if you see this message more than a few times in a row, it's likely an issue
// typically this will only occur for full web implementations, not Direct API
console.log("User login failed");
}
else if(event.data.type === 'USER_ENROLLED') {
// User successfully completed identity and has been enrolled for consumer data
console.log("User enrollment successful");
}
else if(event.data.type === 'IDENTITY_FAILED') {
// Identity process failed, user is likely "stuck" as they cannot continue
console.log("User identity failure");
}
else if(event.data.type === 'SERVICE_FAILURE') {
// Identity process failed most likely due to a service outage, but the user is stuck as they cannot continue without passing identity
console.log("Identity service failure");
}
}
function getData(req, action) {
var xhr = new XMLHttpRequest();
xhr.responesType = 'json';
xhr.onload = action;
xhr.open("GET", req);
xhr.setRequestHeader("Content-Type", "application/json");
xhr.send();
}
}
</script>
</body>
</html>
Here is a sample implementation of an advanced embedded page with messaging: Tile User Interface with dynamic Consumer Authentication integration (tile_sample.html):
<html>
<head>
<title>eCredit Monitoring</title>
<link rel="icon" href="/favicon.ico" />
<meta name="description" content="CRS Consumer Credit Reports" />
<meta
name="viewport"
content="minimum-scale=1, initial-scale=1, width=device-width"
/>
<style>
html,
body {
margin: 0;
padding: 0;
position: relative;
background: #eeeeee;
}
#sc-iframe {
display:block;
margin: 0 auto;
padding: 0;
z-index: 1;
width: 500px;
height: 675px;
border: none;
overflow: hidden;
}
</style>
</head>
<body>
<iframe
id="sc-iframe" allowTransaparency="true"
src="https://efx-dev.stitchcredit.com/login-tile?key=5a10e0d7-1dc8-4325-929f-d0d131990527&ocf=2039"
></iframe>
<script>
//this just throws in a default ID if one isn't provided on the query string
const id = document.location.search.length > 0 ? document.location.search.split('&')[0].split('=')[1] : '988a6fd7-7297-4757-8b96-907daa14a1f6';
console.log("ID: ",id);
console.log("Loading Message Listener...");
window.addEventListener("message", receiveMessage, false);
function receiveMessage(event) {
if(event && event.source && event.data) {
// You only need to implement the types that are important/relevant to your use case.
if(event.data.type === 'AUTH_REQUIRED') {
//The iframe clident will post this message when a valid preauth token does not exist.
//Posting a proper message with a preauth token in response allows the client to continue seemlessly.
//console.log("Auth Required Event Received");
const es = event.source;
//this code uses a test endpoint on the server to provide a preauth-token for any user ID without the usual hurdles.
//This is ONLY for testing and does not exist in the production environment.
getData("https://efx-dev.stitchcredit.com/api/test/preauth-token/"+id, function() {
const token = JSON.parse(this.responseText).token;
console.log("Status: ", this.status, ", token: ", token);
es.postMessage({type: 'PREAUTH', token: this.status == 200 ? token : null},"*");
});
}
else if(event.data.type === 'REG_STARTED') {
const es = event.source;
//only valid for full web implementation, Direct API already creates the customer, so this will never happen in those instances
// (new Date().valueOf()) - is used to generate a new email ID on the fly for testing purposes
es.postMessage({type: 'REG', data: {fname:"Gertrude", lname:"Harkenreadeo", email: "test+" + (new Date().valueOf()) + "@test.com"}},"*");
}
else if(event.data.type === 'IDENTITY_STARTED') {
const es = event.source;
//You could use this function to pre-populate the given fields. DoB and SSN will never be prepopulated as it violates compliance
// new Date().valueOf().toString() - generates a unique number for street2 to ensure each run goes through the full identity process, remove to test sequential sign up of the same user
es.postMessage({type: 'IDENTITY', data: {street1:"305 Linden Av", street2: new Date().valueOf().toString(), city: "Atlanta", state: "GA", zip: "30316", mobile: "0000000000"}},"*");
}
else if(event.data.type === 'LOGIN_SUCCESSFUL') {
console.log("User succesfully logged in");
}
else if(event.data.type === 'LOGIN_FAILED') {
//if you see this message more than a few times in a row, it's likely an issue
//typically this will only occur for full web implementations, not Direct API
console.log("User login failed");
}
else if(event.data.type === 'USER_ENROLLED') {
//User successfully completed identity and has been enrolled for consumer data
console.log("User enrollment successful");
}
else if(event.data.type === 'IDENTITY_FAILED') {
//Identity process failed, user is likely "stuck" as they cannot continue
console.log("User identity failure");
}
else if(event.data.type === 'SERVICE_FAILURE') {
//Identity process failed most likely due to a service outage, but the user is stuck as they cannot continue without passing identity
console.log("Identity service failure");
}
}
function getData(req, action) {
var xhr = new XMLHttpRequest();
xhr.responesType = 'json';
xhr.onload = action;
xhr.open("GET", req);
xhr.setRequestHeader("Content-Type", "application/json");
xhr.send();
}
}
</script>
</body>
</html>
Here is a sample implementation of an advanced embedded page with messaging: Tile User Interface with dynamic Consumer Authentication integration and configuration display flags override (tile_sample_score_only.html):
<html>
<head>
<title>eCredit Monitoring</title>
<link rel="icon" href="/favicon.ico" />
<meta name="description" content="CRS Consumer Credit Reports" />
<meta
name="viewport"
content="minimum-scale=1, initial-scale=1, width=device-width"
/>
<style>
html,
body {
margin: 0;
padding: 0;
position: relative;
background: #eeeeee;
}
#sc-iframe {
display:block;
margin: 0 auto;
padding: 0;
z-index: 1;
width: 500px;
height: 550px;
border: none;
overflow: hidden;
}
</style>
</head>
<body>
<iframe
id="sc-iframe" allowTransaparency="true"
src="https://efx-dev.stitchcredit.com/login-tile?key=5a10e0d7-1dc8-4325-929f-d0d131990527&ocf=1"
></iframe>
<script>
//this just throws in a default ID if one isn't provided on the query string
const id = document.location.search.length > 0 ? document.location.search.split('&')[0].split('=')[1] : '988a6fd7-7297-4757-8b96-907daa14a1f6';
console.log("ID: ",id);
console.log("Loading Message Listener...");
window.addEventListener("message", receiveMessage, false);
function receiveMessage(event) {
if(event && event.source && event.data) {
// You only need to implement the types that are important/relevant to your use case.
if(event.data.type === 'AUTH_REQUIRED') {
//The iframe clident will post this message when a valid preauth token does not exist.
//Posting a proper message with a preauth token in response allows the client to continue seemlessly.
//console.log("Auth Required Event Received");
const es = event.source;
//this code uses a test endpoint on the server to provide a preauth-token for any user ID without the usual hurdles.
//This is ONLY for testing and does not exist in the production environment.
getData("https://efx-dev.stitchcredit.com/api/test/preauth-token/"+id, function() {
const token = JSON.parse(this.responseText).token;
console.log("Status: ", this.status, ", token: ", token);
es.postMessage({type: 'PREAUTH', token: this.status == 200 ? token : null},"*");
});
}
else if(event.data.type === 'REG_STARTED') {
const es = event.source;
//only valid for full web implementation, Direct API already creates the customer, so this will never happen in those instances
// (new Date().valueOf()) - is used to generate a new email ID on the fly for testing purposes
es.postMessage({type: 'REG', data: {fname:"Gertrude", lname:"Harkenreadeo", email: "test+" + (new Date().valueOf()) + "@test.com"}},"*");
}
else if(event.data.type === 'IDENTITY_STARTED') {
const es = event.source;
//You could use this function to pre-populate the given fields. DoB and SSN will never be prepopulated as it violates compliance
// new Date().valueOf().toString() - generates a unique number for street2 to ensure each run goes through the full identity process, remove to test sequential sign up of the same user
es.postMessage({type: 'IDENTITY', data: {street1:"305 Linden Av", street2: new Date().valueOf().toString(), city: "Atlanta", state: "GA", zip: "30316", mobile: "0000000000"}},"*");
}
else if(event.data.type === 'LOGIN_SUCCESSFUL') {
console.log("User succesfully logged in");
}
else if(event.data.type === 'LOGIN_FAILED') {
//if you see this message more than a few times in a row, it's likely an issue
//typically this will only occur for full web implementations, not Direct API
console.log("User login failed");
}
else if(event.data.type === 'USER_ENROLLED') {
//User successfully completed identity and has been enrolled for consumer data
console.log("User enrollment successful");
}
else if(event.data.type === 'IDENTITY_FAILED') {
//Identity process failed, user is likely "stuck" as they cannot continue
console.log("User identity failure");
}
else if(event.data.type === 'SERVICE_FAILURE') {
//Identity process failed most likely due to a service outage, but the user is stuck as they cannot continue without passing identity
console.log("Identity service failure");
}
}
function getData(req, action) {
var xhr = new XMLHttpRequest();
xhr.responesType = 'json';
xhr.onload = action;
xhr.open("GET", req);
xhr.setRequestHeader("Content-Type", "application/json");
xhr.send();
}
}
</script>
</body>
</html>
Responsiveness Breakpoints
These are two main breakpoints we use to scale desktop, tablet, and mobile devices. Devices with a width larger than 960px will be treated as a desktop view, devices with smaller widths fall under tablet and mobile device scaling thus will be displayed as a mobile view. With that being said, the widget should scale well on small, medium, and large devices without issues.
Each breakpoint (a key) matches with a fixed screen width (a value):
- sm, small: 600px
- md, medium: 960px