Add to Wallet Preview

The Add to Wallet component allows your customers to add one card to Apple Wallet or Google Wallet. It renders only the wallet buttons, so you can place them in your own card UI instead of the full Card component.

Note

The element stays empty until the buttons are ready, and stays empty when no wallet can be shown. Your app owns any fallback UI.

Note

This component is web only. On iOS, Android, and React Native, keep using Add to Wallet from the Card component.

Implementation

Web Components

Add the Add to Wallet element where you want the wallet buttons to appear.

Behavior

• Provisioning runs in production only. Sandbox and other non-production environments emit unitAddToWalletWalletsUnavailable with cause environment.
• Mounting the element loads the wallet SDK and requests a provisioning payload.
• The Platform must have Apple and/or Google push provisioning enabled. To set this up, follow Add to Mobile Wallet. For a managed solution, follow Add to Wallet.
• Buttons are offered only when the card status is Active.
• Inside the native mobile SDK the element emits unitAddToWalletWalletsUnavailable with cause native-sdk. Use the mobile Card component instead.
• Nothing is rendered while the buttons are loading, and nothing is rendered when no wallet is available.

Example

<unit-elements-add-to-wallet
  card-id="632197"
  customer-token=""
  direction="row"
></unit-elements-add-to-wallet>

Inputs:

Name	Type	Required	Description
card-id	string	Yes	Unit card id. Buttons are offered only when the card status is Active.
customer-token	string	Yes	A Unit customer token. Required scopes: cards The element reads the card and requests a mobile wallet payload.
direction	string ("row" / "column")	No	"row" places the buttons side by side. "column" stacks them. Default "row".

Events:

Listen on the element. The events bubble, so a listener on window also receives them. The payload is event.detail.

Event Name	Description	Detail
unitAddToWalletWalletsAvailable	At least one wallet button is ready	{ wallets } — "apple" and/or "google"
unitAddToWalletWalletsUnavailable	Nothing will be rendered	reason is disabled (cause native-sdk, environment, not-enabled, or card-not-active), error (cause fetch-failed or setup-failed), or unavailable (cause no-wallet). When wallet setup fails (setup-failed), error may include code and correlationId.
unitAddToWalletProvisioningResult	The customer finishes or fails an add	{ result?, error? }. result.status is also written to data-provisioning-status, or "error" when provisioning fails.

Example

<unit-elements-add-to-wallet id="add-to-wallet" card-id="632197" customer-token=""></unit-elements-add-to-wallet>
<script>
  const element = document.querySelector("#add-to-wallet");

  element.addEventListener("unitAddToWalletWalletsAvailable", (event) => {
    // event.detail.wallets — ["apple"], ["google"], or ["apple", "google"]
    console.log(event.detail.wallets);
  });

  element.addEventListener("unitAddToWalletWalletsUnavailable", (event) => {
    // event.detail — { reason: "disabled", cause: "card-not-active" }
    console.log(event.detail.reason, event.detail.cause);
  });

  element.addEventListener("unitAddToWalletProvisioningResult", (event) => {
    // event.detail — { result: { status: "SUCCESS" } } or { error: {} }
    console.log(event.detail.result, event.detail.error);
  });
</script>

Host-readable attributes

These attributes are set on the element. Read them when the host does not listen for events.

Attribute	When	Value
data-wallet-state	After the element starts	loading, available, or unavailable. Nothing is rendered while loading.
data-wallets	While available	Comma-separated apple and/or google
data-wallet-unavailable-reason	While unavailable	disabled, error, or unavailable
data-wallet-unavailable-cause	While unavailable	native-sdk, environment, not-enabled, card-not-active, fetch-failed, setup-failed, or no-wallet
data-provisioning-status	After a provisioning attempt	result.status, or "error" when provisioning fails

Example

<unit-elements-add-to-wallet id="add-to-wallet" card-id="632197" customer-token=""></unit-elements-add-to-wallet>
<script>
  const element = document.querySelector("#add-to-wallet");
  const state = element.getAttribute("data-wallet-state");

  if (state === "available") {
    // data-wallets — "apple", "google", or "apple,google"
    console.log(element.getAttribute("data-wallets"));
  }

  if (state === "unavailable") {
    // data-wallet-unavailable-reason — "disabled"
    // data-wallet-unavailable-cause — "card-not-active"
    console.log(
      element.getAttribute("data-wallet-unavailable-reason"),
      element.getAttribute("data-wallet-unavailable-cause")
    );
  }

  // data-provisioning-status — "SUCCESS" or "error", after an add attempt
  console.log(element.getAttribute("data-provisioning-status"));
</script>

FAQs

How do I know whether the buttons are showing?

Listen for unitAddToWalletWalletsAvailable and unitAddToWalletWalletsUnavailable on the element.

• unitAddToWalletWalletsAvailable means at least one button is rendered. event.detail.wallets lists "apple", "google", or both.
• unitAddToWalletWalletsUnavailable means nothing will be rendered. The element stays empty. event.detail.reason and event.detail.cause explain why.

Until one of those events fires, data-wallet-state is loading and nothing is rendered.

If you are not listening for events, read data-wallet-state on the element. available means the buttons are showing. unavailable means they will not be shown.