# Merchant View integration guide

> Follow the steps below to embed the Merchant View component:

Follow the steps below to embed the Merchant View component:

1. (serverside) Confirm the merchant's instance exists, via the capabilities API
2. (serverside) Create a deep link of type `dashboard`, which returns an ID
3. (clientside) Embed it in your page, using our Web SDK
4. (clientside) Handle events via our browser events API

## Instance capabilities

Merchant View shows a merchant's own payment activity, so the instance has to exist and be connected to a payment processor before there is anything to show.

Please see: [Validate Capabilities API](/platforms/reference/operations/getcapabilities/)

If the instance does not exist, create it via the [Instance Creation API](/platforms/reference/platform/operations/createinstance/). If it exists but has no processor connected, send the merchant to [Merchant Setup](/platforms/embedded-payments/onboarding/) first.

## Deep link creation

Create a deep link with `type` set to `dashboard`. The `context` object decides what the merchant lands on and what they are allowed to do:

* `mode` — `enquiry` for the day-to-day console, `setup` for the administrative side. `module` is accepted as a synonym.
* `action` with `id` or `alt_key` — open one account, contract, transaction or payment method directly, instead of the full view.
* `menu`, `menu_logo`, `return_url`, `favicon` — how much Shuttle chrome is shown, and where your logo returns to.
* `features` — turn individual actions off for this session only. See [Merchant View options](/platforms/embedded-payments/activity-view-options/).
Pass `user` alongside `context`, as `deep_link.user`: who is using it. This is what the audit history records against every change they make, so pass a real identity rather than a service account.

Please see: [Create a deep link](/platforms/reference/operations/createdeeplink/)

## Page embedding

* Include the current version of `shuttle.js` in your page (see [shuttle.js](/platforms/embedded-payments/shuttlejs/) for versions and SRI checksums)
* Add an element carrying the deep link ID in `data-shuttle-embed`
* If using a single page app, e.g. React, call `Shuttle.bind();` after the element is rendered

```
<script src="https://app.shuttleglobal.com/shuttle-1.4.7.js" integrity="sha384-4M/kxbiSD8jmfTM8DWfYMqTBpp/0A4G9CpLPtYNSqfIDEVDJ6Uix/lgs2nnhwjjW" crossorigin="anonymous"></script>

<div data-shuttle-embed="2b7a186da84441f98dbac1c773150325"></div>
```

Please see: [Deep links](/platforms/reference/operations/tags/deep-links/#integration)

## Handling events

Merchant View raises three browser events:

* `DASHBOARD_DISPLAY`: the component's height, and whether it is currently showing a modal. Raised on load and whenever either changes, so your page can resize the iFrame and dim behind a dialog rather than clipping it.
* `DASHBOARD_ERROR`: something went wrong inside the component, with a type and the error.
* `EXTEND_SESSION`: raised whenever the merchant does something that reaches the API. Use it to keep your own session alive while they are working, rather than logging them out under an active screen.

Please see: [Browser events](/platforms/reference/operations/tags/deep-links/#browser-events)

## What the merchant sees

Every screen is documented, one page per screen: [Merchant View - Operations](/platforms/user-guides/operations/) and [Merchant View - Admin](/platforms/user-guides/admin/).