Configuring FastSpring Classic Store Integration

This topic is a guide on how to configure to configure the integration between a FastSpring classic 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 Product Option(s) configured in SOLO Server.
4. You already have a FastSpring account.
5. You already have a basic working knowledge of FastSpring and its SpringBoard 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 script for each notification you configure in FastSpring. To obtain this URL, click the Store / FastSpring Options menu, where this URL is listed as the Fulfillment 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 SpringBoard, manage the product, and click "Add" under the Fulfillment Actions section. Select "Generate a license", pick the "Remote Server Request" option, and click Next.
3. Enter the URL of the FastSpring Integration 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 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 "FastSpring API Private Key" value, and paste it into FastSpring's "private key" field.
5. 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.
6. 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 Completed Notification as outlined below.
7. Click Save on the 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 Order Completed Notifications

As noted above, FastSpring only sends very limited information about the customer when generating licenses. 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. If you want FastSpring to provide SOLO Server with additional information about the customer, it is necessary to do so using an Order Completed Notification. Here is how you can configure this in FastSpring:

1. In SpringBoard, click the notification icon at the very top, right.
2. Under the Custom Notifications section, click Add.
3. Choose "Order Completed (one per product)" for the event type.
4. Choose HTTP URL for the Destination. Paste in the URL to the FastSpring Integration Script (to obtain this URL, click the Store / FastSpring Options menu, where this URL is listed as the Fulfillment URL), leave the content type as Name/Value Parameters, and click Next.
5. In the General tab, you may optionally give the notification a name.
6. Under the Conditions tab, you may optionally configure the notification to only apply to select Products.
7. In the Advanced tab, select ISO-8859-1 for the Character Encoding.
8. In the Security tab, paste the private key you established for all notifications sent to SOLO Server. To retrieve this value from SOLO Server, sign-in to SOLO Server, click Store / FastSpring Options, copy the "API Private Key" value, and paste it into FastSpring's "private key" field.
9. In HTTP parameters, you can leave the defaults in place, and add the following parameters (by clicking the Add Parameter button and filling out the new fields for each):
   1. Add a parameter named swk_action, with a value of OrderCompleted.
   2. Add a parameter named swk_authorid, with the Author ID you see at the bottom of SOLO Server's authors administration interface.
10. Click Save when done.
11. Now place a test order using an email address that has a corresponding customer record in SOLO Server, and make sure SOLO Server updates the registration data when an order for an applicable FastSpring product is completed.

With this configuration in place and verified, it may now be time to consider what happens when a customer's order is returned/refunded.

Configuring Return Completed Notifications

Return Completed Notifications tell SOLO Server when a FastSpring order has been returned, and provides some information about the return. This allows SOLO Server to send a notification to author users configured with "Notify Orders" enabled. The notification SOLO Server sends includes licenses associated with the original order, which may need to be deactivated (depending on the nature and details of the return).

The steps for configuring Return Completed Notifications are outlined below.

1. In SpringBoard, click the notification icon at the very top, right.
2. Under the Custom Notifications section, click Add.
3. Choose "Return Completed" for the event type.
4. Choose HTTP URL for the Destination. Paste in the URL to the FastSpring Integration Script (to obtain this URL, click the Store / FastSpring Options menu, where this URL is listed as the Fulfillment URL), leave the content type as Name/Value Parameters, and click Next.
5. In the General tab, you may optionally give the notification a name.
6. Under the Conditions tab, you may optionally configure the notification to only apply to select Products.
7. In the Advanced tab, select ISO-8859-1 for the Character Encoding.
8. In the Security tab, paste the private key you established for all notifications sent to SOLO Server. To retrieve this value from SOLO Server, sign-in to SOLO Server, click Store / FastSpring Options, copy the "API Private Key" value, and paste it into FastSpring's "private key" field.
9. In HTTP parameters, you can leave the defaults in place, and add the following parameters (by clicking the Add Parameter button and filling out the new fields for each):
   1. Add a parameter named swk_action, with a value of ReturnCompleted.
   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 OriginalOrderID, with a value of #{return.original.id}.
   4. Add a parameter named OriginalTotal, with a value of #{return.original.total}.
   5. Add a parameter named ReturnEmail, with a value of #{return.customer.email}.
   6. Add a parameter named ReturnID, with a value of #{return.id}.
   7. Add a parameter named ReturnReason, with a value of #{return.reasonText}.
   8. Add a parameter named ReturnTotal, with a value of #{return.total}.
   9. Add a parameter named ReturnType, with a value of #{return.type}.
