Merchant Tools Package

Overview

The Merchant Tools Package provides the foundational utilities required to integrate secure checkout experiences using the LoginID Wallet. It helps merchants initiate, embed, and manage authentication flows within their checkout UI—whether through iframes or fallback methods.

Key capabilities include:

• Generating and signing secure checkoutId tokens for each session
• Dynamically determining whether to embed the wallet or fallback to an alternative flow
• Communicating securely between parent and wallet domains via postMessage
• Managing session completion and user trust with local storage tracking

Setup SDK

Javascript

Install with command:

npm i @loginid/checkout-merchant

info

You can view the source code here.

Class LoginIDMerchantCheckout

Facilitates the integration of LoginID's checkout authentication flow on the merchant side.

This class provides methods to generate a unique checkoutId and to initiate the checkout process by determining the appropriate authentication flow—either embedding the wallet in an iframe for a seamless experience or falling back method.

Defined in packages/checkout/merchant/src/merchant/merchant.ts:19

constructor

new LoginIDMerchantCheckout(): LoginIDMerchantCheckout

Returns

LoginIDMerchantCheckout

Static getCheckoutId

Generates or retrieves a unique checkoutId for the current session.

getCheckoutId(): Promise<string>

Returns

Promise<string>

Defined in packages/checkout/merchant/src/merchant/merchant.ts:25

Static startCheckout

Initiates the checkout process by determining the appropriate authentication flow.

This method first performs a discovery to decide whether to proceed with an embedded iframe for an embedded on-site experience or to fall back to a full-page redirect or fallback method. It then handles the communication with the wallet and manages the checkout session accordingly.

startCheckout(params: StartCheckoutParams): Promise<void>

Params

Parameter	Type	Required	Description
params	StartCheckoutParams	Yes	The parameters required to start the checkout process.
params.discoverUrl?	string	No	Optional URL used for discovery to determine whether an embedded checkout is possible. If omitted, fallback logic will rely on iframe.src.
params.errorCallback?	(error	No	Optional callback function invoked when an error occurs during checkout. Receives an error string describing the issue.
params.fallbackCallback	() => Promise<void>	Yes	Callback function invoked if embedded checkout is not possible. Use this to implement a manual fallback flow (e.g., redirect to wallet).
params.iframe	HTMLIFrameElement	Yes	The custom iframe element that will be used to render the embedded checkout flow. Must have appropriate allow attributes for WebAuthn (e.g., publickey-credentials-get and publickey-credentials-create).
params.mountTarget	HTMLElement	Yes	The HTML element to which the iframe should be mounted. Typically a container in your DOM, such as document.body.
params.successCallback?	() => Promise<void>	No	Optional callback function invoked when the checkout completes successfully.

Returns

Promise<void>

Defined in packages/checkout/merchant/src/merchant/merchant.ts:48

Class ParentMessages

Class representing parent message handling.

Defined in packages/checkout/merchant/src/messages/parent.ts:16

constructor

Creates an instance of ParentMessages.

new ParentMessages(
    iframe: HTMLIFrameElement,
    allowedOrigin?: string,
): ParentMessages

Params

Parameter	Type	Required	Description
iframe	HTMLIFrameElement	Yes	The iframe element for message communication.
allowedOrigin	string = "*"	No	The allowed origin for message communication.

Returns

ParentMessages

Defined in packages/checkout/merchant/src/messages/parent.ts:50

sendMessage

Sends a message to the child.

sendMessage(method: IframeMethod, params?: any): Promise<unknown>

Params

Parameter	Type	Required	Description
method	IframeMethod	Yes	The method name. - "discover" - "sign_transaction"
params	any = {}	No	The parameters for the method.

Returns

Promise<unknown>

Defined in packages/checkout/merchant/src/messages/parent.ts:144