TrialPay Integration with IPN.NET

I’m slowly closing in on being able to release the new Photo Resizer Social Edition. It will feature 1-click photo uploading to Facebook, Flickr, and TwitPic/Twitter, but all that has been the easy stuff so far. The licensing and marketing side of it is where the real work is.

Building on how I integrated ILS and IPN.NET with DotNetNuke, I’m now adding in TrialPay to the licensing process. For those that don’t know TrialPay, it’s a fantastic idea from Alex Rampell, Terry Angelos and Eddie Lim who founded TrialPay in 2006. I first met them at SIC 2006 in Denver. (I think that was the last CoffeeCup party there as well.) I’d blogged about it here, and shortly thereafter got an email from Alex joking about how he was pissed that I was beating them in the search engines for “trialpay”. We got a kick out of that.

Anyways, TrialPay lets you present users with an option to purchase some product or service, and in return, give them a license for your software for free. It’s good for everyone all the way around. I’ve recommended it to other developers, and they’ve come back with positive stories about increased revenues.

TrialPay has a very good interface to integrate with different styles of licensing systems. As I’ve already got IPN.NET and ILS in place, it’s just a matter of hammering things around a bit to get things working right.

My last round of DNN/ILS/IPN.NET integration is running smoothly, and adding in TrialPay has had noadditional  impact on DNN, though it does have a significant impact on IPN.NET.

While I’ve tried to minimize the impact, I also need to spend my time wisely. As such, there’s a higher impact on IPN.NET than I would really like, but the time it has taken to do it wasn’t very much.

To integrate TrialPay with IPN.NET, there are a few things that need to be done. All of the integration-specific changes and set up from the TrialPay side are done on the “Product Delivery” page in the product configuration:

Once there, under “Activation Method”, choose the “Provide a unique key that I will generate” option. You need to have your IPN.NET URL ready for that as well.

Most of the other settings are pretty straight forward, but you’ll want to make certain that you set up the parameters that TrialPay will POST to your IPN.NET instance. (Don’t use GET. That’s just a bad idea.) So, for example, you could have these parameters:

payer_email=%email%
first_name=%fname%
last_name=%lname%
item_number=ACME123

TrialPay gives you a huge amount of freedom to set up whatever you like. However, it is CRUCIAL that you pass a value for your item number (item_number) back to yourself. It MUST be the same as an existing item_number that’s already set up in IPN.NET. This will be the same as the item_number that you enter into License Tracker. (See my article on entering large numbers of products into License Tracker.)

The item_number is used by IPN.NET to create licenses, so, it’s just kind of a little bit important. 😉 However, see below for how to quickly hack this with the testing tool…

Once you have that set up, you can then move on to customizing your IPN.NET installation. You can get away with only 4 real changes:

1. Add in a string member variable to contain the key for TrialPay
2. Add in a ProcessPurchaseItem > ProcessTrialPayItem method
3. Add in a SendNotificationEmail >SendTrialPayNotificationEmail method
4. Add in some custom logic for TrialPay at the top of the Page_load method

IPN.NET has a huge amount of error checking, and even posts back to PayPal to verify license purchases. Now, you can work with this, but it’s a significant amount of effort, and has a massive impact on IPN.NET, so it might not be worth it to you. Instead, you can filter for TrialPay POSTs and then just run some custom logic and end there.

You can do that with minimal impact by adding that to the top of the Page_load event in IPN.NET. You can simply use an IpnData object to pull in the POST variables, but you’ll need to modify the IpnData class if you don’t use the same variable names. As such, it’s simpler to use the IPN.NET/PayPal variable in TrialPay, as you can see above.

The “ipn” IpnData variable is a member variable, so it has a global scope in Default.aspx.cs. You should set it something like this in the Page_load event:

ipn = new IpnData(Request.Form);

That then lets you reuse the “ipn” variable for TrialPay, and alleviates any need to rewrite basically everything.

Now, you’ll probably want to rewrite/tweak the ProcessPurchaseItem() and the SendNotificationEmail() methods. The “log” variable is a member variable as well, and you’ll need to do a lot of rewriting if you want to use it. If you want to work with License Tracker for TrialPay purchases, then you’ll need to do a lot of that work as the log creates a logfile that gets emailed to you in IPN.NET normally. However, if you cut out the logging, it won’t get created, and you won’t be able to import it from Outlook with License Tracker. Yuck. That’s pretty complicated. So… Might as well take the quick and easy route…

