Subscription Integration Overview
This article describes the necessary steps to integrate your platform with FastSpring billing and discusses three events that are part of a subscription integration: sign up, cancellation and subscription payment. It also describes the setup process of the notifications associated with customer sign up and cancellation, as well as examples of the PHP and ASP scriptsdescribed in the integration process.Customer Sign Up
In this example of the customer sign up process that occurs with a subscription, John is the customer and Alvin is your company. John has already signed up for a free account (or an account with limited access) and has entered in basic information (such as his name, email address, etc.) that has been stored and creates a custom referrer that uniquely identifies him to Alvin's service.
When John views your website to upgrade to more advanced features of your product (which he may or may not have paid for already), the billing script (which is already aware of his custom referrer), queries Alvin’s customer database to retrieve his FastSpring subscription reference (API key) and then calls FastSpring's Subscription API to determine if John has a current paid subscription. When Alvin's customer database shows that John does not have a current subscription, John is automatically redirected to FastSpring’s subscription sign-up page, passing in his unique custom referrer.
After John signs up, FastSpring sends a Subscription Activated Notification containing the subscription reference to Alvin’s activate script that updates his customer database. Both the notification and API provide access to the custom referrer that was passed when the subscription was started, so that Alvin's service can identify for whom the subscription was purchased.
Customer Cancellation
When John wants to cancel his subscription, he clicks on a link to the billing script. John's custom referrer is passed in as a GET parameter at the end of the URL and the billing script queries Alvin’s customer database to look up his FastSpring subscription reference (API key). When Alvin's customer database finds John's subscription reference, FastSpring's subscription URL page billing script makes a subscription API call to determine if John's subscription with FastSpring is active or deactivated. The API call returns the customerUrl and the billing script redirects to this page. John now has the ability to cancel his subscription or update his payment method. If John chooses to cancel the subscription, Alvin’s deactivate scriptwill be called and it will remove the subscription information from Alvin’s customer database.
Subscription Payment
A subscription payment works like any other payment within FastSpring. You can either define fulfillment actions (see also Subscription Product Setup) and/or order notifications (see also Notifications Overview). This enables you to take subsequent actions like sending an email or updating your customer database for successful subscription payments.
Subscription Notifications
To create notifications associated with subscriptions, go to SpringBoard's Store Home » Notify. Click Add next to Custom Notifications.
Subscription Activated Notification
Select Subscription Activated as the Event Type. Select HTTP URL as the Destination. Create a URL on your server, such as http://www.yoursite.com/callback/activate.php , and enter this URL as the Live Server URL. Select Name/Value Parameters for the Content Type. Click Next. Click Move to Active Status.
Subscription Deactivated Notification
Select Subscription Deactivated as the Event Type. Select HTTP URL as the Destination. Create a URL on your server, such as http://www.yoursite.com/callback/deactivate.php , and enter this URL as the Live Server URL. Select Name/Value Parameters for the Content Type. Click Next. Click Move to Active Status.
PHP and ASP Script Examples
Activate Script
This scripts receives a customer and subscription reference from the notification and enter that information into your database.
activate.php Example
<?php
/** Constants */
$customer_data_dir = "/var/tmp";
$customer_ref = $_POST["SubscriptionReferrer"];
$subscription_ref = $_POST["SubscriptionReference"];
if($customer_ref == null) {
header("HTTP/1.0 404 Not Found");
} else {
$customer_data = fopen("$customer_data_dir/$customer_ref.txt", "w") or die("Can't open file.");
fwrite($customer_data, $subscription_ref);
fclose($customer_data);
}
?>
activate.aspx Example
<%@ Language="C#" %>
<%@ Import Namespace="System.IO" %>
<html>
<script language="c#" runat="server">
public void Page_Load(object sender, EventArgs e)
{
string customer_data_dir = Path.GetTempPath();
string customer_ref = Request.Form["SubscriptionReferrer"];
string subscription_ref = Request.Form["SubscriptionReference"];
if (customer_ref == null)
{
throw new HttpException(404, "Post data is not complete");
}
else
{
StreamWriter writer = new StreamWriter(customer_data_dir + "\\" + customer_ref + ".txt");
writer.Write(subscription_ref);
writer.Close();
}
}
</script>
</html>
Billing Script
These scripts receive a customer reference (custom referrer) and check that the customer already has a subscription. If there is no current subscription, it redirects to the sign up page. Otherwise, the customer will be redirected to a page where they can manage their subscription.
billing.php Example
<?php
/** Constants */
$customer_data_dir = "/var/tmp";
$store_id = "your_company";
$product_id = "your_product";
$api_username = "your_username";
$api_password = "your_password";
/** Alvin's customer identification */
$customer_ref = $_GET["customer_ref"];
/** Set $redirectToUrl */
$redirectToUrl = null;
$customer_data = fopen("$customer_data_dir/$customer_ref.txt", "r");
if($customer_data == null) {
$redirectToUrl = "http://sites.fastspring.com/$store_id/product/$product_id";
} else {
$subscription_ref = fgets($customer_data);
fclose($customer_data);
$response = new DOMDocument();
$response->load("https://api.fastspring.com/company/".$store_id."/subscription/"
.$subscription_ref."?
user=".$api_username."&pass=".$api_password);
$redirectToUrl = $response->getElementsByTagName("customerUrl")->item(0)->nodeValue;
}
/** Redirects to sign-up or subscription page */
header("Location: $redirectToUrl");
?>
billing.aspx Example
<%@ Language="C#" %>
<%@ Import Namespace="System.IO" %>
<%@ Import Namespace="System.Xml" %>
<html>
<script language="c#" runat="server">
public void Page_Load(object sender, EventArgs e)
{
Response.BufferOutput = true;
string customer_data_dir = Path.GetTempPath();
// Constants
string store_id = "your_company";
string product_id = "your_product";
string api_username = "your_username";
string api_password = "your_password";
// Alvin's customer identification */
string customer_ref = Request.Form["customer_ref"];
// Set redirectToUrl
string redirectToUrl = null;
FileInfo customer_data = new FileInfo(customer_data_dir + "\\" + customer_ref + ".txt");
if (!customer_data.Exists)
{
redirectToUrl = "http://sites.fastspring.com/" + store_id + "/product/" + product_id;
}
else
{
StreamReader data = customer_data.OpenText();
string subscription_ref = data.ReadToEnd();
data.Close();
XmlDocument response = new XmlDocument();
response.Load("https://api.fastspring.com/company/" + store_id +
"/subscription/" + subscription_ref + "?user=" +
api_username + "&pass=" + api_password);
redirectToUrl = response.GetElementsByTagName("customerUrl").Item(0).InnerText;
}
Response.Redirect(redirectToUrl);
}
</script>
</html>
Deactivate Script
These scripts receive the customer reference (custom referrer) and remove the customer from your database.
deactivate.php Example
<?php
/** Constants */
$customer_data_dir = "/var/tmp";
$customer_ref = $_POST["SubscriptionReferrer"];
if($customer_ref == null) {
header("HTTP/1.0 404 Not Found");
} else {
unlink("$customer_data_dir/$customer_ref.txt")
}
?>
deactivate.aspx Example
<%@ Language="C#" %>
<%@ Import Namespace="System.IO" %>
<html>
<script language="c#" runat="server">
public void Page_Load(object sender, EventArgs e)
{
string customer_data_dir = Path.GetTempPath();
string customer_ref = Request.Form["SubscriptionReferrer"];
if (customer_ref == null)
{
throw new HttpException(404, "Post data is not complete");
}
else
{
FileInfo customer_data = new FileInfo(customer_data_dir + "\\" + customer_ref + ".txt");
customer_data.Delete();
}
}
</script>
</html>
We're Here to Help
If you need assistance with the subscription integration process, please open a support ticket.