Fetching and using download links

This guide explains how to fetch wallet pass download links via the Voyado API and how to implement them across your key distribution touchpoints, My Pages and registration flows.

How wallet pass links work

Wallet pass links are unique, member-specific URLs that allow a customer to add their digital card directly to Apple Wallet or Google Wallet. These 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 do not 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. This method gives you full control over the user experience and keeps 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:

Request body

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

Path parameters

Response

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

Response fields

Using download links on My Pages

My Pages, or My Account, is the primary always-on distribution surface for your digital card. Members who missed the launch email, 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, Apple Wallet on iOS, Google Wallet on Android, QR code on desktop

Since the 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

The registration flow is one of the highest-converting moments to issue a wallet card as the member has just signed up. The goal is to get the card onto their device with as little friction as possible.

On mobile, the best experience is to automatically redirect the member to their createPassUrl immediately after registration, 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 shown 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

Voyado Engage makes it straightforward to include personalized, localized download buttons in your emails directly from Design Studio.

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 / 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 →