Configuring FastSpring Contextual Store Integration

This topic is a guide on how to configure to configure the integration between a FastSpring conceptual store and SOLO Server. This can be used as an alternative to SOLO Server's integrated shopping cart. Read our blog post on choosing an eCommerce system for more information.

This topic makes several assumptions:

1. You already have a SOLO Server license or an activated SOLO Server account (you can sign-up for free).
2. You already have a basic working knowledge of SOLO Server's administrative interface.
3. You already have the relevant Product(s) and Option(s) configured in SOLO Server.
4. You already have a FastSpring account.
5. You already have a basic working knowledge of the FastSpring Dashboard interface.
6. You already have the relevant Product(s) configured in FastSpring.

One important concept to understand is SOLO Server's FastSpring Integration Script. This is a script included with SOLO Server that is designed to receive automated notifications from FastSpring and respond accordingly.

Gather SOLO Server Information

Before you can begin, there is a little bit of information you need to gather from SOLO Server's authors administration interface. Sign-in to SOLO Server, and find the following information:

1. On the bottom of the screen, you will find your Author ID to the right of your company name. Take note of this.
2. Click the Configure / Products menu, and click "Show options..." next to the product you wish to configure in FastSpring. Take note of the Option ID that corresponds with the product you are configuring in FastSpring.
3. You will need the URL of the FastSpring Integration fulfillment script for each new license notification you configure in FastSpring. To obtain this URL, click the Store / FastSpring Options menu, where this URL is listed as the Fulfillment URL.
4. You will need the URL of the FastSpring Integration Web Hook script for each WebHook notification you configure in FastSpring. To obtain this URL, click the Store / FastSpring Options menu, where this URL is listed as the Web Hook URL.

Configuring Order Fulfillment

The first, and perhaps most important step to getting started is to configure FastSpring to ask SOLO Server to create license as part of an order's fulfillment. Here are the steps to do this:

1. Before you can begin, you must have the product configured in FastSpring, and you must have at least 1 product and product option configured in SOLO Server. Take note of the Product Option ID from SOLO Server (which you can find by clicking Configure / Products, clicking "Show Options..." for the product, and taking note of the Option ID).
2. In the FastSpring Dashboard, manage the product, and click "Add Fulfillment" under the Fulfillment section. Select "Generate a license", pick the "Remote Server Request" option, and click Next.
3. Enter the URL of the FastSpring Integration fulfillment script (to obtain this URL, click the Store / FastSpring Options menu, where this URL is listed as the Fulfillment URL) and change the encoding to ISO-8859-1. You can configure the output format with one of the following options and click Create when done. See the Customizing FastSpring Email / Web Order Notification Text section at the bottom of this topic for examples.
   1. Select Single-Line License (Quantity Based), which is the default. This requires the "FastSpring Multi-line License Response" setting under Store / FastSpring Options to be unchecked, which is the default.
   2. Select Multiple-Line License (Quantity Based), which will give you more control over how the list of License ID(s) and Password(s) is displayed when an order is completed. This also requires the "FastSpring Multi-line License Response" setting under Store / FastSpring Options to be checked.
4. Click the Create button.
5. Click on the Security tab.
   1. If this is the first notification you are configuring, take note of or copy the private key. Then go to SOLO Server, click the Store / FastSpring Options menu, click the Edit button, and enter or paste the private key from FastSpring's Security tab into the "API Private Key" field, and click Submit to save it.
   2. If this is not the first notification you are configuring, go to SOLO Server, click Store / FastSpring Options, copy the "API Private Key" value, and paste it into FastSpring's "private key" field.
6. Click the Parameters tab, and add the following fields:
   1. Add a parameter named swk_action, with a value of NewLicense.
   2. Add a parameter named swk_authorid, with the Author ID you see at the bottom of SOLO Server's authors administration interface.
   3. Add a parameter named swk_prodoptionid, with the Option ID from step 1.
