Connect to Stripe

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

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

Set up your B2B and B2C customers
Issue 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 10Duke 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 Scale end, which are handled by 10Duke.

Supported webhook events and actions

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

The Stripe events sent to 10Duke Scale 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 Scale:

A customer is created, and a default license container to hold the customer’s licenses.
For a B2C customer, this also creates a license consumer of type person.

See more information on customers, license containers, and license consumers in 10Duke Scale.

Data required in the customer.created event:

id: The customer ID.
email: The customer’s email address.

This is set as the email address of the customer in 10Duke Scale, and of the B2C customer’s license consumer. The email address must be unique across customers and license consumers in 10Duke Scale.
name: The customer name.

This is set as the (formal) name for the customer and the associated license consumer, and also as the display name for the customer.

For a B2C customer, this can be overridden by providing the name details in metadata (see below).

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

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

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

Key name: tendukeLicenseeType

Possible values: PERSON (default), ORGANIZATION

If the customer type is not provided, 10Duke Scale applies the default B2C customer type.
Optionally, a B2C customer’s first and last name, and a display name.

The first and last name combined are used to set the (formal) name for the customer and the associated license consumer.

Key names: tendukeFirstName, tendukeLastName, tendukeDisplayName
The customer ID in 10Duke Scale

Key name: tendukeLicenseeId

This can be used to identify a customer that already exists in 10Duke Scale. This may be needed if you have created customers in 10Duke Scale before creating them in Stripe (for example, using the 10Duke Scale UI console or with a data migration).

If this is provided, the customer data in the event is only used for mapping the 10Duke Scale customer to the Stripe customer in the Integration Service component. No new customer is created in 10Duke Scale.

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 issuing of new licenses to the B2C or B2B customer in their default license container.

The event specifies one or more Stripe products, which map to 10Duke Scale product configurations that are used for issuing the licenses.

If needed, license keys can be generated for the issued licenses. This also automatically creates corresponding license consumers of type license key.

See more information on issuing licenses in 10Duke Scale.

Data required in the customer.subscription.created event:

id: The subscription ID.
current_period_start: The subscription validity start date and time (interpreted as UTC time in 10Duke Scale).

If a start date and time is not provided, the licenses are valid immediately.
current_period_end: The subscription validity end date and time (interpreted as UTC time in 10Duke Scale).

The licenses become invalid after this, but are not deleted. If an end date and time 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 issued.

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

Optionally, include the following custom 10Duke Scale data as a key-value pair in the metadata parameter:

Specify whether license keys are generated for the issued licenses.

Key name: tendukeGenerateLicenseKey

Possible values:
- true: Each license will have a license key, and can only be consumed using that license key.
- false: No license keys are generated. For example, when issuing licenses to a B2C customer, this means the customer’s license consumer of type person will be able to consume the licenses.
  
  Note: A license key cannot be generated afterwards for a license.
If not provided, true is applied.

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

customer.subscription.updated

When a registered customer’s subscription is updated in Stripe, the actions triggered by the customer.subscription.updated event depend on what type of changes were made to the subscription.

If only the subscription validity is changed (for example, the subscription is renewed by extending the validity end date), this triggers an update of the validity of the associated licenses in 10Duke Scale.

However, if any other changes are made to the subscription (for example, there’s a change in what products the subscription includes, or the quantity of a product changes), this triggers the following actions in 10Duke Scale:

New licenses are issued to the B2C or B2B customer 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 issuing the licenses.

This may result in a different set of licenses than at the time of the subscription creation, if the Stripe products specified in the event are different.
The old licenses are deleted.

If the old licenses had license keys, those are also deleted with the licenses. New license keys are generated for the new licenses, and they can only be consumed using the new license keys. The old license keys are no longer valid.

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 Scale.

See more information on deleting licenses in 10Duke Scale.

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 requires predefined products for issuing licenses. Feature licenses are not supported.
The integration only supports license management based on Stripe subscription events. One-time purchases are not supported.
The integration only supports issuing seat-based licenses.
The integration doesn’t support issuing licenses restricted to certain client application versions.
With B2B customers’ subscriptions that grant licenses without a license key, take into account that if you move granted licenses to other license containers, updating the Stripe subscription may affect how license consumers of type person and device can access those licenses in 10Duke Scale. This is because some subscription changes cause the old licenses to be deleted, and the new, updated licenses are created in the customer’s default license container. See more information on managing license consumer 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 Scale in the correct order. This helps to make sure that 10Duke Scale is able to create the customer and issue 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 issued correctly to the customer.

In addition, make sure that your implementation requests the customer to enter sufficient details at login so that the existing customer in 10Duke Scale can be correctly identified. For example, granting licenses to the correct existing B2B customer should rely on acquiring the customer ID, instead of relying on a company name manually entered by the customer.

Setup in Stripe

Complete the steps below for the integration setup in Stripe.

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 Scale.

Before you start:

You need the base URL of the 10Duke Scale Integration Service where the webhook will send the events. Contact 10Duke to get the URL.

To register a webhook in Stripe:

In the Developers dashboard, go to webhooks and add a new endpoint.
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 API base URL for 10Duke Scale.
Select to listen to events on your Stripe account.
Select the Stripe API version to use.
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 Scale:

The webhook signing secret.
- 10Duke Scale 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 Scale 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 Scale cannot find a matching customer based on the Stripe customer 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:

In the Developers dashboard, go to webhooks.
Open the webhook you created, and copy and store the signing secret.

To create an API key in Stripe:

In the Developers dashboard, go to API keys.
Create a new restricted API key for the 10Duke Scale integration.
- Set the API key to only allow read access to customer data in Stripe.
- 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 10Duke. 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 10Duke with the new keys in time to keep the integration working.

Step 3: Map products in Stripe and 10Duke Scale

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

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

To map a product:

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.
In the 10Duke Scale UI console, change the technical name of the corresponding product configuration to the Stripe product ID.

See how to edit product configurations in the UI console.

Step 4: Set up API authorization keys for Integration Service

As the last step, set up API keys for authorizing the Integration Service component to connect to the 10Duke Scale APIs: store the public API key in 10Duke Scale and provide the corresponding private key to 10Duke.

We recommend that you generate a new API key pair for the integration.

When storing the public API key in the UI console, note the following:

In Default key use, select Verify Scale JWT.
In Key ID, we recommend that you use a value that makes it easy to later identify where this API key is used. You could, for example, include a prefix such as “stripe-integration” in front of the ID.

Provide the private key from the key pair to 10Duke. Make sure to use a secure method to communicate it, such as GNU Privacy Guard (GPG) encryption.

After all the setup steps have been completed, 10Duke can enable the integration in 10Duke Scale.