10. Click Save when done.
11. Now place a test order for an applicable product, issue a return/refund in SpringBoard, and make sure SOLO Server sends you a notification outlining the licenses associated with that order.

The nature of returns is not always easily deduced from the data in Return Completed Notifications, which is why the notification SOLO Server sent only informs you of licenses that may require your review and possibly further action from you. You can choose to change the Status of the license in SOLO Server, which will deactivate the software using that license when it validates with SOLO Server.

In the case of subscriptions, SOLO Server is only aware of the original order reference number from FastSpring, which is why Return Completed Notifications should not be configured for these types of FastSpring products. This means that, when returning a subscription payment (other than the initial purchase), SOLO Server will not be able to find the original licenses involved with the subscription (this is in part due to a limitation of what's available in FastSpring's notifications). Additionally, deactivating a subscription is a scenario where it does make sense to automatically disable a license in SOLO Server, and this is explained further in the next section.

Configuring Subscription Deactivated Notifications

When issuing licenses in SOLO Server for subscriptions managed by FastSpring, it may be necessary to void a license when the FastSpring subscription payment is not received. This allows you to leverage the two systems to offer your software as a service that requires payment on a recurring basis.

Follow the steps below to configure this feature:

1. In SpringBoard, click the notification icon at the very top, right.
2. Under the Custom Notifications section, click Add.
3. Choose "Subscription Deactivated" for the event type.
4. Choose HTTP URL for the Destination. Paste in the URL to the FastSpring Integration Script (to obtain this URL, click the Store / FastSpring Options menu, where this URL is listed as the Fulfillment URL), leave the content type as Name/Value Parameters, and click Next.
5. In the General tab, you may optionally give the notification a name.
6. Under the Conditions tab, you may optionally configure the notification to only apply to select Products.
7. In the Advanced tab, select ISO-8859-1 for the Character Encoding.
8. In the Security tab, paste the private key you established for all notifications sent to SOLO Server. To retrieve this value from SOLO Server, sign-in to SOLO Server, click Store / FastSpring Options, copy the "API Private Key" value, and paste it into FastSpring's "private key" field.
9. In HTTP parameters, you can leave the defaults in place, and add the following parameters (by clicking the Add Parameter button and filling out the new fields for each):
   1. Add a parameter named swk_action, with a value of SubscriptionDeactivated.
   2. Add a parameter named swk_authorid, with the Author ID you see at the bottom of SOLO Server's authors administration interface.
10. Click Save when done.
11. Now place a test order for a subscription product. When done, pull up one of the License IDs in SOLO Server and observe its "OK" status. In SpringBoard, search for the Order Reference or Subscription Reference number, view the subscription (this is an extra click if you used an order reference), click Cancel on the right, select the option to Cancel Now, and click Confirm. Refresh the license in SOLO Server and make sure its status is now set to "Expired."

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 the notifications:

1. In SpringBoard, go to the home page and click Products and Pages under the Products and Settings section.
2. Click on the Product/Subscription you want to configure.
3. Under Fulfillment Actions, click Add.
4. Choose Send Email / Show Web Notification and click Next. View FastSpring's support page for more information on email / web notifications.
5. Once you click Create, additional tabs will be available.
6. 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.