# Stripe Integration (legacy)

Follow these steps to configure licensing for products that you sell using Stripe

{% stepper %}
{% step %}

### Create product in LicenseSpring platform

1. Log in to `https://saas.licensespring.com/login`
2. Go to **Configure Products → Add new Product** and create a new product

![](https://content.gitbook.com/content/gLzurdfXUuKr9IziZWLz/blobs/NDgdfZOexeH02jbKscTb/wOdApkWWJHMZzDeH6T%20He_image.png)

![](https://content.gitbook.com/content/gLzurdfXUuKr9IziZWLz/blobs/CXQK4KZwFVG3VYwKMx48/HkY6vzMSubZjO2ElFXke1_image.png)
{% endstep %}

{% step %}

### Create product in Stripe dashboard

1. Log in to your Stripe dashboard and go to **Products → Add product**
2. As a part of a product creation process in Stripe, you need to create a **price** for this product. If you select **Recurring** billing type, LicenseSpring integration will create **subscription** license type and use **billing period** from price settings as a **valid duration** in LicenseSpring. If you select **One time** billing type, LicenseSpring will use products default license type value or custom price attribute to set license type in LicenseSpring.
3. Click on **Save product** button in the top right corner of the screen to finish creating a product in Stripe.

![](https://content.gitbook.com/content/gLzurdfXUuKr9IziZWLz/blobs/r1xIDErLa0X9Yn1sAV42/OrEbUV6z5MXsOH70Rlt_F_image.png)

![](https://content.gitbook.com/content/gLzurdfXUuKr9IziZWLz/blobs/cMPl3ZxH1jvEKHxIXmV4/XOsGmDDePmllWIJQyrhQ5_image.png)
{% endstep %}

{% step %}

### Add custom attributes to the product PRICE metadata

To properly create licenses LicenseSpring will use product **price** metadata custom attributes. To add attributes to the **price** metadata, go to *Product* page and select the price which you want to customize.

![](https://content.gitbook.com/content/gLzurdfXUuKr9IziZWLz/blobs/naNajKEhD2ObjrhT0dfi/M2kf0%2071akWsqXHWDkllm_image.png)

![](https://content.gitbook.com/content/gLzurdfXUuKr9IziZWLz/blobs/cfiCAIFrQjNYvF6uxjCr/rdY_ZzFPg96mYlprSz0IA_image.png)

#### License Policy

For every product in the LicenseSpring platform you can define one or many license policies which act as a template when creating licenses. License policy can be added to the Stripe products as a price metadata key `license_policy` with value of some license policy code. When order is being created via Stripe, our integration will take all the fields, product features and custom fields from included license policy and create the license based on those.

If `license_policy` attribute is not included Stripe integration will use default license policy for the product to create a license.

In case of subscription `license_type` will be always set as `subscription` and `valid_duration` period will use billing period from product price settings.

#### Custom Attributes

Custom attributes are used to overwrite fields from license policy and to handle some specific use cases which license policies don't cover. Note that `short_code` attribute is always required.

* `short_code` - required. Add the product short code you configured LicenseSpring product with.
* `max_activations` - optional, INT. If this field is not included, the default from the product configuration in LicenseSpring will be used.
* `floating_cloud` - optional, INT. If this value is set licenses from this product will be created as floating cloud. This value also sets the total number of machines / users that can concurrently use a floating cloud license (Max simultaneous license users value in LicenseSpring configuration). Needs to be less than or equal to `max_activations` attribute value.
* `license_type` - optional, STRING. If this field is not included, the default license type from the product configuration in LicenseSpring is used (`perpetual`, `time-limited`, `subscription`, `consumption`). For recurring product prices, license type can be either `subscription` or `consumption`. In the case of consumption licenses, the total consumptions are reset at the start of each billing interval.
* `valid_duration` - optional, STRING. If this field is not included, the default `valid_duration` from the product configuration in LicenseSpring is used. The format for this is `N[d/w/m/y]` where N is number and option between d,w,m,y is possible (day, week, month, year - ex. "1y"). Not applicable for subscription licenses — subscription licenses will use billing period from product price settings.
* `enable_maintenance_duration` - optional, BOOL. Turns on maintenance capability. If not defined, default from LicenseSpring is used.
* `maintenance_duration` - optional, STRING behaves same as the `valid_duration` field.
* `max_license_users` - optional, INT, limits the number of users which can be added to the licenses — example: one license with multiple license users. Can be added only for products with **user authorization method**.
* `is_license_manager` - optional, BOOL, sets customer as a license manager. Useful on license-key based products where customer is not set as a license manager per default. If you are creating user based licenses, but do not want the customer to be assigned as a license manager, set this as `false`.
* `assign_customer_as_user` - optional, BOOL, customer will be automatically assigned to the license as a license user. Can be added only for products with **user authorization method**.
* `unpaid_active_license_period` - optional, STRING, used to define a period during which the licenses remain active even if they haven't been paid for yet. The format for this is `N[d/w/m/y]` where `N` is a number and `d`, `w`, `m`, or `y` represents days, weeks, months or years respectively (e.g., "3d" for 3 days).
* `added_days` - optional, INT, specifies the number of days to extend the current subscription interval. Applicable only to **subscription** licenses.
* `ignore_product_in_licensespring` - optional, BOOL. When set to `true`, incoming webhooks for the specified product will be ignored, and a `200` status code will be returned to Stripe as a response.

#### Custom Fields

You can customize LicenseSpring license custom fields directly through Stripe using metadata attributes.

If a product has an existing custom field, you can override its default value during the license creation process. This is done by adding a custom attribute to the Stripe Product Price Metadata using the following format:

`custom_field_{CUSTOM_FIELD_NAME}`

**Example**

If you have a custom field named Serial (default value: `111`) and you want to assign a unique value for a specific license:

1. Navigate to the specific Product Price metadata in Stripe.
2. Add a new metadata key named `custom_field_Serial`.
3. Enter your desired override value in the value field.

> Note: To override multiple custom fields, you must add a separate metadata entry for each field using the `custom_field_` prefix.

#### **Single License**

In your store, user can select different quantities for a product. Default behaviour is that multiple quantities will result in multiple licenses (both user and license-key based). If instead, when user selects >1 quantity you want to make a SINGLE license that can be activated multiple times (for license-key based) or a SINGLE license that supports multiple users (for user-based licenses), you need to add this custom attribute: `is_single_license` - optional, BOOL

![](https://content.gitbook.com/content/gLzurdfXUuKr9IziZWLz/blobs/yfQ9RcPRFuVXDlUKotQO/Price_metadata_LmcK6ww.png)

#### **Max Simultaneous License Users from Quantity on a Single License**

In case of single floating-cloud license, quantity can be used to determine max simultaneous license users instead of `max_activations` for license-key based or number of users for user based products. To enable this, please use this following combination of custom attributes on the product price:

* `floating_users_from_quantity`: true
* `floating_cloud`: 1
* `max_activations` - optional, INT. If this field is not included, the default from the product configuration in LicenseSpring will be used.

#### **Product Bundles**

Product bundle is a unique type of product in LicenseSpring that requires specific configuration. This section outlines all the currently available Product Attributes for product bundles and instructions on how to use them.

{% hint style="warning" %}
Only one product bundle can be processed per order. Multiple quantities of the same product bundle are supported; however, including two or more different product bundles in the same order on Stripe is not supported.
{% endhint %}

How to set up product bundles in LicenseSpring?

{% stepper %}
{% step %}
Go to the **Products** section in LicenseSpring platform
{% endstep %}

{% step %}
Click the **Add new bundle** button

![](https://content.gitbook.com/content/gLzurdfXUuKr9IziZWLz/blobs/MqSq06oKrmslMe28MahB/wTUy6_ZK7%20I06p4PDQYRS_image.png)
{% endstep %}

{% step %}
Insert the desired **Bundle name** and **Bundle code**, choose which **Authorization method to use**, and select all the products that you want inside the bundle

![](https://content.gitbook.com/content/gLzurdfXUuKr9IziZWLz/blobs/HHCvuAcatuQF0SO78BUL/XJbs1DPEaNQpUQupP0Bti_image.png)
{% endstep %}

{% step %}
After the bundle is created, it should look something like the following picture. Take the **Bundle code** value and use it as the `short_code` in the Stripe configuration. (Look at the list below to see all the available Product attributes for bundle products)

![](https://content.gitbook.com/content/gLzurdfXUuKr9IziZWLz/blobs/D6AafW4Z3OPXvTBlBkzN/H3BatFY8_bd8mVVZk6D49_image.png)
{% endstep %}
{% endstepper %}

{% hint style="info" %}
All other setup steps are the same as they are for basic Products. The only difference is in the supported Product attributes.
{% endhint %}

{% hint style="info" %}
If a product bundle contains, for example, three products, then four licenses will be created in LicenseSpring. One license will be for the bundle itself, which can be used for all products within the bundle. The remaining three licenses will be created for each individual product in the bundle. The value of these individual licenses is determined by the default license policy of each product.
{% endhint %}

{% hint style="warning" %}
Each license will include the features defined in the default license policy of the product for which the license was created.
{% endhint %}

Product Attributes for bundles:

* `is_product_bundle` - required, BOOLEAN, has to be set to `true`
* `short_code` - required, with the code you configured LicenseSpring Product Bundle with
* `max_activations` - optional, INT. If this field is not included, the value from the default license policy on the product in LicenseSpring will be used.
* `floating_cloud` - optional, INT. If this value is set licenses from this product bundle will be created as floating cloud. This value also sets the total number of machines / users that can concurrently use a floating cloud license (Max simultaneous license users value in LicenseSpring configuration). Needs to be less than or equal to `max_activations`.
* `license_type` - optional, STRING. If this field is not included, the default license type of each product inside the bundle configuration in LicenseSpring is used (`perpetual`, `time-limited`, `subscription`, `consumption`). For subscription products license type is always `subscription`.
* `valid_duration` - optional, STRING. If this field is not included, the default `valid_duration` of each product inside the bundle configuration in LicenseSpring is used. The format for this is `N[d/w/m/y]`. Applicable for `time-limited` licenses only.
* `maintenance_duration` - optional, STRING behaves same as the `valid_duration` field.
* `enable_maintenance_duration` - optional, turns on maintenance capability. If not defined, default from LicenseSpring is used.
* `max_license_users` - optional, INT, limits the number of users which can be added to the licenses. Can be added only for products with **user authorization method**.
* `is_license_manager` - optional, sets customer as a license manager. Useful on license-key or user-based products where the customer is not set as a license manager by default.
* `assign_customer_as_user` - optional, BOOL, customer will be automatically assigned to the license as a license user. Can be added only for products with **user authorization method**.
* `unpaid_active_license_period` - optional, STRING, used to define a period during which the licenses remain active even if they haven't been paid for yet. Format: `N[d/w/m/y]`.
* `added_days` - optional, INT, specifies the number of days to extend the current subscription interval. Applicable only to **subscription** licenses.
  {% endstep %}

{% step %}

### Add webhook endpoint

LicenseSpring will listen to some events sent from Stripe to create orders and licenses in the platform. To enable this you need to create a Stripe webhook which will send those events to LicenseSpring server.

To create a webhook go to Developers -> Webhooks and click on **Add endpoint**.

![](https://content.gitbook.com/content/gLzurdfXUuKr9IziZWLz/blobs/hZOQ8BMMme24nGOzMO1Y/sQVkgLufQxqTKYclPyY7u_image.png)

![](https://content.gitbook.com/content/gLzurdfXUuKr9IziZWLz/blobs/wzK651dc2xuXhpFQ39eB/8nfk70YfIavbjR9LIWxrw_image.png)

**Endpoint URL**

`https://integrations.licensespring.com/api/stripe?uuid={uuid}`

Example:

`https://integrations.licensespring.com/api/stripe?uuid=12345678-7121-6bcb-a355-bbd6b6df0b84`

To retrieve the uuid (api-key) go to **LicenseSpring → Settings → Keys**

![](https://content.gitbook.com/content/gLzurdfXUuKr9IziZWLz/blobs/S67qelzc2lfBTWz7itx6/72DERElhKHmfuwrai_7MD_screenshot%202023%2011%2008%20at%20132209.png)

Select these Events to listen to:

* **customer.subscription.created** (order and licenses will be created in LicenseSpring)
* **customer.subscription.deleted** (licenses from the subscription will be deactivated)
* **customer.subscription.updated** (licenses from the subscription will be updated with new values (quantity, policy and trial changes))
* **invoice.payment\_succeeded** (on successful payment licenses will be prolonged with new Expiration date written in license `validity_period` field)
* **charge.refunded** (licenses associated with the refunded charge will be disabled)
  {% endstep %}

{% step %}

### Add restricted API key from Stripe to LicenseSpring platform account

LicenseSpring needs limited access to your Stripe account to update **Subscription metadata** after order is created and to fetch and copy **Customer** from Stripe to LicenseSpring.

To enable this create **restricted API key** in your Stripe dashboard. Go to *Developer* -> *API keys* and click on the **Create restricted key** button.

![](https://content.gitbook.com/content/gLzurdfXUuKr9IziZWLz/blobs/NSV1Aif5v8l0Zhkw7X3Y/IXa9n6VOdUSYEBMw0SN2q_image.png)

The title of this key can be anything you like, but we recommend something relating to LicenseSpring. Set all **permissions** to *Read* except **Subscriptions**, **Invoices** and **Stripe CLI permissions** which need to be set to *Write*.

Save this key and add it to the LicenseSpring account by going to **Settings -> Integrations**. Press **Activate** for Stripe.

![](https://content.gitbook.com/content/gLzurdfXUuKr9IziZWLz/blobs/pBmH0erFqpJmio37inKD/XVrRNOKQCZ9lXliyQuKmS_screenshot%202023%2011%2008%20at%20132621.png)

Copy the key to the **Stripe secret key** text field.

Select the **Management API key** and **License API key** (uuid) that you want to use.

The License API key (uuid) needs to be the same as the one you used for the webhook endpoint.

![](https://content.gitbook.com/content/gLzurdfXUuKr9IziZWLz/blobs/gj9p922UNa9h4sJUfOCc/Cwn6ffpxrloy3v2GtJjdg_screenshot%202023%2011%2008%20at%20132715.png)
{% endstep %}

{% step %}

### Creating payment

#### One-Time Products

With Invoices:

![](https://content.gitbook.com/content/gLzurdfXUuKr9IziZWLz/blobs/dlU2BoKUWswyvXPattkI/beOA0z4mlHLBdS4YWqxX6_image.png)

To generate an invoice, first select your customer and item (a one-time product). Then, set the payment collection method to 'Autocharge Customer.' Once you've reviewed everything, you can proceed to charge the customer.

![](https://content.gitbook.com/content/gLzurdfXUuKr9IziZWLz/blobs/O9JCgxXce5xshg4HegyW/Nx7XYwO4vcZSU0LQ9biNH_image.png)

With Payment Link:

In the right upper corner click on the '+' sign and then on **Payment Link**

![](https://content.gitbook.com/content/gLzurdfXUuKr9IziZWLz/blobs/UkrryfJuM4oYVR53DM1U/Ie4qGwOGK_cd7Qcouz3jQ_screenshot%202024%2001%2017%20at%20142701.png)

Once the page for payment link creation opens, firstly select the **one-time** product price for which you want to create the link

![](https://content.gitbook.com/content/gLzurdfXUuKr9IziZWLz/blobs/m2tvClfaaU8S1jxBLX02/itb1WgkTz9LW7LGquhifW_screenshot%202024%2001%2017%20at%20142749.png)

After you've selected the product click on **After payment!** Make sure to select the **'Create an invoice PDF'** checkbox.

![](https://content.gitbook.com/content/gLzurdfXUuKr9IziZWLz/blobs/CQjVA1o1f8A2Kk69fgcM/jPe%20Hk5mVKOQaWCFHy6id_screenshot%202024%2001%2017%20at%20142830.png)

#### Subscription Licenses

When dealing with subscription products, you should utilize a payment link. To do so, first choose 'Payment Link,' then select the product, and finally create the link.

![](https://content.gitbook.com/content/gLzurdfXUuKr9IziZWLz/blobs/q5fVzoaXSiUNXNcDhadQ/MaTTd0I3SZ_8fx0%20_k2HZ_image.png)

![](https://content.gitbook.com/content/gLzurdfXUuKr9IziZWLz/blobs/kE6xsjGBaO6fSnttqJKh/86obH9xZqYk%20DvrOG9dAR_image.png)

After creating the link, access it to complete the payment process.
{% endstep %}

{% step %}

### Generate License Keys

There are currently two ways how you can create licenses keys which will be then used for licensing your products.

#### Attaching to Metadata of the New Subscription (preferred)

If Stripe API will be used to create subscriptions, attach the generated license keys to the subscription metadata. LicenseSpring integration will use those keys to create licenses in the LicenseSpring platform. More about Stripe API subscriptions methods here: <https://stripe.com/docs/api/subscriptions/create>

To generate license keys, use [Generate License Key](https://docs.licensespring.com/management-api/order/generate-license-key) from the Management API.

Instead of *{short\_code\_here}* placeholders add a product short code for which you want to use those license keys.

#### LicenseSpring Updates Subscription Metadata After Order Creation

If you are creating Stripe subscriptions and invoices (in case of one time order, ex. perpetual licenses) manually without the ability to create the subscription or invoice with prefilled metadata then LicenseSpring will detect that metadata doesn't contain keys for the product in question and it will generate them automatically. Upon order create is finished, subscriptions / invoice metadata on Stripe will be updated with those license keys.

To access them you can subscribe your application to Stripe `customer.subscription_updated` event in case of a subscription or `invoice.updated` event in case of a one time order.

Alternatively you can fetch the subscription or invoice afterwards using Stripe API.

License keys will be visible on Stripe dashboard on metadata section of the created subscription / invoice.

![](https://content.gitbook.com/content/gLzurdfXUuKr9IziZWLz/blobs/Gmm6TwxmViZLQ2mmSsyR/subscription_metadata_x3cKMfv.png)
{% endstep %}
{% endstepper %}