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
`merchant`	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 (`merchant`)

Field	Description
`module`	Module to display (currently only `enquiry`)
`action`	View to display: `view_account`, `view_contract`, or `view_transaction`
`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`	Teams the user belongs to (controls permissions). Valid values: `ADMIN` (full access, default), `SUPPORT` (support team access), `SUPPORT_RO` (read-only: accounts, transactions, contracts, gateways)
`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