Connect to Stripe

This article provides instructions on the steps required from you (the vendor), when you’re integrating 10Duke Enterprise with Stripe using webhooks.

10Duke Enterprise supports the use of webhooks to trigger actions in 10Duke Enterprise based on Stripe events to:

  • Set up your B2B and B2C customers

  • Grant and update licenses for subscriptions

  • Delete licenses when a subscription ends

The integration requires an optional 10Duke Integration Service component that is purchased separately.

Contact the 10Duke Integration Support team to get started with the integration, and get support with the setup steps if needed.

The integration also requires setup and configurations at the 10Duke Enterprise end, which are handled by the 10Duke Integration Support team. This includes enabling the Integration Service component for your deployment, and defining the connection between the component and Stripe as an OAuth client application, which you will see in the 10Duke SysAdmin tool.

Supported webhook events and actions

You can use webhooks in Stripe for the following events to trigger actions in 10Duke Enterprise.

The Stripe events sent to 10Duke Enterprise must include certain data required by the integration. There’s also some optional data that can be included.

customer.created

When an e-commerce account is created for a customer in Stripe, the customer.created event triggers the following actions in 10Duke Enterprise:

  • For a B2C customer, this creates a user account.

  • For a B2B customer, this creates:

    • A new organization in 10Duke Enterprise.

    • A user account for the organization’s first administrator, with access to the 10Duke OrgAdmin tool (if you’re providing it for your B2B customers).

    • A default entitlement to hold the organization’s licenses.

    • An “employees” user group where the first administrator user is added, and which is granted access to the default entitlement.

See more information on user accounts and organizations.

Data required in the customer.created event:

  • id: The customer ID.

  • email: The user’s email address.

    This is set as the email address in the 10Duke Enterprise user account. The email address must be unique across users in 10Duke Enterprise.

  • name: The customer name.

    • For a B2B customer, this is set as the organization’s name.

    • If the event doesn’t include the user’s name details in metadata (see below), this is also set as the user’s display name.

See detailed information on the Customer object in Stripe’s documentation.

In addition, include the following custom 10Duke Enterprise data as key-value pairs in the metadata parameter:

  • The customer type (a B2C or a B2B customer).

    Key name: tendukeLicenseeType

    Possible values: PERSONAL (default), ORGANIZATION

    If the customer type is not provided, 10Duke Enterprise applies the default B2C customer type.

  • The user’s first name and last name, and optionally a display name.

    Key names: tendukeFirstName, tendukeLastName, tendukeDisplayName

  • User or organization ID

    Key name: tendukeLicenseeId

    Only required if you have API integrations in place that create users and organizations in 10Duke Enterprise before customers are created in Stripe.

See detailed information on the metadata parameter in Stripe’s documentation.

customer.subscription.created

When a subscription is created for a registered customer in Stripe, the customer.subscription.created event triggers the following actions in 10Duke Enterprise:

  • New licenses are granted to the customer (a B2C user or a B2B organization).

    The event specifies one or more Stripe products, which map to 10Duke Enterprise product packages that are used for granting the licenses.

  • For a B2C customer, granting licenses also automatically creates an entitlement if they don’t have one yet.

  • For a B2B customer, the licenses are always created in the organization’s default entitlement.

See more information on granting licenses.

Data required in the customer.subscription.created event:

  • id: The subscription ID.

  • current_period_start: The subscription validity start date.

    If a start date is not provided, the licenses are valid immediately.

  • current_period_end: The subscription validity end date.

    • The license becomes invalid after this date, but is not deleted.

    • If an end date is not provided, the licenses are valid indefinitely.

  • customer: The customer ID.

  • product (under items): The product ID for each product in the event.

  • quantity (under items): The number of products purchased (the number per product in the event).

  • status: The subscription status.

    The integration only accepts the value active or trialing. The value provided doesn’t affect how licenses are granted.

See detailed information on the Subscription object in Stripe’s documentation.

customer.subscription.updated

When a registered customer’s subscription is renewed in Stripe, the customer.subscription.updated event triggers the following actions in 10Duke Enterprise:

  • New licenses are granted to the customer (a B2C user or a B2B organization) that are valid until the end of the new subscription period.

    Like with customer.subscription.created, this event specifies the products to be used for granting the licenses.

    This may result in a different set of licenses than at the time of the subscription creation. This may happen if the Stripe products specified in the event are different, or if the licensed items included in the 10Duke Enterprise product packages have changed.

  • The old licenses are deleted.

See more information on updating licenses.

The customer.subscription.updated event requires the same data as the customer.subscription.created event.

