Stripe Integration Guide

Connect your Stripe account to ExisOne to automatically generate and email license keys when customers purchase on your website.

1. Get Your Stripe API Keys

1. Log into Stripe Dashboard.
2. Go to Developers > API keys.
3. Copy your Publishable key (pk_test_... or pk_live_...).
4. Copy your Secret key (sk_test_... or sk_live_...).

2. Configure Stripe Webhook

1. In Stripe Dashboard, go to Developers > Webhooks.
2. Click Add endpoint.
3. Set the endpoint URL to: https://www.exisone.com/api/stripe/webhook
4. Select these events to listen for:
   • checkout.session.completed - Primary event for payments
   • payment_intent.succeeded - Backup for one-time payments
   • invoice.paid - For subscription renewals
5. Click Add endpoint, then copy the Signing secret (starts with whsec_).

3. Register Your Stripe App in ExisOne

1. In ExisOne, go to Stripe Integration > Stripe Apps and Events.
2. Click Add App and enter:
   • Publishable key - from step 1
   • Secret key - from step 1
   • Webhook signing secret - from step 2
   • Default Currency - the currency Stripe will charge customers in for one-time Checkout sessions (e.g. usd, aud, eur). See Currency Selection below.
3. Set Is Live to match your keys (unchecked for test keys, checked for live keys).
4. Check Active and Default.
5. Save the app.

Currency Selection

The Default Currency dropdown is populated from the EO_Currency reference table. It controls the currency used when ExisOne creates a one-time Stripe Checkout session for this app. Stripe requires that the currency match what your Stripe account is configured to accept in your country/region — if a currency is rejected at checkout, verify your Stripe account settings.

• One-time payments use this default currency. It is stored per Stripe app, so different apps under one tenant can charge in different currencies.
• Per-request override: the POST /api/stripe/checkout/session endpoint accepts an optional currency field that overrides the app default for a single session. Useful for showing a storefront price in the visitor's local currency.
• Subscriptions use the currency embedded in the Stripe price_… ID you map under Subscription Price Mappings. The Default Currency setting is ignored for subscription checkouts.
• Zero-decimal currencies (JPY, KRW, and a few others) are flagged in the currency table; ExisOne automatically sends integer amounts to Stripe for those rather than multiplying the product price by 100.
• Adding currencies: if you need a code that isn't in the dropdown, insert a row into EO_Currency with IsActive = 1. Codes must be lowercase ISO 4217 (Stripe requirement).

ExisOne uses the webhook signing secret to verify incoming webhooks are from your Stripe account.

App Status Indicators

After saving, the Stripe Apps table shows a Status column to help you verify your configuration:

4. Configure Your Product in ExisOne

For each product you sell, configure these settings on the Products page:

• Auto Email: Check this box to automatically email license keys after purchase.
• Default License Days: Set to 0 for Perpetual, or a number of days for time-limited licenses.
• Email Template (optional): Customize the email sent to customers.

4b. Configure Subscription Price Mappings (Optional)

If you want to sell subscription-based licenses where ExisOne creates the Stripe checkout session, you can map your products to Stripe Price IDs:

1. In Stripe Dashboard, create a recurring price for your product under Products.
2. Copy the Price ID (starts with price_...).
3. In ExisOne, go to Stripe Apps and Events.
4. Scroll to Subscription Price Mappings.
5. Click Save after entering:
   • Stripe App - Select your Stripe app
   • Product - Select your ExisOne product
   • Stripe Price ID - Paste the Price ID from Stripe
   • Display Name (optional) - e.g., "Monthly", "Annual"
   • Display Price (optional) - e.g., 9.99

You can map multiple prices to the same product for different tiers (e.g., "Starter" at $9.99/month and "Pro" at $29.99/month).

5. Find Your Product ID

You'll need your Product ID to include in Stripe checkout sessions. Find it on the Products page - it's displayed in the ID column.

6. How the Payment Flow Works