7. Also in the Parameters tab, set the name as appropriate. Under most circumstances, you should set this to "Not Name Based". Setting this to "Person Name" will result in the customer name being passed in the notification, which SOLO Server will detect, and when present will populate both the first/last name and company name fields when adding a new customer record. This will allow partially registering the customer information and optionally not configuring the the order.created Web Hook as outlined below.
8. Click Save on the top-right. You should now see the license generator in the list in the Fulfillment Actions section. You can click Edit on that item to make changes or run tests. Note that when you run tests, the number of licenses displayed in the results may not match the quantity entered if licenses were previously created for that email address and reference number.

The license generator notifications sent from FastSpring only contain very limited information about the customer, which includes the email address. If a customer with that email address already exists in SOLO Server, it will add the new license to that record. If there isn't an existing customer record, SOLO Server creates a new customer from one of these requests, marks it as unregistered, and only saves the customer's email address for future reference. If you wish to have FastSpring also provide SOLO Server with basic contact details about the customer after an order is completed, follow the steps in the next section.

Configuring Web Hook Integration

After configuring the license generator (as instructed above) for order fulfillment, the next critical piece to configure is the Web Hook integration. Note that Web Hook integration only applies to FastSpring Contextual Stores. If you are using a FastSpring Classic Store, refer to the topic on how to configure integration with that.

1. To begin, sign-in to SOLO Server in one browser tab/window, and click the Store / FastSpring Options menu. Then select the URL value listed for Web Hook URL and copy it.
2. In another browser tab/window, sign-in to the FastSpring Dashboard interface, click the Integrations menu, and then click the Web Hooks sub-menu (illustrated below).
   
3. Next, click Add Webhook on the right of the sub-menu. Enter a title such as "SOLO Server", select "Live and Test Orders", and click Add.
4. Now you will see a white box with your new web hook. Click the "Add Webhook URL" button at the bottom.
5. Paste the URL that you copied from step #1 into the URL field.
6. Return to the SOLO Server browser tab/window (from step #1). If you see a Generate button for the HMAC SHA256 Secret field, click it. Then copy the value in the HMAC SHA256 Secret and paste it into the HMAC SHA256 Secret field in the FastSpring browser tab/window.
7. Next, check the following web hook events:
   • order.completed (if you are using the "Person Name" option for the name parameter for order fulfillment and do not want to collect extended customer information, this is optional).
   • return.created
   • subscription.deactivated
8. Click Add to add the web hook integration with SOLO Server.

Now that everything is configured, test ordering with each of your products and subscriptions to ensure everything is working correctly.

Customizing FastSpring Order Email / Web Notification Text

When an order is completed, FastSpring will send the customer an order confirmation email, and SOLO Server can optionally send new customers a welcome email. You can also automatically email the customer their purchased license information, and/or display their license information on the on the order complete web page. This information should include the License ID(s) and Password(s), which the customer will use to activate the software. To configure and customize the notifications:

1. In the FastSpring Dashboard interface, click Products in the menu, click on the Product/Subscription you want to configure.
2. Under the Fulfillment section, click Add Fulfillment.
3. Choose Send Email and click Next. View FastSpring's support page for more information on email / web notifications.
4. Once you click Create, additional tabs will be available.
5. To configure SOLO Server to send a customer welcome email to new customers, create a Customer Welcome Mailing, and then update the Cart Options and set the Customer Welcome Mailing option to the mailing.

Notification Examples

Choosing Multi-Line License (Quantity Based) gives you more control over how the license information is displayed, which can be especially useful if multiple licenses will be sold in the same order.

Single-Line License (Quantity Based)

When using the Single-Line License (Quantity Based) Order Fulfillment output format, the "FastSpring Multi-line License Response" SOLO Server setting under Store / FastSpring Options needs to be unchecked. The License ID and Activation Password will be listed on separate lines when using #{orderItem.fulfillment.license.licenses.list}. Refer the following examples as a reference, and process a test order and use the Preview option in SpringBoard to check your content is displayed as expected.

Multi-Line License (Quantity Based)

When using the Multi-Line License (Quantity Based) Order Fulfillment output format, the "FastSpring Multi-line License Response" SOLO Server setting under Store / FastSpring Options needs to be checked. Refer the following examples as a reference, and process a test order and use the Preview option in SpringBoard to check your content is displayed as expected.