Wallet SDK

Overview

The Wallet SDK enables seamless, secure identity verification and transaction authorization during checkout. It is optimized for embedded experiences (e.g., iframes) and uses multi-factor authentication (MFA).

This SDK allows your wallet domain to:

• Initiate an MFA session tied to a transaction.
• Guide users through passkey authentication, passkey creation or fallback login.

Use this SDK when building wallet experiences to streamline embedded checkout flows using passkeys or third-party login methods.

Prerequisites

• Create an application to obtain a base URL. The SDK uses this base URL to interact with the LoginID authentication service.
• Create an API key with at least the external:verify scope. You’ll need this to request authorization tokens from your backend.

Setup SDK

Javascript

npm i @loginid/checkout-wallet

Import the class:

import { LoginIDWalletAuth } from "@loginid/checkout-wallet";

const lid = new LoginIDWalletAuth({
  baseUrl: process.env.REACT_APP_LOGINID_BASE_URL,
});

info

You can view the source code here.

Kotlin

🚧 Coming Soon

Class LoginIDWalletAuth

A specialized authentication class built on top of LoginID's MFA flow, designed specifically for handling authentication and identity trust during a checkout process.

This class integrates with embedded contexts (e.g., iframes), allowing wallet-based authentication and the propagation of trusted identity back to the merchant securely.

Defined in packages/checkout/wallet/src/wallet/wallet.ts:28

constructor

Initializes a new instance of the LoginIDWalletAuth.

new LoginIDWalletAuth(config: LoginIDConfig): LoginIDWalletAuth

Params

Parameter	Type	Required	Description
config	LoginIDConfig	Yes	The configuration object for LoginID services.
config.appId?	string	No	The optional app ID for specific application.
config.baseUrl	string	Yes	The base URL for LoginID FIDO service which can be obtained on the dashboard.
config.disableAnalytics?	boolean	No	If true, disables sending analytics/events to LoginID. Defaults to false.

Returns

LoginIDWalletAuth

Defined in packages/checkout/wallet/src/wallet/wallet.ts:37

beginFlow

Begins the MFA authentication flow for a checkout session.

If executed within an embedded context, the method attempts to retrieve the checkoutId from the parent message (if not already provided). It initiates the MFA session tied to a specific transaction payload.

beginFlow(options: CheckoutBeginFlowOptions): Promise<MfaSessionResult>

Params

Parameter	Type	Required	Description
options	CheckoutBeginFlowOptions	Yes	Contains the transaction payload and optional identifiers.
options.checkoutId?	string	No	An identifier generated on the merchant side to identify the current checkout session. This identifier is used as a key to retrieve associated trust information. It is passed to the wallet to link the session with wallet-issued identity data, enabling secure transaction confirmation without revealing end-user identity to the merchant.
options.traceId?	string	No	A unique identifier used to trace and correlate all events associated with a single MFA interaction. This ID is useful for end-to-end observability, logging, and debugging across distributed systems. It can be generated by the client or left unset—if not provided, a secure random ID will be created automatically by LoginID. Example: 6957cf6e-a86c-44fb-b25a-bd97cb9ff830
options.txPayload	string	Yes	A transaction payload generated by the merchant to represent the purchase or operation being confirmed.
options.username?	string	No	The username of the user initiating the checkout session. If not provided, the wallet may retrieve it from an embedded context.

Returns

Promise<MfaSessionResult>

interface MfaSessionResult {
    accessToken?: string;
    flow?: "signIn" | "signUp";
    idToken?: string;
    isComplete: boolean;
    nextAction?:
        | "passkey:reg"
        | "passkey:auth"
        | "passkey:tx"
        | "otp:email"
        | "otp:sms"
        | "otp:verify"
        | "external";
    payloadSignature?: string;
    refreshToken?: string;
    remainingFactors: RemainingFactor[];
    session?: string;
    username?: string;
}

Defined in packages/checkout/wallet/src/wallet/wallet.ts:81

discover

Performs discovery to identify the appropriate authentication flow for the wallet experience.

This method should be called immediately on page load of the wallet landing page. It determines whether the user is accessing the wallet via an embedded iframe or requires a fallback method.

The discovery result includes available authentication factors and flow preferences. It also sends the result back to the parent context (if embedded) to allow the merchant to proceed accordingly.

discover(): Promise<DiscoverResult>

Returns

Promise<DiscoverResult>

interface DiscoverResult {
    flow: Flow;
    username?: string;
}

Example

useEffect(() => {
  const runDiscovery = async () => {
    await lid.discover();
  };
  runDiscovery();
}, []);

Defined in packages/checkout/wallet/src/wallet/wallet.ts:64

performAction

Performs an MFA action using the provided factor and optional payload.

In the context of checkout, this method is used for two critical use cases:

Passkey Registration (passkey:reg): Used during account creation to register a passkey (e.g., WebAuthn).

Passkey Transaction Confirmation (passkey:tx): Confirms a specific transaction securely using a passkey.

Other supported factors include standard WebAuthn login (passkey:auth), one-time passwords (otp:email, otp:sms, otp:verify), or external authentication via third-party providers.

After a successful authentication, this method will attempt to communicate the result (e.g., a checkout trust token or identifier) back to the parent frame (if embedded).

performAction(
    factorName:
        | "passkey:reg"
        | "passkey:auth"
        | "passkey:tx"
        | "otp:email"
        | "otp:sms"
        | "otp:verify"
        | "external",
    options?: CheckoutPerformActionOptions,
): Promise<MfaSessionResult>

Params

Parameter	Type	Required	Description
factorName	"passkey:reg" "passkey:auth" "passkey:tx" "otp:email" "otp:sms" "otp:verify" "external"	Yes	The MFA factor to be executed.
options	CheckoutPerformActionOptions = {}	No	The payload for the factor.
options.autoFill?	boolean	No	Enables passkey support in browser autofill suggestions (conditional UI), if supported.
options.displayName?	string	No	A human-palatable name for the user account, intended only for display on your passkeys.
options.payload?	string	No	The payload required for completing the authentication factor. This typically contains user input or challenge-response data.
options.txPayload?	string	No	An updated transaction payload generated by the merchant to represent the purchase or operation being confirmed. This updates the initial txPayload used in the beginFlow method.

Returns

Promise<MfaSessionResult>

interface MfaSessionResult {
    accessToken?: string;
    flow?: "signIn" | "signUp";
    idToken?: string;
    isComplete: boolean;
    nextAction?:
        | "passkey:reg"
        | "passkey:auth"
        | "passkey:tx"
        | "otp:email"
        | "otp:sms"
        | "otp:verify"
        | "external";
    payloadSignature?: string;
    refreshToken?: string;
    remainingFactors: RemainingFactor[];
    session?: string;
    username?: string;
}

Defined in packages/checkout/wallet/src/wallet/wallet.ts:138