vcard4reseller/docs/WALLET-SETUP.md

Wallet-Pässe einrichten (Apple & Google)

Schritt-für-Schritt, um die „Zur Wallet hinzufügen"-Funktion scharf zu schalten. Ohne diese Zugangsdaten bleibt das Feature ausgeblendet. Ein Mac ist nicht nötig – alles geht per OpenSSL.

Die fertigen Dateien und Werte trägst du am Ende als Environment-Variablen ein:

• Lokal (Docker): Dateien nach backend/var/wallet/ legen (ist gitignored), Werte in backend/.env.local. Pfade sind Container-Pfade /app/var/wallet/....
• Produktiv: Dateien außerhalb des Webroots auf den Server, Werte in der Server-Env / .env.prod.local.

---

A) Apple Wallet (PassKit)

Voraussetzung: kostenpflichtiger Apple Developer-Account.

1. Pass Type ID anlegen

1. https://developer.apple.com/account → Certificates, Identifiers & Profiles → Identifiers → +.
2. Typ Pass Type IDs wählen → Beschreibung + Identifier vergeben, z. B. pass.de.vcard4reseller.card.
3. Dieser Identifier ist später APPLE_WALLET_PASS_TYPE_ID.

2. Privatschlüssel + CSR erzeugen (per OpenSSL)

mkdir -p backend/var/wallet && cd backend/var/wallet
openssl genrsa -out key.pem 2048
openssl req -new -key key.pem -out request.csr \
  -subj "/emailAddress=DEINE@MAIL.de/CN=vcard4reseller Pass/O=vcard4reseller/C=DE"

key.pem ist dein unverschlüsselter Privatschlüssel (→ APPLE_WALLET_KEY_PASSWORD bleibt leer).

3. Zertifikat erstellen & als PEM speichern

1. Im Apple-Portal beim Pass Type ID → Create Certificate → die eben erzeugte request.csr hochladen.
2. Das resultierende pass.cer (DER) herunterladen → nach backend/var/wallet/ legen → umwandeln:

openssl x509 -inform DER -in pass.cer -out cert.pem

→ cert.pem = APPLE_WALLET_CERT_PATH.

4. Apple-WWDR-Zwischenzertifikat

1. https://www.apple.com/certificateauthority/ → Worldwide Developer Relations Intermediate Certificate (aktuell G4) herunterladen (AppleWWDRCAG4.cer).
2. Umwandeln:

openssl x509 -inform DER -in AppleWWDRCAG4.cer -out wwdr.pem

→ wwdr.pem = APPLE_WALLET_WWDR_PATH.

5. Team ID

https://developer.apple.com/account → Membership → Team ID (10 Zeichen) = APPLE_WALLET_TEAM_ID.

Ergebnis (Env)

APPLE_WALLET_PASS_TYPE_ID=pass.de.vcard4reseller.card
APPLE_WALLET_TEAM_ID=ABCDE12345
APPLE_WALLET_ORG_NAME=vcard4reseller
APPLE_WALLET_CERT_PATH=/app/var/wallet/cert.pem
APPLE_WALLET_KEY_PATH=/app/var/wallet/key.pem
APPLE_WALLET_KEY_PASSWORD=
APPLE_WALLET_WWDR_PATH=/app/var/wallet/wwdr.pem

Falls du das Zertifikat als .p12 aus dem Keychain exportierst statt per CSR: openssl pkcs12 -legacy -in Cert.p12 -clcerts -nokeys -out cert.pem und openssl pkcs12 -legacy -in Cert.p12 -nocerts -nodes -out key.pem.

---

B) Google Wallet

Voraussetzung: Google-Konto + Google Cloud (kostenlos).

1. Wallet API aktivieren

https://console.cloud.google.com → Projekt wählen/anlegen → APIs & Dienste → Google Wallet API suchen → Aktivieren.

2. Issuer-Account anlegen

1. https://pay.google.com/business/console → Google Wallet API → Issuer-Profil anlegen.
2. Die Issuer ID (Zahl) = GOOGLE_WALLET_ISSUER_ID.

3. Service-Account + JSON-Key

1. Cloud Console → IAM & Verwaltung → Dienstkonten → Dienstkonto erstellen.
2. Anlegen, dann Schlüssel → Neuen Schlüssel → JSON → herunterladen.
3. JSON nach backend/var/wallet/google-sa.json legen → GOOGLE_WALLET_SERVICE_ACCOUNT.

4. Service-Account dem Issuer freigeben

Im Google Pay & Wallet Console → Issuer → Users / Nutzer → die E-Mail des Dienstkontos (...iam.gserviceaccount.com) mit Rolle Developer hinzufügen. Sonst → 403 beim Speichern.

Ergebnis (Env)

GOOGLE_WALLET_ISSUER_ID=3388000000000000000
GOOGLE_WALLET_SERVICE_ACCOUNT=/app/var/wallet/google-sa.json
GOOGLE_WALLET_CLASS_SUFFIX=vcard_generic

Demo-Modus: Solange der Issuer noch nicht von Google freigegeben ist, können nur Test-Nutzer (im Pay & Wallet Console unter dem Issuer hinzugefügt) Pässe speichern. Für die Veröffentlichung muss der Issuer den Google-Freigabeprozess durchlaufen. Logos erscheinen nur, wenn das Firmen-Branding eine öffentliche https-Logo-URL hat.

---

Aktivieren & testen

1. Werte in backend/.env.local (lokal) bzw. Server-Env eintragen.
2. Cache leeren: docker compose exec php php bin/console cache:clear.
3. Ein Mitarbeiter mit shortCode → öffentliche Profilseite zeigt jetzt den QR „Zur Wallet hinzufügen". Direktlinks: /w/{shortCode} (Landing), /w/{shortCode}/apple.pkpass, /w/{shortCode}/google.
4. Auf dem Smartphone scannen/öffnen → „Zu Apple/Google Wallet".

Hinweis: Self-signed Test-Zertifikate erzeugen technisch valide Pässe, werden aber von Apple/Google nicht akzeptiert – für echte Pässe sind die obigen echten Zugangsdaten nötig. Der automatische Over-the-air-Sync (Apple APNs / Google Objekt-Patch bei Datenänderung) ist noch nicht umgesetzt; bisher wird der Pass beim Hinzufügen erzeugt.