Stripe Integration Guide

Follow these steps to connect Stripe and auto-generate license keys upon successful payments.

1. Create a Stripe App

1. Log into Stripe Dashboard.
2. Get your Publishable key and Secret key (test mode for sandbox).

2. Configure Webhook

1. In Stripe, add a webhook endpoint to: https://YOUR-SITE/api/stripe/webhook
2. Subscribe to events: checkout.session.completed, payment_intent.succeeded.
3. Copy the Signing secret (e.g., whsec_...).

3. Add the App in ExisOne

1. Open Stripe Integration > Stripe Apps and Events.
2. Add a new app with your Publishable key, Secret key, and Webhook signing secret.
3. Mark it Active and (optionally) Default.

4. Map Your Product

Ensure your ExisOne product has defaults set:

• Default License Days: 0 for Perpetual, or a positive number.
• Trial Days: number of days for trial when validating without a key.

5. Test Purchase

1. Open Stripe Integration > Test Purchase.
2. Select your product, quantity, and Stripe app (test mode).
3. Complete checkout and verify the license key(s) under the Dashboard.

6. Notes

• We pass productId and quantity in Checkout Session metadata and use them in the webhook.
• Perpetual (0 days) overrides any incoming days; otherwise an explicit plan days value overrides product defaults.
• Emails use the product’s template (placeholders: {{ActivationKey}}, {{ProductName}}, {{CustomerEmail}}).
• Trials: validation without a key returns a trial if the device was never activated for that product and the product has TrialDays > 0.

Troubleshooting

Signature verification fails ("no app matched signature")

• Ensure the webhook Signing secret (whsec_...) is copied from the exact Stripe endpoint that targets https://YOUR-SITE/api/stripe/webhook (test vs live must match).
• Re-enter the secret in Stripe Apps and Events and Save; avoid leading/trailing spaces.
• We tolerate Stripe API version mismatches during verification. Optionally, set your Stripe webhook endpoint API version to match your library (e.g., 2024-04-10) for stricter validation.
• Timestamp tolerance is 300s. Use a brand-new checkout rather than resending very old events.

Diagnostics

Verify that your saved secrets decrypt correctly for the right tenant:

GET /api/stripe/diagnostics
Authorization: ExisOneApi <your_token>

Both HasSecret and HasWebhookSigningSecret should be true for your app. If not, generate/activate a tenant key (Tenant Keys page), then re-save your secrets.

Event log

• View events in the UI or GET /api/stripe/events.
• Status values: failed (includes first error detail), received, verified.

7. Go Live

1. Switch to live keys in Stripe and set your site’s live webhook endpoint.
2. Update your ExisOne Stripe app to Live and Active.