Testing and troubleshooting.
Verify Apple Wallet end to end and fix certificate, badge, generation, display, and stale-pass problems.
Release test checklist
Use a separate development or staging Pass Type ID. Keep every credential and generated test package outside Git.
- In System settings → Integrations → Apple Wallet, save and validate the full identity.
- Download the administrator test pass and install it on an iOS Simulator and a physical iPhone.
- Ensure a test business is entitled, then enable one loyalty card, stamp card, voucher, and prepaid-pass product.
- Add each real member pass on the physical iPhone and review the face, logo/strip crop, localized labels, collapsed-stack header, and the Current details, Support, and Privacy links on the back.
- Scan each QR through the intended staff workflow. Confirm a scan never bypasses staff sign-in, business ownership, current status, expiry, balance, limits, or redemption rules.
- Change points/stamps/visits or redeem the voucher. Confirm Current details and the staff scan show the current state while the Apple pass stays unchanged.
- Change the business name, colors, or Wallet artwork. Download again and confirm Apple Wallet replaces the pass with the new presentation.
- Disable one product, remove the business entitlement, and test an expired/redeemed/used-up subject. New downloads must stop without exposing another business or deleting loyalty history.
- Run retention and privacy deletion tests. Confirm private packages disappear and no secret enters logs, exports, APIs, or support output.
- Check the partner page at 320 px, desktop width, dark mode, keyboard-only navigation, one RTL locale, and all twelve supported locales.
Apple Watch display should be reviewed when a paired watch is available. It is not required to run the staff scanner, and Apple's compact layout may differ from the representative partner preview.
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.