Implementation
Basic Implementation
This step-by-step guide walks you through everything needed to integrate Unit's Ready-to-Launch banking product. To get started, make sure you’ve signed up for Unit’s Sandbox environment—if you haven’t yet, please do so before proceeding.
Embedding
If you have not done so already, embed the Ready-to-Launch component into your app.
- Add the script tag below to your HTML header
<script async src="https://ui.s.unit.sh/release/latest/components-extended.js"></script>
In the production environment, use https://ui.unit.co/release/latest/components-extended.js as the script source.
- Add a new page to your app that will host the Ready-to-Launch banking experience. Paste the code below to the new page.
<unit-elements-white-label-app jwt-token="demo.jwt.token"></unit-elements-white-label-app>
You may choose to create unit-elements-white-label-app dynamically using JavaScript:
<html>
<head>
<script
async
src="https://ui.unit.co/release/latest/components-extended.js"
></script>
</head>
<body>
<div id="unit-app-placeholder"></div>
<script>
const unit = document.createElement("unit-elements-white-label-app");
unit.setAttribute("jwt-token", "demo.jwt.token");
document.querySelector("#unit-app-placeholder").append(unit);
</script>
</body>
</html>
Authentication
In order to seamlessly authenticate with Unit's Ready-to-Launch Banking app, you need to pass it a JWT, that allows us to identify your user and verify that they are logged in.
Unit will not ask the user to log in using a separate set of credentials. However, before performing any sensitive banking activities, we will OTP the user.
In sandbox, please use code 000001 to complete the OTP.
Configuring your identity provider
If you use one of the following identity providers: Okta, Auth0, AWS Cognito, Stytch - follow the steps below. Otherwise, please follow the steps detailed in Unit’s custom jwt authentication guide.
Log into Unit's dashboard.
- Under "Developer", go to "Org settings"
- Under "JWT settings", choose the identity provider you use from the "Provider" drop down.
- Paste the JWKs Path in the JWKs Field.
Passing The JWT
Pass your JWT to Unit's banking component (see example below), replacing the static token that was previously there.
<unit-elements-white-label-app jwt-token="{{JwtToken}}"></unit-elements-white-label-app>
Cleanup
Ready-to-Launch Banking will use 2 keys in local storage: unitCustomerToken and unitVerifiedCustomerToken. It's important to clean them up when the user logs out from your app.
localStorage.removeItem("unitCustomerToken");
localStorage.removeItem("unitVerifiedCustomerToken");
Content Security Policy
If you are using a Content-Security-Policy (CSP) header, you may need to add the following directives to allow the web components to work correctly:
<meta
http-equiv="Content-Security-Policy"
content="connect-src 'self' https://*.s.unit.sh https://*.unit.co"
/>
Optimized Implementation
The following are optional implementation steps that can be taken to optimize the branding, streamline the end customer experience, and provide access to richer functionality.
Pre filling end-user information [Recommended]
If you have access to end customer information that you can share in order to streamline their onboarding onto banking and can reduce the friction of submitting the application, we allow you to provide it and we will use it to pre-fill the end customer’s application form. To support that, you will have to expose an API endpoint that Unit will call when seeing an end user (identified by their JWT subject) for the first time.
Unit will make an HTTP request to this endpoint with a JWT token associated with this user in the Authorization header before initiating the end customer application process. The server will need to return the End User Configuration resource. The response must include the data, type: whiteLabelAppEndUserConfig and attributes keys.
Please contact Unit in order to configure the endpoint.
Request example:
curl -X GET 'https://yourdomain.com/unit/application-form-prefill' \
-H "Authorization: Bearer ${JWT Token}"
Inviting additional users to Banking [Optional]
In order to allow more than one end user of yours access to the same banking experience (e.g. two employees of the same business, represented as two separate JWT subjects on your platform), The user that applies for banking, once approved, needs to be able to invite additional users.
Since Unit isn’t familiar with the relationship between users on your platform, we rely on you to tell us who the users are that another user may grant access to, by providing an API endpoint we can call, that returns a list of users, represented as JWTs.
Unit relies on you to manage and define user roles effectively. Below are the responsibilities and requirements for user management and role assignment within the Ready-to-Launch Banking App.
Role Assignment via JWT Token
Each user in Ready-to-Launch Banking has an assigned role, which your backend is responsible for managing. The end customer can create users in the White-Label App and assign roles to them. To update a user’s role, include the new role in a unitRole attribute in the JWT token. Unit validates the JWT token on a user login: if a role is provided in the token, Unit will update the user’s role in the White-Label App accordingly. If a role is not provided in the JWT token, Unit will retain the last role that was sent.
Allowed Roles
The only allowed roles are Admin and ReadOnly. If you include a role other than these in the JWT token, the request will fail.
Managing End Users
The White-Label App provides functionality for creating, removing, and listing users within the app. The customer can manage all types of users. Admin can only manage users who has ReadOnly permissions. To enable these capabilities, you will need to implement an API endpoint that returns a list of your app's existing end-users.
API Endpoint Requirements
Request: Unit will send an HTTP request to the API endpoint that you will implement, including a JWT token in the Authorization header.
curl -X GET 'https://yourdomain.com/unit/users' \
-H "Authorization: Bearer ${JWT Token}"
Response: The API must return a list of end-users associated with the customer resource created at Unit. Each end-user in the list should be represented as an object and include their unique JWT subject. By adhering to these guidelines, you will ensure consistent user role management within the White-Label App.
Field Type Description fullName FullName Full name of the end user. email string Email address of the end user. phone Phone Phone number of the end user. jwtSubject string See this section for more information. unitRole string The role of the end user. Can be either Admin or ReadOnly.
Example whiteLabelAppEndUser type:
[
{
"data": {
"type": "whiteLabelAppEndUser",
"attributes": {
"fullName": {
"first": "Peter",
"last": "Parker"
},
"email": "peter.parker@parker.com",
"phone": {
"countryCode": "1",
"number": "2345678888"
},
"jwtSubject": "test",
"unitRole": "Admin"
}
}
},
{
"data": {
"type": "whiteLabelAppEndUser",
"attributes": {
"fullName": {
"first": "April",
"last": "Oneil"
},
"email": "april.oneil@parker.com",
"phone": {
"countryCode": "1",
"number": "2345678899"
},
"jwtSubject": "test2",
"unitRole": "ReadOnly"
}
}
}
]
After the endpoint has been implemented on your side, please contact Unit in order to configure it.
Custom JWT Authentication
Unit can rely on a custom implementation of JWT token that adheres to the specifications outlined in RFC 7519.
In this case you should provide Unit with a public key that will be used to validate the token.
The token must be signed using the RS256 algorithm and must include the following claims:
| Claim | Description |
|---|---|
sub | A unique identifier for the end-user |
exp | The expiration time of the token |
iss | The issuer of the token |
Theming
Follow the theming guide