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

triggerOtp

​​ Overview

triggerOtp starts an OTP-style verification. The wallet sends the challenge code to the cardholder out of band (SMS / email). Call verifyOtp once the cardholder enters it.

Use this for verification methods with type: "otp" from enrollCard’s verificationMethods. For iframe-based methods, use registerPasskey instead.

​​ Signature 


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

​​ Parameters

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

  • methodId (string, required) — One of the id values from enrollCard’s verificationMethods.

  • options (object) — Optional CallOptions: apiTokenOverride, signal. For Visa also container (Element, to mount the auto-handshake iframe) and secureToken (string, to supply a token and skip the handshake).

​​ Returns

Promise<TriggerOtpResult>

  • session (FlowSession) — The advanced session — pass it to verifyOtp.

  • challengeType (string) — The challenge type reported by the wallet (defaults to "otp"). null when the wallet short-circuits and returns a virtualCardId directly.

  • challenge (object) — The wallet challenge object when one is returned (otherwise null).

  • virtualCardId (string) — Present when the wallet completes verification immediately without a further challenge; otherwise null. When set, enrollment is done — skip to createIntent.

​​ Example 


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



const otp = verificationMethods.find((m) => m.type === 'otp');



// Capture the advanced session — pass THIS to verifyOtp, not the pre-trigger one.

const triggered = await fap.triggerOtp(session, otp.id);



// The cardholder receives the code out of band — collect it, then:

const { virtualCardId } = await fap.verifyOtp(triggered.session, codeTheUserEntered);

​​ Errors

The call rejects (not resolves) on failure — wrap it in try / catch.

  • Unknown / non-OTP methodId. Passing an id that is not an otp-type method from enrollCard’s verificationMethods is rejected. Use registerPasskey for iframe-type methods.
  • 503 from the network. If the underlying verification service is unavailable, the call rejects with the REST ErrorServiceUnavailable (503) error surfaced through the SDK — retry after a short delay.
  • Timeout / abort. Bounded by timeoutMs; an aborted options.signal also rejects the call.