SupportGithubFeedbackNalpeiron UniversityFree Trial

Stripe

The Stripe integration enables automatic license provisioning in Zentitle 2 when customers complete payments through Stripe. This eliminates manual license creation and provides a seamless customer experience.

How It Works

The integration follows a simple webhook-based flow:

  1. Customer Purchase: Customer completes payment through Stripe (payment links, checkout, etc.)

  2. Webhook Trigger: Stripe processes the payment and sends a webhook to Zentitle2

  3. License Creation: Zentitle2 automatically creates the appropriate license/entitlement based on the purchase

Prerequisites

Before setting up the integration, ensure you have:

  • Admin access to your Zentitle2 tenant

  • A Stripe account (test mode recommended for initial setup)

  • Products and licensing offerings already configured in Zentitle2

Setup Overview

The setup process involves five main steps:

  1. Configure products and offerings in Zentitle2

  2. Set up products and pricing in Stripe

  3. Configure webhook in Stripe

  4. Configure Stripe integration in Zentitle2

  5. Create payment links (optional)

Step 1: Configure Products and Offerings in Zentitle 2

Learn more here about setting up your products.

Create Products (Product Catalog > Products)

  1. Create or verify your products are properly configured

Create Subscription Plans (Product Catalog > Plans)

Configure paid subscription plans with these critical settings:

  • License Start: Set to "Entitlement Creation"

  • Billing Periods: Configure appropriate periods (monthly, yearly, etc.)

Create Offerings (Product Catalog > Offerings)

Create offerings with meaningful SKUs that you'll reference in Stripe:

Example SKUs:

  • my_product_monthly

  • premium_annual

  • basic_monthly

Important: Document these SKUs carefully - you'll need them for Stripe configuration.

Step 2: Set Up Products and Pricing in Stripe

Create Products

  1. Log into your Stripe Dashboard

  2. Navigate to Product catalogue

  3. Create a product for each Zentitle2 product you want to sell

  4. Add product descriptions, images, and other details as needed

Create Prices

For each product:

  1. Click on the product to add pricing

  2. Set the billing period to match your Zentitle2 plan

  3. Set the amount and currency

Critical: Add Metadata

For each price, add metadata that links it to your Zentitle2 offering:

Key: offering_sku
Value: [Your Zentitle 2 Offering SKU]

Example: If your Zentitle 2 offering SKU is premium_monthly, add metadata with key offering_sku and value premium_monthly.

Step 3: Configure Webhook in Stripe

Create Webhook Destination

  1. Go to Developers (Workbench) > Webhooks in your Stripe Dashboard

  2. Click "Add destination"

  3. Select "Add an endpoint" as destination type

Configure Events

Select these events to listen for:

  • invoice.paid

  • customer.subscription.deleted

Get Zentitle2 Webhook URL

  1. Log into Zentitle2 as an administrator

  2. Navigate to Admin → Integrations → Stripe

  3. Copy the webhook endpoint URL displayed there (following pattern: https://your-domain.integration.nalpeiron.io/stripe/webhook)

  4. Enter this URL in Stripe

Complete Setup

  1. Click "Create destination"

  2. Copy the "Signing secret" from the destination details - you'll need this for Zentitle2 configuration

Step 4: Configure Stripe Integration in Zentitle2

  1. Log in to Zentitle2 as an administrator

  2. Navigate to Admin → Integrations → Stripe

  1. Enter the following information:

  • Secret API Key: Get this from Stripe Dashboard → Developers → API Keys

  • Webhook Signing Secret: Paste the signing secret from Step 3

  1. Save the configuration

Step 5: Create Payment Links (Optional)

To create simple payment links for testing or direct sales:

  1. Go to Payment Links in the Stripe Dashboard

  2. Click "Create payment link"

  3. Select your configured product and price

  4. Configure additional settings as needed

  5. Save and copy the payment link URL

Testing the Integration

Test Purchase

  1. Use Test Mode: Ensure Stripe is in test mode (not live mode)

  2. Make Test Purchase: Use a payment link or your checkout flow

  3. Use Test Payment Details:

    • Card Number: 4242 4242 4242 4242

    • Expiry: Any future date (e.g., 12/28)

    • CVC: Any 3 digits (e.g., 123)

    • Email: Any test email address

  4. Complete Purchase

Verify Integration

Check Zentitle 2:

  1. Go to the Entitlements section

  2. Verify that a new entitlement group was created with order reference id = Stripe subscription Id

  3. Confirm it's linked to the correct offering

  4. Check that the entitlement status is active

Verify Entitlement Creation: The entitlement should now be available for customer activation.

Customer License Activation

Customers can activate their license using the Z2 activation code. The activation code is available in Stripe's subscription metadata under the activation_codes field.

For Developers

If you're building custom activation flows, you can subscribe to the Z2 entitlement.group.created webhook. The webhook payload includes the Stripe subscription ID in the OrderRefId property, allowing you to:

  1. Fetch the subscription from Stripe

  2. Retrieve activation codes from subscription metadata

  3. Send activation emails to customers

Managing Subscriptions

Subscription Renewals

  • Automatic: Stripe handles renewals automatically

  • License Extension: Zentitle2 automatically extends the license period when renewals are processed

  • No Action Required: The process is fully automated

Subscription Cancellations

  • Manual: Cancel through Stripe Dashboard → Customers → [Customer] → Subscriptions

  • Automatic Cleanup: Zentitle2 automatically disables associated licenses when cancellation events are received

Troubleshooting

No License Created After Payment

Check these common issues:

  1. Metadata Configuration: Verify the offering_sku metadata is set on the Price (not the Product) in Stripe

  2. SKU Matching: Ensure the SKU exactly matches your Zentitle2 offering SKU (case-sensitive)

  3. Webhook Events: Confirm the webhook is configured for invoice.paid events

  4. Signing Secret: Verify the webhook signing secret in Zentitle2 matches the one from Stripe

Webhook Errors

  1. URL Verification: Ensure the webhook URL is correct and accessible

  2. Signing Secret: Check for extra spaces or characters in the signing secret

  3. Logs: Review webhook attempt logs in Stripe Dashboard → Webhooks → [Your Webhook]

License Activation Issues

  1. Offering Configuration: Verify the Zentitle 2 offering is properly configured

  2. Customer Instructions: Ensure customers receive activation instructions

  3. Entitlement Status: Confirm the entitlement shows as active in Zentitle2

Important Notes

  • Test Thoroughly: Always test in Stripe test mode before going live

  • Subscription Only: Only subscription-based payments are supported (one-time payments are not processed)

  • Multiple Products: Multiple products can be purchased in a single transaction

  • Automatic Matching: Customer matching is handled automatically

  • Real-time Sync: Data synchronisation happens in real-time when payments are processed

Support

If you encounter issues during setup:

  1. Review the troubleshooting section above

  2. Verify all configuration steps were completed correctly

  3. Contact your Zentitle2 administrator for technical assistance

  4. For Stripe-specific issues, consult Stripe's documentation or support

Future Enhancements

In future versions, the integration setup process may be streamlined by providing only the Stripe Secret API Key in the Z2 UI. A "connect" button would automatically create the webhook in Stripe and store the settings, reducing manual configuration steps.

PreviousFastSpringNextSlack

Last updated

Was this helpful?