Download pages
Configure hosted download pages that let customers save one or more Apple Wallet and Google Wallet passes.
Download pages are hosted pass-delivery pages. They let customers save Apple Wallet or Google Wallet passes without completing an enrolment form.
Real-world examples
A loyalty email links to one existing customer card.
A booking confirmation displays every ticket in one order.
An account area lists a customer’s active cards and tickets.
When to use a download page
Use a download page when the pass already exists. The delivery URL resolves the pass, then shows the relevant wallet action.
Use an Enrolment form when registration, identity checks, or consent collection must happen first.
Use On your website to embed an Add to Wallet button in an existing web experience. Use On your mobile app for a native app flow.
Configure a download page
Configure download pages in Wallet → Download pages. Each page needs a unique URL slug and a page type.
Use separate slugs for separate delivery journeys. For example, use loyalty for cards and tickets for event passes.
Choose the page type
Single pass
pass
One delivery URL resolves one pass.
Pass list
passList
One delivery URL resolves several passes.
A single-pass page displays wallet actions for the resolved pass. A pass-list page lets customers select matching passes.
Configure a single-pass page
Use a pass page where the URL resolves exactly one pass.
autoDownloadPass
false
Downloads the pass file automatically. This suits mobile deep-link journeys.
passCreation.flow
—
Runs when no pass exists. The flow must contain a Pass element.
Without passCreation.flow, a missing pass produces an error.
Configure a pass-list page
Use a passList page when the URL can resolve several passes. A booking with several tickets is a common example.
allowDownloadAllPasses
true
Displays an action to download every resolved pass.
showInactivePasses
false
Lists inactive passes without allowing download.
Apply shared settings
Both page types support these settings.
headerImage
Displays an image at the top of the page. Use an absolute URL or a /public/ path.
theme
Overrides the page theme.
internationalization.resources
Defines translated string resources, such as /locales/fields.
errorLayoutName
Sends unrecoverable errors to another page slug.
requireValidRedirectId
Only accepts a known platform redirect when set to true.
Set requireValidRedirectId to true when approved platform redirects must control access. Its default is false.
Build a delivery URL
A delivery URL opens a hosted download page. Customers use this page to save a pass to Apple Wallet or Google Wallet.
Use delivery URLs in email, SMS messages, QR codes, and campaign landing pages. Choose the lookup method based on the data available when the link is generated.
Choose the lookup method before building the URL. First, decide whether the link resolves one known pass or a customer record. Then assess whether the identifier is opaque, predictable, or sensitive. Finally, confirm where the URL is generated and which connector handles it.
Use a pass ID when the exact platform pass is known. Use an external ID when a business-owned identifier must resolve a pass or pass list. Use an authentication token when a backend creates a secure, recipient-specific link.
Every delivery URL has this base structure:
https://{host}/{tenant}/{layout}?{lookup parameter}
{host}is a custom domain orapp.neostore.cloud.{tenant}is the tenant identifier.{layout}is the configured download-page slug.{lookup parameter}identifies the pass or customer.
The layout controls the page after the pass is found. It can show one pass, a pass list, or a registration flow.
Real-world examples
A loyalty email resolves one customer card with a signed CRM identifier.
A QR code opens every ticket linked to one booking identifier.
A campaign link uses an authentication token for each recipient.
Use a pass ID when the platform-assigned pass ID is already available. This opaque value identifies one known pass. It does not need a signature.
This suits customer communications after pass creation. Store the pass ID when the pass is created. Then add it to the delivery URL.
Use an external ID when a stable, business-owned identifier is available. The identifier key is free-form. Common keys include y2.customerId, comarch.customerId, and shopify.orderId.
Use the same key and value stored on the pass. The security method depends on the identifier and connector. An external ID can be protected with an HMAC signature or by including a secret in the delivery URL.
For an HMAC-protected lookup, add the signature as the matching .hmac parameter:
id.y2.customerId={customerId}&id.y2.customerId.hmac={hmac}
Use HMAC-SHA256 with the tenant secret. Tenant secrets are available in Settings → API keys & secrets. Two rotating secrets are accepted. This supports secret rotation without delivery downtime.
Do not expose a predictable identifier without protection. Customer and loyalty card numbers can be enumerated to access other passes.
Use an authentication token when a backend creates a signed link for each recipient. The token identifies the customer before the download page opens.
Generate the JWT on a server with the token API. The API key requires the AuthenticationToken.Write scope. The response returns one JWT per claim set. Add that JWT as the neo.authToken delivery URL parameter.
Tokens are valid for 10 years by default. Set validityDuration to shorten this period. For example, 1.00:00:00 creates a one-day validity period.
Generate tokens on a server only. Never expose an API key or token-generation logic in browser code or email templates.
Add campaign tracking
Add neo.src to record how a customer reached the download page. Its format is tags|medium|origin.
tags are comma-separated categories, such as
email-campaign,loyalty.medium is a channel, such as
email,sms, orqr.origin is the referring source. The HTTP
Refererheader is used when omitted.
For example, a loyalty email can use neo.src=email-campaign,loyalty|email|crm.
Validate the delivery flow
Test each page with a delivery URL that targets known data.
Confirm that a single-pass page displays the expected pass.
Confirm that a pass-list page returns every expected pass.
Confirm that inactive passes follow the chosen display setting.
Confirm that an altered identifier or signature does not resolve a pass.
Choose the right delivery channel
Download pages host the pass-delivery experience. Other channels control where that experience starts.
Enrolment form — capture data before issuing a pass.
On your website — add wallet actions to an existing website.
Via Email — send secure pass links to existing customers.
On your mobile app — launch native wallet installation from an app.
FAQ
When should a pass-list page be used?
Use a passList page when one delivery URL can resolve several passes. Booking confirmations and account areas are common examples.
Can one brand use several download pages?
Yes. Multiple pages can use the same type. Give each page a distinct slug for its delivery journey.
Can a download page register a customer?
No. Use an Enrolment form when customer identity must be captured before pass issuance.
Last updated