iOS Certificates

iOS certificates let you sign Apple Wallet passes with your own identity instead of using WalletHero's default certificate. This gives you control over your Pass Type Identifier and displays your company's Team ID on passes.

Why Use Your Own Certificate?

By default, all passes are signed using WalletHero's platform certificate. While this works perfectly for most use cases, you might want your own certificate to:

Default (Platform Certificate)	Your Own Certificate
Pass Type ID: pass.com.wallethero.*	Pass Type ID: pass.com.yourcompany.loyalty
Team ID: WalletHero's	Team ID: Your company's
Quick setup, no Apple account needed	Full branding control

Prerequisites

To use your own certificate, you need:

• Apple Developer Account — Enrolled in the Apple Developer Program ($99/year)
• Workspace Admin Access — Only admins can manage certificates

How Certificates Work

Setup Process

Step 1: Generate a Certificate Signing Request (CSR)

In WalletHero, go to your workspace settings and create a new certificate request. You'll need to provide:

• Certificate Name — A friendly name like "Production Certificate"
• Pass Type Identifier — Your identifier (e.g., pass.com.yourcompany.loyalty)

WalletHero generates a CSR file that contains a public key. The matching private key is securely stored on our servers — it's never exposed or downloadable.

Step 2: Download the CSR File

Download the .certSigningRequest file to your computer. You'll upload this to Apple in the next step.

Step 3: Create Certificate in Apple Developer Portal

1. Go to Apple Developer Portal
2. Navigate to Certificates, Identifiers & Profiles
3. Under Identifiers, create a Pass Type ID if you haven't already
   • Click + → Select Pass Type IDs → Continue
   • Enter a description and your identifier (e.g., pass.com.yourcompany.loyalty)
4. Under Certificates, click + to create a new certificate
5. Select Pass Type ID Certificate → Continue
6. Choose your Pass Type ID from the dropdown
7. Upload the CSR file you downloaded from WalletHero
8. Click Continue and then Download the .cer file

Step 4: Upload the Certificate to WalletHero

Back in WalletHero, upload the .cer file you downloaded from Apple. WalletHero automatically:

• Validates the certificate matches the original CSR
• Extracts the Team ID and expiration date
• Test-signs a pass to verify everything works

Once uploaded, your passes will be signed with your certificate.

Certificate Lifecycle

Certificates have a limited lifespan and go through several stages:

Status	Meaning
Pending CSR	CSR generated, waiting for you to download it
Awaiting Certificate	CSR downloaded, waiting for you to upload the .cer from Apple
Active	Certificate is ready and being used to sign passes
Expired	Certificate has passed its expiration date (398 days from Apple issuance)

Certificate Expiration

Apple certificates are valid for 398 days from the date Apple issues them. WalletHero tracks expiration dates and will notify you before your certificate expires.

When a certificate expires:

• New passes cannot be signed with the expired certificate
• Existing passes in customers' wallets remain valid
• WalletHero automatically falls back to the platform certificate

Recommendation: Set a calendar reminder to renew your certificate 30 days before expiration.

Best Practices

Naming Conventions

Use clear, descriptive names for your certificates:

• ✅ Production Loyalty Card 2024
• ✅ Event Tickets Certificate
• ❌ cert1
• ❌ test

One Certificate Per Workspace

Each workspace can have one active iOS certificate. If you need different Pass Type Identifiers for different programs, consider using separate workspaces.

Keep Track of Expiration

• Note the expiration date when you upload your certificate
• Plan renewal 30 days in advance
• The renewal process is the same as the initial setup

Troubleshooting

"Key mismatch" error when uploading

The .cer file you're uploading was generated from a different CSR. Make sure you upload the certificate that Apple generated from the exact CSR you downloaded from WalletHero.

Solution: Delete the certificate in WalletHero and start the process over with a fresh CSR.

Certificate shows as "Invalid"

The certificate failed validation. This can happen if:

• The certificate file is corrupted
• It's not a Pass Type ID certificate (wrong certificate type)
• It was revoked in Apple Developer Portal

Solution: Check the certificate in Apple Developer Portal and ensure it's a valid Pass Type ID certificate.

Passes still show WalletHero's Team ID

Your certificate might not be active yet. Check that:

1. The certificate status is Active (not Pending or Awaiting)
2. You're creating new passes (existing passes keep their original signature)

For Developers

For technical implementation details, API endpoints, and SDK methods, see:

• iOS Certificates API Reference — REST API endpoints
• WorkspacesService SDK — TypeScript SDK methods