Your Website                        Stripe                         ExisOne
      |                                 |                               |
      |-- Create checkout session ----->|                               |
      |   (using Stripe API directly)   |                               |
      |   metadata: { productId: "42" } |                               |
      |                                 |                               |
      |<---- Return checkout URL -------|                               |
      |                                 |                               |
      |   Customer completes payment    |                               |
      |                                 |                               |
      |                                 |-- Webhook ------------------ >|
      |                                 |                               |
      |                                 |   Verify signature (matches   |
      |                                 |   your stored webhook secret) |
      |                                 |                               |
      |                                 |   Extract productId from      |
      |                                 |   metadata                    |
      |                                 |                               |
      |                                 |   Generate license key        |
      |                                 |                               |
      |                                 |   Email key to customer       |
      |                                 |                               |

7. Integrate Stripe on Your Website

Use Stripe's API directly on your website. The key is to include your ExisOne productId in the checkout session metadata.

Server-Side (Node.js Example)

const stripe = require('stripe')('sk_test_YOUR_SECRET_KEY');

app.post('/create-checkout-session', async (req, res) => {
    const session = await stripe.checkout.sessions.create({
        mode: 'payment',
        line_items: [{
            price_data: {
                currency: 'usd',
                unit_amount: 2999,  // $29.99 in cents
                product_data: {
                    name: 'Pro License',
                },
            },
            quantity: 1,
        }],
        metadata: {
            productId: '42',    // Your ExisOne Product ID - REQUIRED
            quantity: '1'       // Number of licenses to generate
        },
        customer_email: req.body.email,  // Optional: pre-fill customer email
        success_url: 'https://yoursite.com/success',
        cancel_url: 'https://yoursite.com/cancel',
    });

    res.json({ url: session.url });
});

Client-Side (JavaScript)

<button onclick="buyLicense()">Buy Pro License - $29.99</button>

<script>
async function buyLicense() {
    // Call your server to create checkout session
    const response = await fetch('/create-checkout-session', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ email: customerEmail })
    });

    const { url } = await response.json();
    window.location.href = url;  // Redirect to Stripe Checkout
}
</script>

Required Metadata Fields (One-Time Payments)

7b. Subscription Licenses

For subscription-based licensing (e.g., annual renewals), ExisOne generates a new license key on each billing cycle - both on initial signup and every renewal.

Server-Side Subscription Example (Node.js)

const stripe = require('stripe')('sk_test_YOUR_SECRET_KEY');

app.post('/create-subscription-checkout', async (req, res) => {
    const session = await stripe.checkout.sessions.create({
        mode: 'subscription',
        line_items: [{
            price: 'price_YOUR_RECURRING_PRICE_ID',  // Created in Stripe Dashboard
            quantity: 1,
        }],
        // IMPORTANT: Use subscription_data.metadata for renewals to work
        subscription_data: {
            metadata: {
                productId: '42',    // Your ExisOne Product ID - REQUIRED
                quantity: '1'       // Number of licenses per renewal
            }
        },
        customer_email: req.body.email,
        success_url: 'https://yoursite.com/success',
        cancel_url: 'https://yoursite.com/cancel',
    });

    res.json({ url: session.url });
});

How Subscription Licensing Works

Initial Subscription                          Renewals (Annual)
        |                                            |
        |-- checkout.session.completed -->           |-- invoice.paid ----------------->
        |                                            |
        |   ExisOne reads productId from             |   ExisOne fetches subscription
        |   session metadata                         |   from Stripe, reads productId
        |                                            |   from subscription metadata
        |                                            |
        |   Generates license key                    |   Generates NEW license key
        |   Emails to customer                       |   Emails to customer
        |                                            |

Required Metadata Fields (Subscriptions)

7c. Using Stripe Payment Links (No Website Required)

If you want to sell a license without building a checkout flow on your website, you can create a Stripe Payment Link directly in the Stripe Dashboard and email it to your customer. ExisOne will still auto-generate and deliver the license key as long as you attach the right metadata to the link.

Payment Links are ideal for:

• One-off invoices or custom quotes sent by email.
• Sales you handle manually (phone, chat, in-person).
• A simple "Buy Now" URL embedded in a blog post or social media bio.

