Drop-in quick start

Get started with Monite’s Drop-in web component.

Overview

The fastest and recommended way to embed Monite’s UI into your web application is to utilize the Drop-in library, which contains pre-built JavaScript web components that can be integrated into almost all types of web apps.

To learn how this can be done, follow the steps in this tutorial.

Before you begin

Before proceeding with this tutorial, make sure you completed the steps in the Step 1: Get your credentials and Step 2: Implement server side guides.

1. Add monite to your app

The fastest way to add Monite to your app is to use NPM or Yarn to install Monite as a package:

$npm install @monite/sdk-drop-in

After installation via NPM or Yarn, you must import the SDK to use Monite’s Drop-in components in your application:

1import('@monite/sdk-drop-in').then(({ MoniteDropin }) => {
2 // ...
3});

2. Create a Drop-in instance

To create a Drop-in instance that contains the UI and configuration for the Drop-in components, add to your application:

1const dropinConfig = {
2 entityId: 'ENTITY_ID',
3 apiUrl: 'ENVIRONMENT_URL',
4 fetchToken: async function fetchToken() {...},
5};
6
7const dropin = new MoniteDropin(dropinConfig);
8
9dropin.create(component).mount(...);

Here, the apiUrl parameter should be set to the base URL for all routes in your application, but you can leave it empty in this tutorial.

Note that the entity-id parameter here should be automatically set to the entity ID you generated in Step 2: Implement server side.

The fetchToken function obtains the user authentication.

(Optional) Configure components

During the Drop-in instance creation, you can set the configuration of the components:

1const dropinConfig = {
2 entityId: 'ENTITY_ID',
3 apiUrl: 'ENVIRONMENT_URL',
4 componentSettings: {
5 receivables: {},
6 counterparts: {
7 customerTypes: ['customer'],
8 },
9 },
10
11 fetchToken: async function fetchToken() {...},
12};
13
14const dropin = new MoniteDropin(dropinConfig);
15
16dropin.create(component).mount(...);

Here are the components and respective parameters you can configure:

ParameterValues
pageSizeOptions15, 50, 100
ParameterValues
pageSizeOptions15, 50, 100
ParameterValues
pageSizeOptions15, 50, 100
customerTypescustomer, vendor
ParameterValues
pageSizeOptions15, 50, 100
ParameterValues
pageSizeOptions15, 50, 100
ParameterValues
pageSizeOptions15, 50, 100
ParameterValues
pageSizeOptions15, 50, 100
ParameterValues
pageSizeOptions15, 50, 100

(Optional) Theming

You can customize the theme of the component as shown:

1const dropinConfig = {
2 entityId: 'ENTITY_ID',
3 apiUrl: 'ENVIRONMENT_URL',
4 theme: {
5 colors: {
6 primary: '#562BD6',
7 },
8 },
9 fetchToken: async function fetchToken() {...},
10};
11
12const dropin = new MoniteDropin(dropinConfig);
13
14dropin.create(component).mount(...);

(Optional) Localization

You can customize the locale of the component renderings as shown:

1const dropinConfig = {
2 entityId: 'ENTITY_ID',
3 apiUrl: 'ENVIRONMENT_URL',
4 locale: {
5 code: 'en-US',
6 messages: {
7 Sales: 'Invoicing',
8 Counterparts: 'Customers',
9 },
10 },
11 fetchToken: async function fetchToken() {...},
12};
13
14const dropin = new MoniteDropin(dropinConfig);
15
16dropin.create(component).mount(...);

3: Set up user authentication

Every entity user of the Monite app should authorize themselves with a mechanism that is used in your web application. When a user is authorized by you, you should also issue an entity user token, as described in the previous Step 2: Implement server side.

If you already implemented a backend part that is capable of issuing entity user tokens, then write a function that retrieves this token.

However, if you have not implemented the backend part yet but can already generate an entity and entity user token, you can also just send a POST request to the /auth/token endpoint directly from this script, as shown below:

1 async function fetchToken() {
2 const request = {
3 grant_type: "entity_user",
4 entity_user_id: "ENTITY_USER_ID",
5 client_id: "CLIENT_ID",
6 client_secret: "CLIENT_SECRET",
7 };
8
9 const response = await fetch(
10 "https://api.sandbox.monite.com/v1/auth/token",
11 {
12 method: "POST",
13 headers: {
14 "Content-Type": "application/json",
15 "x-monite-version": "2024-05-25",
16 },
17 body: JSON.stringify(request),
18 }
19 );
20 return await response.json();
21 }

Monite does not recommend exposing the credentials in your fetchToken function on the client side as shown earlier. For security reasons, we recommend that all Monite tokens are generated from your server-side code.

4: Review the code

Finally, you can compare your resulting code with our template to make sure that everything is correct:

1const dropinConfig = {
2 entityId: 'ENTITY_ID',
3 apiUrl: 'ENVIRONMENT_URL',
4 componentSettings: {
5 receivables: {},
6 counterparts: {
7 customerTypes: ['customer'],
8 },
9 },
10 theme: {
11 colors: {
12 primary: '#562BD6',
13 },
14 },
15 locale: {
16 code: 'en-US',
17 messages: {
18 Sales: 'Invoicing',
19 Counterparts: 'Customers',
20 },
21 },
22 fetchToken: async function fetchToken() {...},
23};
24
25const dropin = new MoniteDropin(dropinConfig);
26
27dropin.create(component).mount(...);

(Optional) Events

You can subscribe to events in the Monite system:

1import('@monite/sdk-drop-in').then(({ MoniteDropin, MoniteEventTypes }) => {
2 const dropinConfig = {...};
3 const dropin = new MoniteDropin(dropinConfig);
4 dropin.create(component).mount(moniteAppRef.current);
5
6 // Subscribe to events <===
7 dropin
8 .on(MoniteEventTypes.INVOICE_CREATED, () => {
9 console.log('invoice.created');
10 });
11});

Here is the list of events you can subscribe:

Event nameDescription
INVOICE_CREATEDAn invoice was created.
INVOICE_UPDATEDAn invoice was updated.
INVOICE_DELETEDAn invoice was deleted.
INVOICE_SENTAn invoice was sent.
PAYMENTS_ONBOARDING_COMPLETEDThe payments onboarding process was completed.
WORKING_CAPITAL_ONBOARDING_COMPLETEDThe working capital (financing) onboarding process was completed.

Next steps

By completing this quick start, you have learned how to:

  • Install and set up Monite Drop-in SDK.
  • Localize it and change the default appearance.

To learn more about this integration, see Drop-in library.