Note: To avoid a break in the license validity when replacing a customer’s existing licenses, the date from current_period_start is only used for the new licenses if it’s in the past. If the date is in the future or no date is provided, the license validity start is set to the current date.

customer.subscription.deleted

When a registered customer’s subscription ends in Stripe, the customer.subscription.deleted event triggers the deletion of the corresponding licenses in 10Duke Enterprise.

See more information on deleting user licenses or organization licenses.

Data required in the customer.subscription.deleted event:

  • id: The subscription ID.

  • customer: The customer ID.

See detailed information on the Subscription object in Stripe’s documentation.

Limitations

  • The integration only supports license management based on Stripe subscription events. One-time purchases are not supported.

  • The integration only supports granting seat-based licenses.

Recommendations for purchase flow

  • We recommend that your Stripe purchase flow first creates the customer and then handles the purchase, so that the events are sent to 10Duke Enterprise in the correct order. This helps to make sure that 10Duke Enterprise is able to create the customer and grant licenses correctly.

  • To handle returning customers, we recommend that your Stripe implementation makes sure that a customer uses their existing Stripe customer account if they have one. Otherwise there’s a risk that licenses are not granted correctly to the customer.

Setup in Stripe

Complete the steps below for the integration setup in Stripe.

After all the setup steps have been completed, the 10Duke Integration Support team can enable the integration in 10Duke Enterprise.

Step 1: Register a webhook in Stripe

In Stripe, register a new webhook for the integration. This includes defining the Stripe events that the webhook will send to 10Duke Enterprise.

Before you start:

  • You need the base URL of the 10Duke Enterprise integration service where the webhook will send the events. Contact the 10Duke Integration Support team to get the URL.

To register a webhook in Stripe:

  1. In the Developers dashboard, go to webhooks and add a new endpoint.

  2. Enter the URL where the webhook sends events.

    URL format: <integration_service_base_url>/stripe/actions/webhook

    Note: This base URL is not the same as your 10Duke Enterprise deployment’s base URL.

  3. Select to listen to events on your Stripe account.

  4. Select the Stripe API version to use.

  5. Select the events that this webhook sends. See information on the supported events.

See detailed information on Stripe webhooks in Stripe’s documentation.

Step 2: Provide 10Duke with webhook signing secret and API key

You need to provide the following security keys that are needed in 10Duke Enterprise:

  • The webhook signing secret.

    • 10Duke Enterprise will use this to verify that the event was sent by the correct webhook in Stripe.

    • Stripe automatically created a unique signing secret for the webhook that you registered in the previous step.

  • Your Stripe system’s API key.

    • 10Duke Enterprise will use this to make authorized API calls to Stripe.

    • The API key is needed for cases where Stripe sends the customer.subscription.created event before the customer.created event for a new customer.

    • If 10Duke Enterprise cannot find a matching customer (a user account or an organization) based on the Stripe customer account ID provided in the customer.subscription.created event, it must be able to retrieve the customer’s details from Stripe and create the customer.

To find the webhook secret in Stripe:

  1. In the Developers dashboard, go to webhooks.

  2. Open the webhook you created, and copy and store the signing secret.

To create an API key in Stripe:

  1. In the Developers dashboard, go to API keys.

  2. Create a new restricted API key for the 10Duke Enterprise integration.

    • Set the API key to only allow read access to customer data in Stripe.

    • Make sure to copy and store the API key before saving—you won’t be able to access it later.

For more detailed steps on API keys in Stripe’s documentation.

Provide the webhook signing secret and the API key to the 10Duke Integration Support team. Make sure to use a secure method to communicate these, such as GNU Privacy Guard (GPG) encryption.

Note: If you’re rolling your Stripe webhook signing keys and API keys periodically, make sure you always provide the 10Duke Integration Support team with the new keys in time to keep the integration working.

Step 3: Map products in Stripe and 10Duke Enterprise

To enable the integration to manage licenses to your products correctly, map the products defined in your Stripe system to the product packages defined in 10Duke Enterprise.

The mapping is based on setting the unique product ID from Stripe as the product package’s name in 10Duke Enterprise. The product ID is set when a product is created in Stripe.

To map a product:

  1. On Stripe’s product list, open the product and copy the product ID from the top right corner.

    Note: Stripe products must have the “recurring” option selected for the integration to work.

    See detailed information on managing Stripe products in Stripe’s documentation.

  2. In 10Duke SysAdmin, change the name of the corresponding product package to the Stripe product ID.

    See how to edit product packages in SysAdmin.

On this page