How to create the link

1. In Stripe Dashboard, go to Payment Links > + New.
2. Select the Stripe Product and Price you want to sell (or create a new one).
3. Leave Collect customer email enabled (it is by default) — ExisOne uses this to deliver the license key.
4. Expand Advanced options > Metadata and add the following keys:

Save the link, copy the URL, and send it to your customer. When they complete payment, Stripe fires a checkout.session.completed webhook that ExisOne receives; the metadata you set on the Payment Link is forwarded on that session automatically, and the license key is generated and emailed to the address the customer entered at checkout.

8. Test Your Integration

1. Make sure you're using test mode keys (starting with pk_test_ and sk_test_).
2. Trigger a checkout from your website.
3. Complete payment using Stripe test card: 4242 4242 4242 4242 (any future expiry, any CVC).
4. Check Stripe Apps and Events in ExisOne - you should see the webhook event with status "verified".
5. Verify the license key appears under License Keys in the ExisOne dashboard.
6. Confirm the customer received the license key email (if Auto Email is enabled).

You can also use ExisOne's built-in Test Purchase page to verify webhook connectivity before integrating with your website.

9. Notes

• One-time payments: The productId and quantity are read from the Checkout Session metadata.
• Subscriptions: Initial purchase reads from session metadata. Renewals read from subscription metadata (set via subscription_data.metadata). Without this, renewal keys won't be generated.
• 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}}, {{PaymentProcessorCustomerName}}).
• Trials: validation without a key returns a trial if the device was never activated for that product and the product has TrialDays > 0.

Troubleshooting

Status shows "Partial" (missing webhook signing secret)

This means your secret key is configured but the webhook signing secret is missing. To fix this:

1. Go to Stripe Dashboard > Webhooks (use test or live mode as appropriate).
2. If you don't have a webhook endpoint yet, click Add endpoint:
   • Set the URL to: https://www.exisone.com/api/stripe/webhook
   • Select events: checkout.session.completed, payment_intent.succeeded, invoice.paid
   • Click Add endpoint
3. Click on your endpoint, then find Signing secret and click Reveal.
4. Copy the value (starts with whsec_...).
5. In ExisOne, go to Stripe Apps and Events, click Edit on your app.
6. Paste the signing secret into the Webhook Signing Secret field and click Save.

The status should change from "Partial" to "Ready".

Status shows "Not configured" (missing secret key)

This means the secret key is missing or cannot be decrypted. To fix this:

1. Go to Stripe Dashboard > API keys.
2. Copy your Secret key (sk_test_... or sk_live_...).
3. In ExisOne, go to Stripe Apps and Events, click Edit on your app.
4. Paste the secret key into the Secret Key field and click Save.

If you still see "Not configured" after saving, you may need to generate a tenant encryption key first. Go to Settings > Tenant Keys and ensure you have an active key.

Subscription renewals not generating license keys

If initial subscription purchases generate keys but renewals don't, the issue is likely missing subscription metadata:

• Ensure you're using subscription_data.metadata (not just metadata) when creating the checkout session.
• The productId must be on the subscription object itself, not just the checkout session.
• Verify the subscription has metadata by checking in Stripe Dashboard: Customers > [Customer] > Subscriptions > [Subscription] > Metadata.
• For existing subscriptions missing metadata, you can add it via Stripe Dashboard or API:

  stripe subscriptions update sub_xxx --metadata[productId]=42

• Make sure your webhook endpoint is listening for invoice.paid events.

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.

10. Setup Checklist

Before going live, verify all items are complete:

11. Go Live

1. In Stripe Dashboard, switch to live mode and create a new webhook endpoint pointing to https://www.exisone.com/api/stripe/webhook.
2. In ExisOne, add a new Stripe app with your live keys (pk_live_..., sk_live_...) and the live webhook signing secret. Check Is Live and Active.
3. Update your website to use your live Stripe secret key.
4. Make a real purchase (you can refund it) to verify the complete flow works in production.