Testing and troubleshooting.
Verify Apple Wallet end to end and fix certificate, badge, generation, display, and stale-pass problems.
On this page
Start with the common-problems table. If a member cannot add a pass, check the program's Apple Wallet switch and ask the administrator to check signing health.
Test your setup
- In System settings → Integrations → Apple Wallet, validate the signing identity.
- Download the administrator test pass and add it on an iPhone.
- Enable Apple Wallet for a test program through the business dashboard.
- Add that program's pass from an eligible member account.
- Scan it through the normal staff workflow.
- Open Current details on the back to check the live program page.
The Apple pass does not display changing balances. Its QR leads staff to a live check. See Using an Apple Wallet pass.
Renew or reset?
Choose the least disruptive action. Most certificate problems need a repair or renewal, not an identity reset.
| Your situation | Choose | What to do |
|---|---|---|
| Your certificate will expire soon | Renew | Create a certificate for the same Pass Type ID, export a new .p12, and upload it through the normal form |
| Your certificate has expired | Renew | Keep the same Pass Type ID and Team ID, upload the replacement set, validate it, and test a sample |
| The WWDR certificate has expired | Replace WWDR | Download Apple's current WWDR certificate and save the full matching set |
Reward Loyalty rejects the .p12 password |
Repair | Check the password or export a modern AES-encrypted .p12; do not reset the identity |
| You lost the server copy but have a working backup | Restore | Upload the backed-up files through the normal form and validate them |
| A private key may have leaked | Contain first | Revoke the affected certificate, follow your incident plan, and ask the Apple team owner whether the Pass Type ID can remain |
| You entered the wrong identity and no pass has been issued | Correct it | Upload the correct complete identity through the normal form |
| You must change the Pass Type ID or Apple Team after passes were issued | Reset | Read the full reset guide, prepare the replacement and member message, then use Reset Apple Wallet identity |
| One business wants to stop using Apple Wallet | Disable | Remove its permission or turn off its individual programs |
| The business changed its name, colors, or Wallet artwork | Download again | Keep the identity and let the member add the same pass again |
Read What “Break glass” means before any identity reset. Opening the review panel changes nothing. The reset occurs only after the backup confirmation, typed phrase, current administrator password, and final red button.
Common problems
| Problem | What to check |
|---|---|
| Apple Wallet button is missing | Confirm healthy signing, Gold/Platinum or per-business permission, the individual product toggle, the member relationship/current eligibility, and a supported Apple device. Reward Loyalty already includes the official badge files |
| Page says setup is not ready | Ask the installation operator to open the Apple Wallet admin screen and run validation |
.p12 password invalid or file unreadable |
Re-enter the export password. Confirm the certificate and private key were exported together. Some older Keychain exports use legacy RC2 encryption that OpenSSL 3 does not read by default; securely re-export or convert to a modern AES-encrypted PKCS#12 without putting either password on the command line or in shell history |
| Private key missing | In Keychain Access → My Certificates, expand the Pass Type ID certificate. Its key must be underneath it. Recreate the certificate from a CSR whose key lives on this Mac if necessary |
| Pass Type ID or Team ID mismatch | Copy both from the same Apple Developer team and certificate. Do not use an App ID, Service ID, Merchant ID, or the identifier from another team |
| WWDR missing or wrong | Use Apple's active Worldwide Developer Relations G4 intermediate for Pass Type ID certificates, downloaded from Apple PKI |
| Certificate expired | Renew for the same Pass Type ID, export the new certificate plus private key, upload the complete matching set, validate, and test before replacing production |
| Certificate appears untrusted in Keychain | Install the current WWDR intermediate, reopen the certificate, and confirm the chain is valid. Reward Loyalty validates the uploaded chain independently |
| Add sheet says the pass is invalid | Check application logs for the controlled reason, validate artwork and package size, then use the operator sample. Do not unzip and rezip a signed package. The manifest and signature would no longer match |
| Badge missing in one supported language | Check that the server runs an unmodified current Reward Loyalty release, then redeploy or repair the release files. Do not download a replacement or make a substitute button |
| Images crop badly | Use a text-free strip image and adjust horizontal/vertical focal points on the partner Apple Wallet page |
| Member cannot find a balance or status on the pass | Open Current details on the back. The Apple pass does not contain changing loyalty values |
Current details returns 403 after APP_KEY changed |
Restore the backed-up APP_KEY. Every pass stores a signed Current details link that depends on APP_KEY. If you cannot restore it, save the Apple Wallet credentials again and ask the member to download the pass again |
| Duplicate-looking pass | Download from the same Reward Loyalty subject. The stable serial should replace it. A different issued prepaid pass is intentionally a separate pass |
| QR opens a sign-in page | Staff authentication is required by design. Sign in as staff with access to that business and continue |
| QR shows unavailable after a program change | Reward Loyalty rechecks live server state. An expired, redeemed, disabled, exhausted, or foreign item cannot authorize an action |
| Generation is busy | Retry once after a few seconds. Reward Loyalty serializes concurrent generation for the same pass and lets later requests reuse the completed cache |
Health Center and logs
The admin Health Center reports Apple Wallet runtime support, signing health/expiry, private-storage access, scheduler state, and whether an operator sample has been generated. Partner analytics provides only aggregate delivery behavior.
Application logs may contain internal IDs, counts, durations, and controlled reason codes. They must not contain the .p12 password, private key, certificate body, APP_KEY, pass authentication token, QR value, member profile, package bytes, or private filesystem path.
Development tools
Xcode and the iOS Simulator are optional for production but strongly recommended for development. Install Xcode from Apple, open Xcode → Settings → Components, install an iOS Simulator runtime, select Xcode under Settings → Locations → Command Line Tools, then boot an iPhone simulator. A real iPhone is still the final proof because Simulator success does not guarantee physical-device behavior.