2Checkout.com

In developing Bitesize Irish Gaelic (the idea was there for a while, but needed to be polished), I decided to use 2Checkout.com as the processor of recurring payments.

Why them? I’ve been using them since 2002 on Irish-Sayings.com and LearnIrishGaelic.com. No fancy stuff, just a landing page that accepts sale parameters.

Since then, they came out with an Instant Notification System (INS). It basically calls a specified script on your sever whenever an order is placed, or when fraud status changes, if it’s cancelled, or if a recurring payment has billed. Basically, an automated way to know what’s being ordered from you and what needs to be fulfilled. They also provide a backoffice API for looking up customer and order information.

Confusing inconsistencies

2Checkout.com calls a Direct Return immediately after each sale is complete. That notifies my server immediately of a new sale. It’s how I can provide the user with instant access to what they buy. Within the next few seconds (or perhaps up to 5 minutes later), and INS call is also made with further details of the sale.

Two services with some overlapping data.
The direct return is older than INS, and the INS was developed without, it seems, directly matching what already existed. For example, direct return has an order_number parameter, but INS calls it sale_id (same information). Both are promoted services to developers.

Differing information structures.
An INS call is based on the idea of a sale having an invoice and an invoice having invoice items. Great for storing in a database! But guess what, the Direct Return describes product_id, product_id_1, etc. depending on how many items in the sale, and specifies no invoice number. However, INS describes an invoice number with invoice items item_id_1, item_id_2, etc. What a mess.

The INS API doesn’t do what it promises

Two or three months ago, I gave 2Checkout.com a phone call for the first time. I was testing my billing system built on top Direct Return+INS, after learning a lot about their specifications. For some reason, my test purchases were successfully coming in, getting recorded in my database through INS calls, but lacked any information on the recurring sale, contrary to the spec.

For example, the “status of payment” was NULL, the “next bill date” was NULL, and the price for the recurring item was NULL.

Good thing I called them. Turns out that with any PayPal payment (through which I was testing), 2Checkout.com had a bug where it didn’t provide any of this information.

Seriously, if your application depends on 2Checkout.com to keep track of which date each customer has paid up until, it won’t work. Despite the INS specification promising this information, it’s just not supplied.

As of this week, they have confirmed that the bug still exists.

Ways around it

If you’re a programmer, probably you’re thinking, “There’s lots of ways around this bug!“. I agree (and I have already changed my implementation).

The point is, this payment service that processes recurring payments on my behalf can’t even tell me, in line with the documentation, until what date has this customer paid for.

Custom search engines in your browser are all the rage these days. Well, more honestly, they’re not. They won’t make girls swarm in your direction, but they people search your site directly from within in their browser (instead of visiting your site first).

I’ll give you step-by-step directions on how to create your own browser search engine. I put together one for searching the dictionary at Irishionary.com, and you can see it as an addon on Mozilla.org.

In Firefox, my custom search engine look like so:

Custom browser search engine for Irishionary.com.

Creating a browser search engine is quite simple. You write an XML file to describe your search functionality, then you expose that XML file to your site’s visitors. The XML file specification is called OpenSearch, a standard to describe search engines that your browser will understand. We’ll have the search results display as a web page, but you can have the spat back as JSON or whatever.

What you’ll need

1. A knife.
2. A rubber band.
3. A web site with its own search functionality that accepts GET requests (for compatibility with Internet Explorer). For example, you’ll need a page such as http://www.example.com/search.php?query=beer .

Step 1: Create your XML description file

Copy-paste this XML code to a file such as search.xml. You can see mine live in action at http://www.irishionary.com/scripts/browser_search.xml.

