Deep links

deep-links

A deep link creates a secure, time-limited URL that links to a Shuttle UX component. Deep links power the embeddable Merchant Setup and merchant view experiences.

Deep Link Types

Type	Description
`gateway-setup`	Embeds the Merchant Setup component — allows a merchant to connect and configure payment processors
`dashboard`	Embeds the merchant view — allows searching and viewing accounts, transactions, and contracts

Integration

Server-side: Create a deep link via POST /deep_links with the type and context
Client-side: Include shuttle.js and add a container div:

<script src="https://app.shuttleglobal.com/shuttle-1.4.X.js"></script>
<div data-shuttle-embed="DEEP_LINK_ID"></div>

If the div is added after page load (e.g., React), call Shuttle.bind().

Context Options

Merchant Setup (`gateway-setup`)

Field	Description
`processor`	Limit Merchant Setup to a single processor (e.g., `"STRIPE"`)
`processor_filter`	Array of allowed processors (e.g., `["STRIPE", "SQUARE"]`)
`theme`	UI customisation — fonts, colours, border radius, row height

Merchant View (`dashboard`)

Field	Description
`mode`	Section to display: `enquiry` or `setup`
`action`	View to display: `view_account`, `view_contract`, `view_transaction`, `view_payment_method`, or `localisation` (`localisation` requires `mode` `setup`)
`id` / `alt_key`	ID of the object to view (pass one or the other)
`menu`	Menu style: `normal`, `banner`, or `hidden`
`menu_logo`	URL to PNG logo for banner menu (max 120x20px recommended)
`return_url`	URL to navigate to when logo is clicked (banner menu)
`favicon`	URL to PNG favicon when opened in a window

Security

Field	Description
`user.alt_key`	Your primary key for the logged-in user — all activity is grouped under this key
`user.name`	Display name of the logged-in user
`session.teams`	The user’s role, which decides what actions the session can perform. Every role sees the same screens and data; only the actions differ. Shuttle enforces the role on the server for every action. `ADMIN`: everything. `SUPPORT`: services customers, including taking payments, refunds, captures and voids, but cannot change providers, routing, merchant account settings or screen wording. `SUPPORT_RO`: performs no action. Omitted: the level of the session creating the link. A link never gets a higher level than the session that creates it: a request for more is issued at the creator’s level. See Roles and permissions
`ip_address`	IP address of the merchant
`expiry_seconds`	How long the link is valid (default: 900 seconds). Generate links just before redirecting and use short expiry times

Browser Events

Merchant Setup Events

Event	Description
`SETUP_STATUS`	Raised when payment readiness changes. Check `payment_ready` boolean
`SETUP_DISPLAY`	Frame height changed. Includes `height` (pixels) and `modal` (boolean)
`SETUP_ERROR`	Error occurred (e.g., `SESSION_EXPIRED`)

Merchant View Events

Event	Description
`DASHBOARD_DISPLAY`	Frame height changed. Includes `height` and `modal`
`DASHBOARD_ERROR`	Error occurred (e.g., `SESSION_EXPIRED`)

Common Events

Event	Description
`EXTEND_SESSION`	Server request made — use to extend your app’s session

Was this page helpful?