Docs
Firmly Agentic Commerce
Docs
Set theme to dark (⇧+D)
  1. Docs
  2. API Reference
  3. Headless SDK
  4. registerPasskey

registerPasskey

​​ Overview

registerPasskey handles iframe-based verification (passkey / FIDO2 / 3DS / Mastercard MANAGED_AUTHENTICATION). It wraps three wallet calls plus the iframe lifecycle into a single SDK call:

​​ Trigger

Posts to /enroll/trigger with the chosen method and callback_uri.

​​ Mount the iframe

The wallet returns { challenge: { type: 'embed_iframe', uri } }. The SDK mounts an iframe pointed at uri in your container.

​​ Wait for the result

The SDK waits for a postMessage from the iframe (Visa direct) or the bridge page (Mastercard redirect → bridge → postMessage).

​​ Verify

Posts to /enroll/verify and returns the virtualCardId.

​​ Signature 


const result = await fap.registerPasskey(session, methodId, options);

​​ Parameters

  • session (FlowSession, required) — The session from enrollCard.

  • methodId (string, required) — An iframe-type method id from verificationMethods (e.g. "MANAGED_AUTHENTICATION" for Mastercard, "VISA_IFRAME_HANDSHAKE" for Visa).

  • options.container (Element) — DOM element to mount the iframe in. Falls back to ClientConfig.iframeContainer — one of the two must be set.

  • options.callbackUri (string) — Overrides the default bridgeUrl.

  • options.timeoutMs (number) — Per-call iframe timeout override.

  • options.apiTokenOverride (string) — Override the apiToken for this call.

  • options.signal (AbortSignal) — Abort the iframe wait.

​​ Returns

Promise<RegisterPasskeyResult>

  • session (FlowSession) — The advanced session.

  • virtualCardId (string | null) — Set when the wallet completed enrollment.

  • verificationMethods (array | null) — Returned when the wallet asks for additional verification.

​​ Example 


const { session, verificationMethods } = await fap.enrollCard({ /* ... */ });



const method =
  verificationMethods.find((m) => m.id === 'MANAGED_AUTHENTICATION') ||
  verificationMethods.find((m) => m.type === 'embed_iframe');



const { virtualCardId } = await fap.registerPasskey(session, method.id, {
  container: document.getElementById('mc-iframe-slot')

});