Browser SDK

The Titus Browser SDK (@titus/sdk) lets you embed Titus checkout, authorization, and estimate flows directly into your site.

Loading the SDK

Add the script tag to your HTML:

<script src="https://assets.gotitus.com/sdk/v1/titus.js"></script>

Once loaded, the titus global is available and ready to use.

Calling methods before the script has fully loaded will trigger an error.

Staging: If you're developing against the staging environment, you override the sdk global to point to staging:
window.titus = new TitusSDK({ baseWebUrl: "https://www.gotitus.dev" });

checkout(options)

Opens a checkout flow in a popup window. The SDK opens the popup immediately on click, calls your getId function to create the checkout, then navigates to the checkout flow once the ID is returned.

Returns { close } if the popup opened, or null if it was blocked.

// Triggered on a user click
const handle = titus.checkout({
  getId: async () => {
    // Call your server to create a checkout via the Titus API
    // and return the checkout ID
    const id = await yourServer.createCheckout();
    return id;
  },
  onSuccess: ({ id }) => {
    console.log("Checkout completed:", id);
  },
  onClose: ({ id, loanDecision }) => {
    console.log("Popup closed by user:", id, loanDecision);
  },
  onError: ({ code }) => {
    console.error("Checkout error:", code);
  },
});

// Programmatically close the popup later if needed
handle?.close();

Options

Option	Type	Required	Description
`getId`	`() => Promise<string>`	Yes	Async function that returns the checkout ID. Called after the popup opens.
`newSession`	`boolean`	No	When `true`, logs out any existing Titus user before showing the popup so the flow starts with a fresh session. Useful when a business owner is logged in but wants a client to go through the flow on the same device.
`onSuccess`	`(result: { id: string }) => void`	No	Called when the customer completes the checkout flow.
`onClose`	`(result: { id: string, loanDecision: 'approved' \| 'denied' \| 'approved-awaiting-signatures' \| null }) => void`	No	Called when the popup is closed — by the customer, your code, or the overlay cancel button. `loanDecision` is `null` if no decision was made.
`onError`	`(error: { code: string }) => void`	No	Called when an error occurs. See error codes below.
`overlayText`	`string`	No	Overrides the default message shown on the overlay behind the popup.
`overlayCancelButtonLabel`	`string`	No	Overrides the default label for the overlay cancel button.

Return value

{ close } — call close() to programmatically dismiss the popup and trigger onClose.
null — the popup was blocked by the browser. The onError callback fires with code popup_blocked.

authorize(options)

Opens a pre-authorization flow in a popup window. Same signature and behavior as checkout().

// Triggered on a user click
const handle = titus.authorize({
  getId: async () => {
    // Call your server to create an authorization via the Titus API
    // and return the authorization ID
    const id = await yourServer.createAuthorization();
    return id;
  },
  onSuccess: ({ id }) => {
    console.log("Authorization completed:", id);
  },
  onClose: ({ id, loanDecision }) => {
    console.log("Popup closed by user:", id, loanDecision);
  },
  onError: ({ code }) => {
    console.error("Authorization error:", code);
  },
});

showEstimateModal(options?)

Opens a full-screen modal with the Titus estimate page, where customers can check if they qualify and see their rate. Unlike checkout() and authorize(), this uses an iframe rather than a popup.

titus.showEstimateModal({
  platformId: "741474f1-960e-481a-b202-f0423fcabe75",
  externalId: "12345",
});

All parameters are optional:

Option	Type	Description
`businessShortCode`	`string`	Short code identifying the business.
`businessId`	`string`	ID of the business.
`platformId`	`string`	ID of the platform.
`externalId`	`string`	Your external identifier for the business.

Passing platformId and externalId is recommended so the estimate modal can show personalized rates for the current business context.

Error codes

These error codes are passed to the onError callback in checkout() and authorize():

Code	When
`popup_blocked`	The browser blocked the popup window. This usually means the call wasn't triggered by a direct user interaction (click).
`get_id_failed`	The `getId` function threw an error or its promise rejected.
`invalid_id`	The `getId` function returned an invalid ID.

Browsers block popups that aren't triggered by a direct user action (like a click). The SDK is designed around this constraint — checkout() and authorize() open the popup immediately when called, then use getId to create the entity in the background while the popup is already open.

This means you must call these methods directly inside a click handler:

// Good — called directly from click handler
button.addEventListener('click', () => {
  titus.checkout({ ... });
});

// Bad — async gap before calling checkout, popup will be blocked
button.addEventListener('click', async () => {
  const data = await fetchSomeData();
  titus.checkout({ ... });
});

If the popup is blocked, onError fires with code popup_blocked and the method returns null.

Design Guidance

Get Help