Skip to main content

Apple Wallet

Put an Add to Apple Wallet button on every ticket, free registrations included. The pass carries the same QR code the ticket page shows, so it scans at your door unchanged. Off until you configure it.

Overview

This page is for whoever runs the install. Apple Wallet passes are switched on for the whole install by environment variables: there is no setting for them in the app, and nothing for a schedule owner to turn on. Once they are set, every eligible ticket carries an Add to Apple Wallet button, and tapping it on an iPhone or a Mac opens a pass that holds the ticket's own QR code. It works beside Google Wallet, and either can be on without the other.

Where the Button Appears

Place What the buyer sees
The ticket page The button under the QR code, first on an iPhone, iPad or Mac
The order page For a purchase that spans several events, one button for each event
The ticket confirmation and reminder emails The button under the button that opens the ticket

A ticket is eligible when it is paid (a free registration counts), not deleted, for an event that is not cancelled and is not an appointment booking, and its payment plan, if it has one, is not behind. Google Wallet uses the same rule.

Included on every plan

Wallet passes are free on every tier, and a selfhosted install resolves to Enterprise anyway. Without the environment variables below no button renders anywhere, no email carries a link, and the pass address answers 404.

Prerequisites

  • A paid Apple Developer Program membership. Passes are signed in this account's name, so it belongs to whoever operates the installation
  • A Mac with Keychain Access to make the certificate request, or OpenSSL on any machine
  • PHP's openssl, zip and gd extensions, which the install already needs. Without them the button stays hidden rather than failing

Setup Instructions

1. Create a Pass Type ID

  1. In Certificates, Identifiers & Profiles, add an identifier of the type Pass Type IDs
  2. Give it a reverse-domain name such as pass.com.example.tickets. This is APPLE_WALLET_PASS_TYPE_ID
  3. Your Team ID, ten characters, is in the top right of the developer site and under Membership. This is APPLE_WALLET_TEAM_ID

2. Create its certificate

  1. Open the Pass Type ID and choose Create Certificate
  2. Upload a certificate signing request: in Keychain Access, Certificate Assistant > Request a Certificate From a Certificate Authority, saved to disk
  3. Download the certificate and open it, so Keychain pairs it with the private key the request made
  4. In Keychain Access, select the certificate with its key and Export it as a .p12 file with a password
A .p12 that will not open

A .p12 exported from an older Keychain can use an algorithm OpenSSL 3 only reads with its legacy provider, and the button then stays hidden. Convert it once to a PEM file holding the certificate and the key, and use that instead: openssl pkcs12 -legacy -in pass.p12 -out pass.pem -nodes, then set APPLE_WALLET_CERTIFICATE to the PEM and leave the password empty.

3. Configure the app

Add these to your .env. .env.example carries the same lines, commented out, in its "Apple Wallet passes (optional)" block.

.env
APPLE_WALLET_PASS_TYPE_ID=pass.com.example.tickets
APPLE_WALLET_TEAM_ID=ABCDE12345
APPLE_WALLET_CERTIFICATE=/var/www/secrets/pass.p12
APPLE_WALLET_CERTIFICATE_PASSWORD=the-export-password

Variable Reference

Variable Description
APPLE_WALLET_PASS_TYPE_ID The Pass Type ID from step 1
APPLE_WALLET_TEAM_ID Your developer Team ID
APPLE_WALLET_CERTIFICATE Either an absolute path to the .p12 (or a PEM file holding the certificate and its key), or the base64-encoded contents of that file, for hosts with no writable file mount
APPLE_WALLET_CERTIFICATE_PASSWORD The export password of the .p12, or of the key in a PEM file
APPLE_WALLET_WWDR_CERTIFICATE Optional. Apple's WWDR G4 intermediate certificate, which every pass signature carries, ships with the app (valid until December 2030). Set this to a path or base64 PEM only when Apple issues a newer one

4. Optional: Apple's badge

Apple licenses its Add to Apple Wallet artwork to each developer account for its own passes, so the app does not ship it, and the button is plain text until you add it. Download the badges from Apple's guidelines and save each language as public/images/wallet/apple/{language}.svg for the pages and {language}.png for email, for example en.svg and en.png. English stands in for a language you have not added. The folder is in .gitignore and is not part of the release, so an update leaves your files where they are; in Docker, mount it as a volume or the files go with the next rebuilt image.

Verifying it works

  1. Register for a free event on your install, or buy a ticket
  2. Open the ticket page: the Add to Apple Wallet button is under the QR code
  3. Tap it on an iPhone, or click it in Safari on a Mac: Wallet shows the pass and offers Add
  4. Scan the pass's QR code with the door scanner: it admits the ticket exactly as the ticket page's code does

What is sent to Apple

Nothing. The pass is a file your install builds and signs when the buyer taps the button, and the buyer's device opens it. It names no web service, so Apple's servers never hear from your install, and the buyer's device never reports back to it. The pass holds the event's name, date and venue, the schedule's name, colour and picture, the ticket type, the attendee's name, the number of guests, any seats, your ticket notes and the link to the ticket page.

How it works

  • A snapshot. The pass is built at the moment it is added and is not updated afterwards, as Google's is not. A changed time or venue reaches the buyer by email; the back of the pass links to the live ticket page
  • On the lock screen. Wallet raises the pass around the start of the event, in the event's own time zone
  • Afterwards. The pass is greyed out three hours after the event ends (an hour after the start when the event has no length). A season pass expires when the pass itself does
  • Colours and picture. The schedule's colour is the background, with white or near-black text, whichever reads; its profile picture is the icon and logo, and the app's own icon stands in when it has none

Troubleshooting

No button appears

All of the pass type id, the team id and a certificate that opens with its password must be set; one missing, an expired or mismatched certificate and key, or a missing zip or openssl extension keeps the feature off: nothing is shown to buyers, and the app's log (storage/logs/laravel.log) says which one, in a warning that starts Apple Wallet: and is written at most once an hour. Check the values, then see A .p12 that will not open. The ticket must also be eligible (see Overview).

The iPhone says the pass cannot be added

The pass type id or team id does not match the certificate, or the certificate was made for another Pass Type ID. Wallet checks that the signature, the pass type id and the team id all belong together.

The button is plain text

Apple's badge is not installed. See step 4.

See Also

Last updated 11 November 2026 Improve this page on GitHub