How Kemicard works under the hood: the Salesforce layer, the stateless Kemicard Server, and the Apple and Google Wallet ecosystems. Based on the Kemicard Technical Documentation (v1.1).
Platform structure
Kemicard is a Salesforce-native application purpose-built for delivering digital experiences through mobile wallets. While Kemicard functions within Salesforce, its true power lies in its seamless extension via a stateless orchestration layer — the Kemicard Server — hosted in Kemisoft’s secure, enterprise-grade cloud environment.
This server acts as a middleware abstraction and orchestration engine. It encapsulates and translates Salesforce-native data structures into the pass formats required by Apple Wallet and Google Wallet. By isolating this logic in a cloud-based, stateless server, any future changes made by Apple or Google to their wallet APIs remain transparent to client organizations — significantly reducing development overhead, maintenance burden, and the risk of integration failure from upstream platform changes.
Key architectural components
Salesforce layer
- Template and Pass records — custom objects that define the layout, branding, and content of each pass, supporting custom fields, barcodes, and images.
- Apex services and Flows — the key method is
upsertPasses, which handles both creation and updates of digital passes based on user data or events. - OAuth-secured communication with the Kemicard Server — via the Kemicard Digital Pass Connected App; OAuth 2.0 tokens authenticate every request between Salesforce and the Kemicard Server.
Kemicard Server
- Stateless architecture — each request is processed independently; no business or customer data is stored.
- Pass generation & cryptographic signing — transforms Salesforce data into wallet formats and signs Apple .pkpass bundles with Apple-issued certificates.
- Integration hub — interfaces with Apple Push Notification Services (APNs) and Google Wallet APIs for device registrations and real-time updates.
- Secure endpoints — HTTPS with TLS encryption and token-based authentication on every call.
Apple & Google Wallet ecosystems
Users receive an email or notification with a secure link to download their pass into Apple Wallet or Google Wallet. With push notifications and automatic updates enabled, changes to the associated Salesforce data propagate in real time through APNs or Google's messaging systems — a living digital card experience.
Generating and updating passes: upsertPasses
Pass generation is driven by a PassRequest object built in Apex or Flow:
| Field | Type | Purpose |
|---|---|---|
templatePassId | String | ID of the Template Pass record |
passDetails | List | Ordered values matching Template Pass Field Content records |
passBarcodes | List | Ordered barcode values (QR, PDF417) |
passLocationDetails | List | Optional locations (name, latitude, longitude, altitude) |
passSendToEmails | List | Recipient email addresses |
whatId | Id (optional) | Record merged into the email template |
attachmentName | String (optional) | Custom name for the attached pass file |
passId | String (optional) | Existing pass ID — include it to update instead of create |
// Apex trigger handler
KemicardService.upsertPasses(List<PassRequest> passRequests);passDetails and passBarcodes must strictly match the Order defined on their Template Pass Field Content and Template Barcode records.To update an existing pass, include the passId: the Kemicard Server recognizes the pass, regenerates it with the new data, and synchronizes changes to the user's wallet — no manual re-download required.
Image requirements
| Type | Apple (px) | Google (px) | Size / formats |
|---|---|---|---|
| Logo | 150×150 | 150×150 | <100 KB — PNG (Apple); JPG/JPEG/PNG (Google) |
| Notification icon | 87×87 | N/A | <100 KB — PNG (Apple) |
| Strip / hero | 1125×294 | 1125×294 | <100 KB — PNG (Apple); JPG/JPEG/PNG (Google) |
| Detail (Google) | N/A | 300×300 | <100 KB — JPG/JPEG/PNG |
Mandatory fields in the Template Builder
- Apple: Logo Image (Front tab), Strip Image (Front tab), Icon Image (Notification tab), and at least one field from Field Selection.
- Google: Logo Image and Hero Image (Front tab), Detail Image (Back Side tab), Card Title (Front tab), Header field configuration, and one field from field configuration.
Personas
- Initiator (Salesforce user) — an admin, marketer, or operations user who defines templates, creates and maintains pass records, sends passes, and manages updates.
- End user (wallet owner) — receives an email with a secure download link, adds the pass to Apple Wallet or Google Wallet, and receives real-time updates and push notifications.
Security model
- OAuth 2.0, scoped — tokens granted to the Connected App are tightly scoped, short-lived, and securely refreshed; admins explicitly authorize the app before any communication occurs.
- TLS, authentication & access control — all endpoints enforce TLS encryption, token authentication, firewalls, role-based access control, and infrastructure-level identity and access management (IAM) policies.
- No persistence of business data — data from Salesforce is used only for the lifetime of the request; no PII or customer content is stored on Kemicard Server. Only essential logs (status codes, request metadata) are retained temporarily under strict retention policies — simplifying GDPR and CCPA compliance.
- Forward compatibility through API abstraction — Apple/Google API changes are absorbed by the Kemicard Server; no Salesforce-side modifications are ever needed.
Kemicard Scanner (native component)
The Kemiscanner is a native Salesforce component available in the Salesforce UI or Experience Cloud UI — no external calls are necessary. Each scan reads the QR/barcode, validates it against Salesforce in real time, shows Valid / Invalid / Duplicate feedback to staff, and logs the scan event for attendance, auditing, and downstream automation. It is browser-based, mobile friendly, and optimized for high-throughput entry.
Screenshots
Related: Installation Guide · Flow Integration & Apex Action · API Reference