Fetching and using download links

Wallet pass links are unique, member-specific URLs that let a customer add their digital card directly to Apple Wallet or Google Wallet. This article explains how to fetch these links via the Voyado API and how to implement them across your key distribution touchpoints, including My Pages, registration flows, and emails.

How wallet pass links work

Wallet pass links are fetched server-to-server using the Voyado API and can then be surfaced to the customer in a number of ways depending on the context and the device they are using.

Each createPassUrl returned by the API is a smart link that handles everything automatically:

• On iOS: redirects directly to the Apple Wallet pass download
• On Android: redirects directly to the Google Wallet pass download
• On desktop: displays a QR code that the member can scan with their phone to complete the download

This means you don't need to implement separate device detection logic or generate QR codes yourself. The link handles all of this out of the box.

Fetching download links

Download links are fetched via a secure server-to-server API call using a Voyado API key. Keep your API key secure — never expose it client-side.

Endpoint

POST https://[client].voyado.com/api/v3/wallet/pass/urls

Authentication

The apikey authorization method is used as part of an HTTPS header. Read more about authentication here.

Request body

{
  "cardId": "00000000-0000-0000-0000-000000000000",
  "contactIds": [
    "00000000-0000-0000-0000-000000000000"
  ]
}

Request parameters

Response

{
  "[contactId1]": "[createPassUrl1]",
  "[contactId2]": "[createPassUrl2]"
}

Response fields

Using download links on My Pages

My Pages, or My Account, is the primary place members can download their card. Members who signed up later or switched devices will find their card here.

Implementation flow

1. Member visits My Pages, authenticated.
2. Your server fetches the pass link from the Voyado API using the member's contactId.
3. Render the createPassUrl as the href on the Add to Wallet button.
4. The link handles the rest. It opens Apple Wallet on iOS, Google Wallet on Android, and displays a QR code on desktop.

Since createPassUrl handles device detection and QR code generation automatically, the implementation on My Pages is straightforward. Link the button directly to the URL.

Example implementation (React)

'use client';

type WalletProps = {
  createPassUrl: string;
};

export default function MyPagesWalletSection({ createPassUrl }: WalletProps) {
  return (
    <div>
      <p>Add your membership card to your wallet.</p>
      <a href={createPassUrl}>
        <img src="/assets/add-to-wallet.svg" alt="Add to Wallet" />
      </a>
    </div>
  );
}

Using download links in a registration flow

On mobile, the best experience is to automatically redirect the member to their createPassUrl immediately after registration, with no button tap required. On desktop, linking to the URL will display the QR code automatically.

Implementation flow

1. Member completes registration.
2. Your server fetches the pass link from the Voyado API using the new member's contactId.
3. On mobile, automatically redirect to createPassUrl on page load.
4. On desktop, render createPassUrl as a link or button. The QR code is displayed automatically.

Device detection for automatic redirect

On mobile, use navigator.userAgent to detect the device and trigger an automatic redirect via useEffect. On desktop, no redirect is needed. Simply render the link and the createPassUrl will display the QR code.

Example implementation (React / Next.js)

'use client';

import { useEffect } from 'react';

type WalletProps = {
  createPassUrl: string;
};

export default function RegistrationSuccess({ createPassUrl }: WalletProps) {
  function isMobile() {
    return /iPhone|iPad|iPod|Android/i.test(navigator.userAgent);
  }

  useEffect(() => {
    if (createPassUrl && isMobile()) {
      window.location.href = createPassUrl;
    }
  }, [createPassUrl]);

  // Mobile: redirect fires automatically via useEffect
  if (isMobile()) {
    return <p>Opening your wallet card...</p>;
  }

  // Desktop: createPassUrl displays a QR code automatically
  return (
    <div>
      <h2>You're all set!</h2>
      <p>Scan the QR code below with your phone to add your membership card to your wallet.</p>
      <a href={createPassUrl}>
        <img src="/assets/add-to-wallet.svg" alt="Add to Wallet" />
      </a>
    </div>
  );
}

Behavior summary

Adding download buttons to emails

Step 1: Add the download link

1. Open your email in Design Studio.
2. Add a button or image element to your email.
3. In the link field of the element, insert the personalized field named Create pass URL.
4. The link is automatically personalized per member at send time. Each recipient receives their own unique createPassUrl.

Step 2: Set up localized Apple and Google Wallet button images

Design Studio supports localized Add to Wallet button images so the correct language asset is served automatically based on the email's localization setting.

1. Select the image element you are using as your Add to Wallet button.
2. In the Image source, select Dynamic.
3. Insert the personalized field for the button image:
   • Use Apple image URL for the Apple Wallet button.
   • Use Google image URL for the Google Wallet button.
4. The correct localized button image is served automatically based on the localization configured for the email.

Best practices for download buttons in email

• Always include an image of the card alongside the download buttons. Showing the actual card makes the value tangible and significantly increases download rates.
• Place the download buttons above the fold in dedicated card emails.
• Use Engage segmentation to only send to members who have not yet downloaded their card. Engage tracks card installation status per member, so you can exclude existing card holders from card download emails entirely.

Apple and Google Wallet badge assets

Always use the official badge assets when displaying Add to Wallet buttons. Do not create custom designs.

Apple Wallet buttons

Apple Wallet guidelines and asset files

Google Wallet buttons

Google Wallet guidelines and asset files