Elements and card vault for Web

initElements opens a focused credential experience without requiring Payment Widget. Use it to vault a card, run Click to Pay, or launch a configured native wallet.

Choose an Elements typeAsk Athia about this#

Vault a cardAsk Athia about this#

await DeunaSDK.initElements({
  orderToken,
  userInfo: {
    firstName: 'Ada',
    lastName: 'Lovelace',
    email: 'ada@example.com',
  },
  types: [{name: 'vault'}],
  callbacks: {
    onSuccess: (credential) => useCredentialResult(credential),
    onError: ({type, metadata}) => showRecovery(type, metadata.code),
    onClosed: () => restorePaymentMethods(),
    onCardBinDetected: ({cardBin, cardBrand}) => updateCardOffers(cardBin, cardBrand),
    onInstallmentSelected: ({installmentPlanOptionId}) => rememberPlan(installmentPlanOptionId),
  },
});

Experience flowAsk Athia about this#

Preload ElementsAsk Athia about this#

await DeunaSDK.initialize({
  publicApiKey: 'YOUR_PUBLIC_API_KEY',
  env: 'sandbox',
  preloadWidgets: [
    {
      widget: 'elements',
      params: {
        types: [{name: 'vault'}],
        language: 'en',
        callbacks,
      },
    },
  ],
});

// Add the order or user context and reveal the prepared experience.
await DeunaSDK.initElements({orderToken, userToken});

Initialization parameters and the later call are merged by the SDK. Put stable configuration in the preload entry and the freshest tokens in initElements.

ParametersAsk Athia about this#

Tokenize or purchaseAsk Athia about this#

The credit-card Elements behavior supports tokenize or purchase:

behavior: {
  paymentMethods: {
    creditCard: {
      flow: 'tokenize',
    },
  },
}

Use tokenize when the merchant flow only needs a reusable credential. Use purchase only with the required order and merchant configuration. Keep the backend responsible for deciding how the credential may be used.

Native walletsAsk Athia about this#

Check availability before rendering your button, then launch the matching type directly from the customer gesture:

const wallets = await DeunaSDK.getWalletsAvailable({orderToken, userInfo});
applePayButton.hidden = !wallets.includes('APPLE_PAY');

applePayButton.addEventListener('click', () => {
  DeunaSDK.initElements({
    orderToken,
    userInfo,
    types: [{name: 'APPLE_PAY'}],
    callbacks,
  });
});

See Wallet availability for platform values, caching, and troubleshooting.

Embedded and controlled modesAsk Athia about this#

Use mode: 'target', target, and onResize for an embedded experience. When your page owns the primary action, set hidePayButton: true, call isValid(), then await submit(). Disable the outer button while submission is pending.

await DeunaSDK.initElements({
  orderToken,
  types: [{name: 'vault'}],
  mode: 'target',
  target: '#credential-entry',
  hidePayButton: true,
  callbacks: {
    onResize: ({height}) => {
      document.querySelector('#credential-entry').style.height = `${height}px`;
    },
    onSuccess: useCredentialResult,
    onError: showRecovery,
  },
});

Migrate legacy secure fieldsAsk Athia about this#

Earlier documentation described modularPaymentCredentialsStorage, mountPaymentCredentialStorage, and a separate sdk.deuna.io secure-field bundle. Those names are not present in the audited current Web SDK public types or implementation. Do not copy the legacy initialization or field-mounting snippets into a new integration.

The maintained credential surface is hosted Elements through DeunaSDK.initElements:

Hosted Elements owns the sensitive input UI. The current public SDK does not expose a one-to-one API for mounting each card field into unrelated merchant DOM nodes. If your approved PCI scope or product design requires independent field ownership, stop the migration and confirm a supported architecture with DEUNA before implementation.

When migrating, run the old and new experience only in separate controlled test cohorts. Never initialize both against the same customer action or attempt to copy values from legacy secure frames into Elements.

Security and operationsAsk Athia about this#

• Do not read, mirror, or log card fields rendered by Elements.
• Send the result only to the merchant backend operation that needs it.
• Expire merchant sessions and SDK state together when the customer signs out.
• Reconcile an order after an interrupted purchase-mode flow.
• Treat onSuccess as a client result, not permission to use a credential outside the customer’s consent and merchant contract.

Related referencesAsk Athia about this#