Recurring Membership & Subscription Architecture
For fitness clubs, coworking spaces, transit networks, subscription boxes, and professional associations, digital wallet passes act as dynamic, real-time membership credentials. Unlike static cards, a subscription pass in Apple Wallet and Google Wallet can update its expiration date, membership status, and barcode validity automatically as recurring billing cycles succeed, fail, or cancel.
Passinstance synchronizes subscription billing agreements (from Stripe Billing, PayPal Subscriptions, or custom subscription backends) with the pass lifecycle using automated webhook handlers and silent push notifications:
Linking Payment Subscriptions to Pass Records
To ensure seamless recurring lifecycle synchronization, each pass must be bound to the customer's subscription record using the externalId field:
-
1
When Customer Subscribes: When an initial subscription is created in Stripe or PayPal, your backend or Passinstance's checkout integration captures the subscription ID (e.g.
sub_1Q8xYz2e...) or customer ID (e.g.cus_987654...). -
2
Binding to
externalId: Passinstance stores this ID inPass.externalId. -
3
Setting Initial Expiration: The pass's initial
expirationDateis set to the Unix timestamp ofcurrent_period_endfrom the billing provider.
Webhook Lifecycle Events & Automated Actions
Passinstance listens to recurring billing webhooks and triggers corresponding pass state updates:
1. Subscription Renewed (invoice.payment_succeeded / BILLING.SUBSCRIPTION.RENEWED)
When a monthly or annual subscription payment succeeds:
-
Action: Passinstance locates the pass matching
externalIdand extendspass.expirationDateto the new billing cycle end date. -
Field Update: Any dynamic field displaying
{validUntil}or{membershipExpiry}updates to the new date. -
Push Notification: Apple Wallet receives a silent APNs update; Google Wallet updates the object via REST. The lockscreen may display a subtle update banner (e.g. "Membership renewed through March 31").
2. Payment Failed / Past Due (invoice.payment_failed / INVOICE.PAYMENT_FAILED)
If a recurring charge fails due to an expired credit card or insufficient funds:
-
Action: The pass remains active during your configured grace period (e.g. 7 days).
-
Field Update: An auxiliary or secondary field updates from
"ACTIVE"to"PAYMENT PAST DUE". -
Alert Notification: A push notification is sent to the customer's device: "Please update your payment method to keep your membership active."
3. Subscription Cancelled or Terminated (customer.subscription.deleted / BILLING.SUBSCRIPTION.CANCELLED)
When a customer terminates their subscription:
-
Action: At the conclusion of the paid billing period, Passinstance updates the pass status to
EXPIREDor setspass.voided = true. -
Visual Deactivation: Apple Wallet crosses out the check-in barcode and displays a "Pass Voided" badge. Google Wallet marks the card as expired.
-
Scanner Rejection: Physical validation at gym turnstiles or front desks via Passinstance Scanner immediately displays a red screen with
EXPIREDorVOIDED.
Step-by-Step Setup: Connecting Stripe Billing to Passinstance
Step 1: Connect Stripe in Workspace Settings
-
1
Navigate to Settings -> Integrations -> Payments in the Passinstance dashboard.
-
2
Connect your Stripe account.
Step 2: Register the Stripe Webhook Endpoint
In your Stripe Dashboard -> Developers -> Webhooks, add an endpoint pointing to Passinstance:
https://api.passinstance.com/api/v1/webhooks/stripe-billing
Select the following events:
-
invoice.payment_succeeded -
invoice.payment_failed -
customer.subscription.created -
customer.subscription.updated -
customer.subscription.deleted
Step 3: Configure Subscription Pass Expiration Rules
In your Pass Template settings:
-
1
Open Functionalities -> Expiration & Validity.
-
2
Select Dynamic Subscription Expiration.
-
3
Choose the post-cancellation behavior: Expire Pass (remains in wallet history) or Void Pass (crosses out barcode immediately).
Managing Subscription Status with Passinstance Scanner
When gym staff or venue hosts scan a member's pass using the Passinstance Scanner App (Passinstance Scanner):
| Subscription State | Scanner Screen | Scanner Response | Result |
|---|---|---|---|
| Active & Paid | Green Screen | VALID | Member admitted. Displays customer name and active tier. |
| Payment Past Due (Grace Period) | Amber Screen | WARNING | Staff alerted: "Grace period active. Prompt member to update card." |
| Cancelled / Expired | Red Screen | EXPIRED | Turnstile remains locked. Displays "Membership expired on [Date]". |
| Revoked / Voided | Red Screen | VOIDED | Check-in blocked. Displays "Card has been voided by issuer". |
Related Documentation
-
Selling Passes — One-time paid pass sales via PassFlow.
-
Scan Modes & Validation Rules — Configuring scanner rules and turnstile admittance.
-
Payment Methods — Managing workspace payment methods.
-
Update Existing Passes — APNs and Google Wallet live push mechanics.
