Onboarding via Web Component [BETA]
Beta notice
This feature is currently in beta, subject to change, and only available upon customer requests. If you are an eligible partner of Monite and would like to try out the Onboarding Web Component, please contact your Account Manager at Monite.
Overview
Monite provides a full-featured web component for entity onboarding that you can embed into your applications. It allows your customers to complete payments onboarding without leaving your application. The onboarding component uses Monite API to fetch the onboarding requirements and generates a multi-step interface where the the users can fill in all the necessary information required for the entity to make or receive payments via Monite payment rails.
Flow diagram
The following diagram shows a typical way to implement the payments onboarding flow by using Monite's Onboarding Web Component.
Payments onboarding flow
Usage
1. Create an entity
This guide assumes that the entity to be onboarded must have already been created in Monite. To learn how to create entities, see Entities.
The Onboarding Web Component supports only entities from the EU and UK. To onboard US-based entities, use the hosted onboarded page.
There is no need to create entity bank accounts or persons in advance - the Onboarding Web Component itself will collect this information for you. However, if you have already collected this information upfront (for example, during the entity registration flow in your application), the Onboarding Web Component will skip the corresponding steps.
2. Create an entity user and role for onboarding
The Onboarding Web Component requires an entity user's access token for authentication. This means that at least one user must have been created for the entity. This user can be, for example, the business owner or an authorized representative. To learn how to create entity users, see Entity users.
The user's role must include the following permissions required to provide the onboarding information:
entity:readandupdateentity_bank_account:create,read,update,deleteonboarding:create,read,updateperson:create,read,update,delete
User role JSON
{
"name": "Role for entity onboarding",
"permissions": {
"objects": [
{
"object_type": "entity",
"actions": [
{
"action_name": "read",
"permission": "allowed"
},
{
"action_name": "update",
"permission": "allowed"
}
]
},
{
"object_type": "entity_bank_account",
"actions": [
{
"action_name": "read",
"permission": "allowed"
},
{
"action_name": "create",
"permission": "allowed"
},
{
"action_name": "update",
"permission": "allowed"
},
{
"action_name": "delete",
"permission": "allowed"
}
]
},
{
"object_type": "onboarding",
"actions": [
{
"action_name": "create",
"permission": "allowed"
},
{
"action_name": "read",
"permission": "allowed"
},
{
"action_name": "update",
"permission": "allowed"
}
]
},
{
"object_type": "person",
"actions": [
{
"action_name": "read",
"permission": "allowed"
},
{
"action_name": "create",
"permission": "allowed"
},
{
"action_name": "update",
"permission": "allowed"
},
{
"action_name": "delete",
"permission": "allowed"
}
]
}
]
}
}
3. Enable payment methods for the entity
The next step to is to specify which payment methods the entity is going to use. Payment methods determine which information the entity needs to provide to complete its onboarding.
For more information, see Enable payment methods for an entity.
4. Display the Onboarding Web Component
The way you can embed the onboarding component into your application depends on whether you use Monite React SDK or Drop-in library.
import { MoniteSDK } from '@monite/sdk-api';
import { MoniteProvider, Onboarding } from "@monite/sdk-react"
// A function that retrieves user access tokens.
// See: https://docs.monite.com/docs/react-sdk-quick-start#2-authentication
const fetchToken = async () => {
...
}
// Initialize the SDK
const monite = new MoniteSDK({
apiUrl: 'https://api.sandbox.monite.com/v1', // Or 'https://api.monite.com/v1' to use Production
entityId: 'ENTITY_ID',
fetchToken: fetchToken
});
function App() {
return (
<MoniteProvider monite={monite} locale={{ code: "en-US" }}>
<Onboarding />
</MoniteProvider>
);
}
export default App;
<script type="module" async src="https://cdn.sandbox.monite.com/monite-app.js"></script>
...
<monite-app
entity-id="ENTITY_ID"
api-url="https://api.sandbox.monite.com/v1"
component="onboarding"
basename="/"
>
<script slot="fetch-token">
// A function that retrieves user access tokens.
// See: https://docs.monite.com/docs/drop-in-quick-start#4-set-up-user-authentication
async function fetchToken() {
...
}
</script>
</monite-app>
For more information on installing and using the Monite React SDK and Drop-in library, see:
5. Track the onboarding status
After the entity user has filled in the information requested by the Onboarding Web Component, Monite sends the entity.onboarding_requirements.updated and entity.onboarding_requirements.status_updated webhooks to your server. You can then check the entity's onboarding status by calling GET /onboarding_requirements.
In a success scenario, the verification_status for each payment method will be "enabled".
If the response from GET /onboarding_requirement indicates any pending onboarding requirements or verification errors, you can inform the user and repeat the onboarding process to collect the missing information.
Customization
The Onboarding Web Component supports theming and customization. For more information, see:
User interface
The onboarding UI provided by the component includes several steps. The steps vary depending on the entity type - organization or individual. Some steps and input fields may be hidden if the necessary information has already been provided for the entity (for example, previously provided via API).
Company details
On the first screen, the user is asked to provide one or more of the following: company phone number, company tax number (if applicable), company address.
This screen is not displayed if this information was already provided during the entity creation.
Business details
On this screen, the user is asked to specify the Industry and Website of their business.
- The industry corresponds to the merchant category code (MCC).
- The website URL must include
http(s)://, for example,https://example.com.
Verify you represent your business
This screen is displayed only for organization-type entities.
It prompts for the information about the primary owner of the business. The user needs to provide the owner's name, date of birth, address, whether that person owns or less than 25% of the business, whether or not they are the sole owner, and other details.
Business owners
This screen is displayed only for organization-type entities and if the user specified that there are several persons who own more than 25% of the business. The user needs to provide information about other owners of the business. Owners are individuals who either own 25% or more of a company or exercise significant control over it. The latter refers to persons responsible for managing and directing the business, such as executive officers, senior managers, CEO, CFO, COO, President, Vice Presidents, and similar.
Business directors
This screen is displayed only for organization-type entities.
The user is asked to provide a list of the company's directors (if any). Directors are typically members of the company's governing board.
Business owners added on the previous screen can be selected as directors if applicable.
Business executives
This screen is displayed only for organization-type entities.
The user is asked to provide a list of company's executives (if any). Executives are persons with significant responsibility to control, manage, or direct the business.
Business owners and directors that were previously added can be selected as executives if applicable.
Bank account
On this screen, the user is asked to provide information about the bank account that the entity will use to make or accept payments.
If the entity already has a bank account defined, the screen instead displays the details of that bank account so the user can review them and update if needed.
Note
Only EUR, USD, and GBP bank accounts are supported for payments.
Terms and conditions
On this screen, the user is asked to accept the terms and conditions for using Monite payment rails.
Upload documents
Depending on the entity type and country, the user may be required to provide scans of documents as proof of identity, address, and business registration. Some document types may require scans of both the front and back of the document.
Verification submitted
This is the last screen that indicates that the information provided by the user has been successfully submitted to Monite.
Updated 2 days ago