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 10Duke Enterprise 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.

  • For both customer types, an email is sent to the created user, who needs to activate their user account by setting a password.

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

    This can be used to identify a user or organization that already exists in 10Duke Enterprise. This may be needed if you have created users or organizations in 10Duke Enterprise before creating the customers in Stripe (for example, using SysAdmin or with a data migration).

    If this is provided, the account data in the event is only used for mapping the user or organization to the Stripe account in the Integration Service component. No new user or organization is created in 10Duke Enterprise.

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.

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 licenses become invalid after this, but are 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:

  • The existing licenses are updated.

  • If the name of the product package included in the received customer.subscription.updated event has changed, 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.

Note: When the licenses are granted through the Graph API 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, and the old licenses are deleted. If there were seat reservations for the old licenses, those are also deleted.

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 an update to the validity of the corresponding licenses in 10Duke Enterprise. The valid until date is set to the current instant (now) making the licenses invalid with immediate effect.

Note: When a registered customer’s subscription ends in Stripe, and the licenses are granted through the Graph API the customer.subscription.deleted event triggers the deletion of the corresponding licenses in 10Duke Enterprise.

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.

  • With B2B customers’ subscriptions, take into account that if you move granted licenses to other entitlements, updating a subscription’s licenses may affect how the organization’s users and devices can access those licenses in 10Duke Enterprise. See more information on authorizing access to 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.

    In addition, make sure that your implementation requests the customer to enter sufficient details at login so that the existing user or organization in 10Duke Enterprise can be correctly identified. For example, granting licenses to the correct existing organization should rely on acquiring the organization ID, instead of relying on an organization name manually entered by 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. Only select events supported by the integration.

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

Step 2: Provide 10Duke with Stripe 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.

See detailed information on Stripe 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