<?xml version="1.0" encoding="UTF-8"?>
<OpenSearchDescription xmlns="http://a9.com/-/spec/opensearch/1.1/"
                   xmlns:moz="http://www.mozilla.org/2006/browser/search/">
	<ShortName>Irishionary.com</ShortName>
	<Description>Irish language dictionary.</Description>
	<Tags>gaeilge irish gaelic dictionary</Tags>
	<Contact>info@irishionary.com</Contact>
	<InputEncoding>iso-8859-1</InputEncoding>

	<OutputEncoding>iso-8859-1</OutputEncoding>
	<Image width="16" height="16" type="image/x-icon">http://www.irishionary.com/favicon.ico</Image>
        <Image width="64" height="64" type="image/png">http://www.irishionary.com/resources/images/search_logo.png</Image>
	<Url type="text/html" method="get" template="http://www.irishionary.com/process/search.php?search_phrase={searchTerms}">
	</Url>
	<Url type="application/opensearchdescription+xml"
		rel="self"
		template="http://www.irishionary.com/scripts/search.xml" />
	<Query role="example" searchTerms="beer" />

	<Language>en-us</Language>
	<Language>en-gb</Language>
	<Language>ga</Language>
	<moz:SearchForm>http://www.irishionary.com/</moz:SearchForm>
	<AdultContent>false</AdultContent>
	<Attribution>Search data copyright eTeanga (www.eteanga.ie)</Attribution>

</OpenSearchDescription>

Step 2: Customise your XML file (boring)

So the code above describes the Irishionary.com Irish Dictionary search engine. Use your common sense when editing the tags.

Here are some boring details on some of the parts that may need an explanation. There is a full specification of the OpenSearch format available.

• <InputEncoding> and <OutputEncoding> describe the character encoding that your search engine first accepts, and then spits out (in our case, the character encoding of your HTML search results).
• The <Image> tags describe two sizes of icons that represent your service. The browser might use the smaller icon to display beside the search box. The bigger image may be used by a directory of search engines, for example.
• The first <Url> tag is the meat of this whole operation. It describes where to send the search query to get the results. It’s the http://www.example.com/search.php?query=beer URL I mentioned above. In the XML tag, note that {searchTerms} is how you capture what the person typed into the search box. Using our original example, you’d put in http://www.example.com/search.php?query={searchTerms}
• The second <Url> tag is the URL for where you’re going to publish your XML file online. This will allow the browser to check for updates to your XML in the future.
• The <Query> is a way to give an example search query. I don’t know where this is displayed.
• The <Language> tags specify which languages your search engine will accept. It may only be one language. I think you can also use * as a wildcard for “any language”.
• We’re almost there! <moz:SearchForm> is a Firefox-specific tag which points to where the search form is online.

Step 3: Upload your XML file

Do it. I haven’t been able to get Firefox to recognise a file hosted locally on my machine.

Step 4: Tell your browser about your search engine

There are a couple of ways to test your engine. The first is to let your browser “discover” it. In the HTML of a test page on your site, add the following code inside the <head></head> tags. Customise it to point to where your XML is found.

<link rel="search" type="application/opensearchdescription+xml" title="Test Search" href="http://www.irishionary.com/scripts/browser_search.xml" />

Now *visit* that HTML page in your browser to “auto-discover” the tag you’ve included.

Add to Firefox

When viewing the HTML page that includes the <link> tag above, click the little highlighted arrow beside your default search engine in the search bar. It should look something like the following:

The little arrow gets highlighted when Firefox detects your search engine mentioned in the tag.

When you click the arrow, you’ll see the list of installed search engine with the option to “Add” your own engine. If your engine hasn’t been listed, there’s something wrong with your <link> tag above. Once added, you can test your engine!

Add to Chrome

Google give instructions on how to add a detected engine to the browser.

Step 5: Test your search engine

In Firefox, select your engine from the list of search engines, and perform a search. Check out if it brings you to your site’s search results page. If you’ve gotten this far, get someone to pat you on the back. In fact, this may be one of your life’s biggest achievements. Well done.

Bonus step: Direct install link for your visitors

You’ll want to promote the search engine on your site to your visitors. It needs a little Javascript link to get this done:

<a
href="javascript:window.external.AddSearchProvider('http://www.irishionary.com/scripts/browser_search.xml');">Add
engine</a>

Customise the URL in there to point to your own XML file. Now visitors can install the search engine directly from your site.

(Yet Another) Bonus step: Submit to Mozilla

A good way to promote your search engine is to submit it to Mozilla’s addons repository for Firefox. It takes some effort. You’ll need to create a developer profile, then submit your addon for testing. Once you move it out of the “sandbox” it will be available publicly and marked as “experimental”. Have your users test it out for a while, then you can ask for it to be fully released. Get started on Mozilla’s developers’ guide.

Congrats, you’re created a browser search engine. I hope you’ve learned some bits here. There is a good best practices guide over at OpenSearch’s site.

<Image