Notably, IPN.NET does a POST back to PayPal for verification, and you can’t do that while using TrialPay. This happens in the Page_load event just before the ProcessPayment() method call. The ProcessPayment() call contains the ProcessShoppingCartItems() and ProcessSinglePurchaseItem() method calls, which is where the actual licensing “work” gets done.

For TrialPay, I’m only interested in selling 1 license at a time, so I’m only concerned with the ProcessSinglePurchaseItem() method. It contains the ProcessPurchaseItem() method call, which as I’ve mentioned above, I’ve tweaked for TrialPay.

So, I’ve simply created a ProcessTrialPayItem() and a SendTrialPayNotificationEmail() method from the 2 mentioned above, then tweaked them for what I need, i.e. to send people their licenses and send me a quick and dirty email notification. You can open up the source code to see inside them. From what I’ve written here, it should be very simple for you to modify them similarly to what I have, or perhaps even more extensively, depending on your requirements.

Modifications for the ProcessTrialPayItem() method basically boil down to commenting out the log calls, and the tweaks I’d previously made to integrate IPN.NET into DNN. Actually, this entire block can be deleted:

if (item.IsUpgrade)
{ … }
else if (!CartHasPrerequisiteItems(item))
{ … }
else if (BlockCustomerEmail())
{ … }

However, it doesn’t matter whether you delete it or not. None of those conditions will ever be satisfied except possible the BlockCustomerEmail() method call. However, there I would strongly recommend either deleting the entire contents of that file, or very carefully editing it. If you’re selling consumer level or professional level software, the chances are VERY high that many of your customers will have email address that would get blocked there. Not good.

Modifications for the SendTrialPayNotificationEmail() method boil down to nothing. There’s a log check to see if it is null, but that can stay in.

Now, if you want to hack things up while testing with the Infralution IPN Test Tool, just set the product item_number something like this:

item.ItemNumber = “ACME123”;

You can add in some logic that draws on data from the TrialPay POST (if you have more than 1 product pointing to the same IPN.NET instance), but that’s not very hard to figure out. You just need to keep it straight with the Infralution IPN Testing Tool.

The issue there is that you can end up with “item_number1” when you’re expecting “item_number”. It can be remedied, but I’m quite frankly too busy/lazy to get on top of that one when I have zero reason to right now.

I can’t post much code as that is not a part of what I am allowed to do according to my Infralution source code license, but I can post a little bit. The following is some very brief logic for what you want to stick up at the top of your IPN.NET Page_load event:

// If we have a Trial Pay sale...
if (isTrialPay)
{
    // Recycle the "ipn" member variable:
    ipn = new IpnData(Request.Form);
    // Create an item for the TrialPay "purchase"
    PurchaseItem tpItem = new PurchaseItem();
    // Hack/fix the item number for the InfralutionIPN Testing Tool
    tpItem.ItemNumber = "ACME123"; // Used below
    // Now, get the item from your existing IPN.NET settings:
    tpItem = GetPurchaseItem(tpItem.ItemNumber);
    // Call the tweaked method to process the "purchase":
    ProcessTrialPayItem(tpItem, 1);
    // Send the license email to the customer:
    SendTrialPayNotificationEmail();
    // Clear the HTML body response but not the headers (should be 200):
    Response.ClearContent();
    // You must return the key to TrialPay in the HTML body.
    // "tpKeys" is a member variable that you set in the ProcessTrialPayItem() method above:
    Response.Write(tpKeys);
    // HTML markup is not valid for the response to TrialPay, so end the response and send it back:
    Response.End();
    return;
}

Now, you’ll need to figure out how you want to verify a TrialPay POST, as I’m not going to do that here. Just read their documentation and you’ll figure it out quickly enough.

You will also likely want to add in a bit more error checking and whatnot. I’ve cut things down there to the very basics as described above.

That’s about all there is to it though. I hope that serves as a good starting point for anyone that wants to integrate TrialPay sales into their Infralution IPN.NET system.

Cheers,

Ryan

P.S. If you want to find out more about TrialPay, click the button: