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

createIntent

​​ Overview

createIntent creates a payment intent bound to a mandate (the transaction amount, currency, and merchant details). It runs the intent challenge and returns an intentId once the cardholder is authenticated.

For Mastercard, the payment challenge (the MANAGED_AUTHENTICATION iframe) is produced here — so createIntent mounts an iframe and needs a container.

​​ Signature 


const result = await fap.createIntent(session, mandate, options);

​​ Parameters

  • session (FlowSession, required) — A verified session from registerPasskey / verifyOtp / selectCard.

  • mandate (object, required) — The transaction the cardholder is authorizing. Required fields:

    • amount (string) — Transaction amount.
    • currency_code (string) — ISO currency code (e.g. "USD", "AUD"). Optional fields:
    • merchant_name — Merchant display name.
    • currency_numeric — ISO numeric currency code.
    • merchant_category / merchant_category_code
    • description, consumer_prompt
    • quantity, ttl_seconds
    • callback_uri — overrides ClientConfig.bridgeUrl for this intent (used by Mastercard’s TAS authenticate step).

  • options.container (Element) — DOM element to mount the intent challenge iframe in. Required whenever this call mounts an iframe — i.e. for Mastercard, where the payment challenge (MANAGED_AUTHENTICATION) is produced here. For Visa, the FIDO assertion iframe is also driven from this step, so provide a container (or set ClientConfig.iframeContainer). The iframe is only skipped when the network short-circuits (e.g. a re-authenticated Visa flow that returns the intent directly).

  • options.secureToken (string) — Visa only, optional override. For Visa the SDK auto-mints a fresh secureToken via an iframe re-handshake (_mintVisaSecureToken), so you normally omit this. Supply it only to short-circuit the handshake (e.g. tests, replayed flows, or environments where the iframe cannot mount). Ignored for Mastercard.

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

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

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

​​ Returns

Promise<CreateIntentResult>

  • session (FlowSession) — The advanced session — now holds intentId.

  • intentId (string) — The created payment intent identifier. Pass session to completeOrder.

​​ Example 


// `session` is the verified session from registerPasskey / verifyOtp / selectCard.

const { session: intentSession, intentId } = await fap.createIntent(
  session,
  {
    amount: '36.99',
    currency_code: 'AUD',
    merchant_name: 'Sydney Zoo Shop'
  },
  { container: document.getElementById('mc-iframe-slot') }

);



// Pass intentSession forward to completeOrder.