Product API Guide for Programmers

Overview

This is a guide for programmers who want to interface their point-of-sale systems to Product, to allow them to accept payment from Product members.

The Product API is implemented over HTTPS, either in XML or in JSON. The result is the same, and the requests are analogous between XML and JSON. The POS software you write is called the client in this document; our HTTPS destination is called the server in this document.

The sequence of events takes place as follows:

• Your client software signs on and gets back a Sign-in Token. You will need this token for the rest of the requests.
• Your cashier enters items to be bought using whatever means. You client collects this list, probably managing the list with the existing inventory/purchase infrastructure.
• At the end, the cashier scans the customer's barcode, whether on their smartphone or on a card. With the barcode, you send a Send Order request. In response, you get back information about the customer you'll need for the confirmation, including the URL of a photo of them.
• Your client displays the photo. The cashier looks at the customer photo on the screen, and compares against the customer's actual face. The cashier indicates to the client software (in your cash register) whether the faces match (a Confirm Order request) or not (a Deny Order or Cancel Order request). Accordingly, the transaction either is made or is discarded.
• Your client can continue to send Send Order and Confirm Order requests, one for each customer order.
• Your client signs off to invalidate your sign-in token after it is no longer needed.

Intended Audience

This document is intended for programmers wishing to add the ability to take Product as a payment method on your point-of-sale equipment.

You should be proficient in your chosen programming language, and you should have some experience with either JSON or XML. You should be able to read JavaScript for the Reference Client, but in-depth JavaScript knowledge is not required. (JavaScript is similar to Java, PHP or C++ syntax; the complicated parts in the Reference Client don't deal with the protocol much.)

Requirements

Your POS must be a programmable computer, with enough ram to, for instance, run a browser with fairly complex pages. You can use any programming language you want, but it must be able to generate ASCII text for XML or JSON. Most computers that can do web surfing are powerful enough.

This API operates over the internet to access the Product server. Your POS must have some sort of internet access and the ability to do HTTPS POST requests.

The POS screen must be able to display a photo of the customer to the cashier. This is a crucial part of the Product system and is part of what makes it so secure. We can supply five different photo sizes from 40 pixels to 640 pixels, although the lower resolutions lose a lot of detail.

We document the API in its raw XML or JSON format; we do not provide a library beyond the Reference Client, which shows you how it is done in JavaScript. You should Save the HTML and examine the JavaScript code in it. Feel free to modify it for your own experimentation.

Whichever format you choose, it is very helpful to have a parser library that can read the format and either produce a tree, or generate callbacks (such as the SAX xml library). The Reference Client uses native JSON and XML parsers built-in to modern browsers; the difficulty of parsing data depends on the tools available in your particular programming envrionment.

The JSON or XML that you must generate can be done with simple Print statements, or you can use a similar library that is designed to generate JSON or XML.

Choose whether you want to see the JSON or XML in the rest of this document.
Show JSON examples
Show XML examples

Data Structures

Requests

Each request is an HTTP POST, whose body is either XML or JSON. For best results, the MIME type of the body should ideally be application/json or application/xml. You send the requests to one of the URLs:

Your POSTs must be raw data posts, not as with a form. For instance, if you had an HTML form like this:

<form method="POST">
	<input name="area" VALUE="Sonoma">
	<input name="city" VALUE="Atkinson">
	<input type="submit" name="submit" VALUE="submit">
</form>

area=Sonoma&city=Atkinson&submit=submit

{ "action": "signOut", "apitoken": "tDPKWDh0I1S9mCAtEu9hxvKuOSG4ALtT" }

Replies

Each request will return a response that is the same type as the request (XML/JSON). The MIME type will be application/json or application/xml. Every response has a property errorCode that will tell you if the request failed or succeeded. Success is 'Success', and failure is some other code, either numerical or alphanumerical.

Sign In Token

The Sign In Token is a 32 character string that you send with almost every request. You must send this with each request, although the server will set a cookie for you named apitoken. If your client HTTP interface can pick up and send back cookies (eg Curl) then the cookie can take care of this for you; otherwise, just send it as an argument with each request that needs it. Do a Sign Out request when you are done with it, for security.

This token is your context identifier. Orders, or other sequences of requests, collect details that are attached to the sign-in token, back in our servers. If you try to interleave individual requests for different orders on the same token, the server will get confused, leading to unexpected results (probably, orders being lost instead of processed). Instead, sign in a second time to get another sign-in token, and process orders on that sign-in token independently and concurrently with the original token.

Your implementation can either present a Product email and password dialog for the cashier to directly log in, or you can rely on some other authentication (or even none at all) for your cashier, while your implementation keeps the Product credentials internally. Product does have a way to distinguish between cashiers in a company by giving each their own cashier account and signon info; if you want, you could set up parallel cashier accounts on FC for each of your own cashier accounts. This way, we can keep track of which cashier was responsible for what transactions on your behalf.

A token is guaranteed to last 20 minutes or more from the time of the most recent request. Your client should manage this timeout for best results. Here are some suggested approaches:

• Your client can simply send a Ping every 15 or 19 minutes, regardless of what other requests are made.
• Your client can track the time from the latest request, and send a Ping if the elapsed time approaches the timeout.
• If your transactions come infrequently, you can simply run a transaction by signing in, processing the order, then signing out. This would be a lot of overhead, however, for a high-volume situation.

JSON

JSON is a popular format, easier than XML. It is based on JavaScript, but the rules are more strict.

A brief recap of the rules, and the way we use them:

• All attribute names, and all values that are not numbers, must be surrounded by double quotes. {"like": "this", "or this": 5661}
• All arrays are separated by commas and surrounded by square brackets ["like", "this"] [{"or": "like"}, "this"]
• Our JSON is in UTF-8, although you can send flat ASCII as it's a subset of UTF-8. You must escape (backslash) certain characters:
  " => \"
  \ => \\
  / => \/
  So instead of Racing Series 518 Red/Machined - 18 x 7.5 Inch Wheel you need to send down Racing Series 518 Red\/Machined - 18 x 7.5 Inch Wheel. For characters whose value is beyond 127, you can either encode in UTF-8 like série => the bytes s 0xc9 0x83 r i e or you can use a \u construct like série => s\u00e9rie. Some internet libraries have some functions that can do that for you.
• The top level is always an object with an action attribute that's camel-cased, such as sendOrder. This is the verb in your request.
• You can use whitespace (space, tab, linefeed, return) freely outside of quoted strings.

For more information about JSON, see the official JSON specifications or the JavaScript Kit.

XML

The XML we use is a proprietary dialect, so it does not follow a protocol like SOAP or XML-RPC.

A brief recap of the rules, and the way we use them:

• All tags must be closed - like <blah></blah>. Nested elements must close within their level.
• We don't use attributes in our XML; instead we use subobjects. For instance, <axe><head>72</head></axe> instead of <axe head="72"></axe>
• All arrays are sequences of singular-named tags enclosed by plural-named tags, as in <dogs><dog>Barclay</dog><dog>Scruffy</dog></dogs>.
• By default, XML is in UTF-8, although you can change this with the right heading line. Use entities such as &aring; = 'å' for maximum safety.
• You need to translate certain characters in your text being included into entities. These two are mandatory:
  & => &amp;
  < => &lt;
  So instead of 50mm Telephoto Lens for E300 & E500 Digital SLRs you need to send down 50mm Telephoto Lens for E300 &amp; E500 Digital SLRs. Many internet libraries have some function that can do that for you.
• The top level is always an element with a camel-cased name for the action, such as <sendOrder>. This is the verb in your request.
• You can use whitespace (space, tab, linefeed, return) freely outside of tags. We try to properly indent our responses for clarity but you don't have to.
• The response will always be <reply> at the top level, and there will always be an XML Declaration such as <?xml version="1.0" encoding="UTF-8" ?> at the start.

For more information about XML, see the official W3C spec or the O'Reilly XML site.

Member Photo

The Send Data request will return a URL for a photo of the customer, for comparison by the cashier. You should display this file (always a .jpg) on the cashier's display; this is a crucial part of the system. You can choose among five sizes to fit your display hardware. The URL will be entity-encoded in XML so ampersands will be &amp;.

The URL for this photo includes your sign-in token. Therefore, it is only good as long as your sign-in token is good. You can, however, display it under a different sign-in token, although you'll have to splice in your new token in place of the old.

Product ID

A Product ID is the numeric account number that a consumer uses to buy items. This is the number that appears below the customer's Product barcode, and which the cashier scans to initiate payment. Fundamentally, it is an 11-digit number. As encoded in the barcode, however, it has '000' (zero zero zero) prefixed onto it for a total of 14 digits.

Typically a barcode reader emulates a keyboard through USB or a similar interface. To the computer, it's just another keyboard. When it scans a Product ID, you will get three digit zeros, eleven digits for the number, and then a Return character, like this:

0 0 0 4 5 4 9 0 4 4 7 4 9 4 Return

You can send the number with or without the leading 000, it doesn't matter.

ErrorCode and ErrorMessage

Every response contains an errorCode property. 'Success' means that it succeeded (case sensitive; will always be spelled that way). If it is something else, there should also be another property, errorMessage. This will be a character string indicating what happened, in english. The error messages are meant for human consumption, and we reserve the right to change the wording as we see fit. The error code, however, will never change and you can test for specific codes if you want to handle specific error situations.

Entities

The term "entity" refers to something that spends and receives money, and pays taxes. This can either be a person, or a company that is incorporated. (Sole Proprietorships and certain other companies are the same entity as their owners.)

A Product account is actually multiple accounts. There is one account for each entity that the customer has authority to spend money for. The person is always the first entity, and any companies (usually zero or one) are each additional entities. These entities are set up as the user signs up, and upon subsequent changes that they make to their account. Each entity is assigned an integer that does not change, called the Entity ID.

One step the cashier must perform is to figure out which of the customer's entities is paying for the current purchase. That entity id forms part of the confirmation.

Locations

Large retailers often have multiple locations. If they are listed in their Product account, we can keep track of which location each transaction was conducted in. This is decided by the api username and password used in signin; each location has a unique set of credentials, and a person (manager) who is principally responsible for it.

Test Mode

Product offers a way to disable a merchant account for testing or training purposes. From your Home page, go to Settings > Locations, and choose the merchant location you want to test. Near the bottom should be Test Mode which you can turn off or on. With Test Mode on, every order you send to Product will be responded to in the normal way, but instead of actually charging the customer and crediting your account on our servers, the sale is ignored.

Leaving Test Mode on accidentally can be a disaster, as a cashier could ring up real purchases that would ultimately be forgotten. Turning it off by accident would mean all your test transactions would become real. Although you could refund the extra charges or re-enter orders, it would be needless trouble. To make sure you know when it is on or off, we email you a receipt for every test transaction you perform. In addition, every reply from the orders group of requests (that is, not signin/out, ping) carries an extra attribute testMode whose value is 1. We suggest that you use it to make some striking change to the appearance of your POS screen, such as changing large areas of color and/or adding a large banner that wasn't there before, to avoid accidents.

Description, Clerk ID and Reference Number

When you send an order, you can optionally send along a Description, a Clerk ID, and a Reference Number. They are all for your own use and are not visible to customers. The Description and Reference Number show up in the Orders and Payments listing when you log into the Product web site.

Use the Description to specify categories of transactions, or their department, or whatever you want.

Use the Clerk ID to specify which clerk, waiter or salesperson registered the order. For restaurants, we can collect tips by clerk ID for disbursement later. The Clerk ID is sent down with the order confirmation rather than the original order.

Use the Reference Number to record your internal transaction ID to better match our records with yours.

The Description can be any character string using Latin-1 encoding, up to 100 characters long. The Clerk ID and Reference Number can also be anything from Latin-1, but only 25 characters long. Longer strings will be truncated.

Tips and Tipping

Many Product merchants are restaurants and other service businesses where customers might leave tips for the individuals who serve them. Product manages these tips and allows the merchant to apportion tip money to exactly the clerks who deserve them.

Central to this system is a setting for each of the merchants' locations: the tipping policy. A merchant changes this in the Settings > Locations area from the home page.

• Disabled - No tipping at all. All transactions are straightforward, for the total amount. This is usually the case for retail stores that sell things.
• Expected - Everybody expects the customer to leave a tip. Restaurants usually chose this setting.
• Encouraged - This is an intermediate setting, for more informal restaurants or coffeeshops, where tipping is optional for the customer.

The customer enjoys a meal at a restaurant and then pays the bill with FC for the total amount, not including the tip. After leaving the restaurant, the customer uses their Product smartphone app, or the website, to choose a tip for the waiter. They have two hours, after which a default tip is applied so the transaction can be closed. As of this writing, Expected defaults to an 18% tip, and Encouraged defaults to a zero tip at the end of this period.

These are automatically provided if the merchant's setting is set to Expected or Encouraged.

Request Details

Sign In

Use this request to sign in and get a token to use on the other requests.

This request returns your API token in apitoken. You must pass this in all of your other requests using this api, in an attribute called apitoken, or in an HTTP cookie named apitoken. Your HTTP interface may or may not do cookies; often the simplest is to just pass it with each request.

In addition, it sends you back the timeout for your session. If you go without a request for that many seconds, the API will automatically sign you out. See the Ping request for more info.

Ping

Your apitoken lasts for the signintimeout (currently 60 minutes) from the time of last use. Renew it by sending any request before it times out; a Ping request is good for this because it does nothing else. (The current duration is returned to you from the Sign In request.

Sign Out

Very simple; just pass your token back.

Send Order

This initiates an order. You will follow this with a Confirm Order, Deny Order, Cancel Order or First Purchase Verify request. You can send a split subtotal and tax, or just the total alone if you already track your sales tax yourself. The Product ID is the code that the cashier gets from scanning the customer's barcode, either on their smartphone or on a separate card. Although the Product ID is all digits, you should enclose it in quotes for json because it can get longer than certain implementations can work with.

The total and productid attributes are mandatory. Some additional attributes you can send with Send Order:

• description - should describe the purchase - a guess, or a boilerplate, of what was purchased or what the transaction was all about. Default is 'Unspecified Product'.
• reference - Use this to store your internal transaction number in our databases, so that you can retrieve the data later. Default is the empty string.
• simulatefirstpurchase - for testing only, sending this as 1 will force the server to return 'Inactive' as the contact status, which should get your client to do a First Purchase Verify. Do not use for production.
• tax and subtotal - include both of these to break out the sales tax, otherwise include neither.
• photosize - The best photo sizes to use are extra large 'xl' (640 pixels square), large 'l' (ell, 360 square) or medium 'm' (168 square).

You get a large chunk of data back called the buyer tree. It has enough information so that you can display the customer's photo and option buttons for each possible entity the customer wants to charge it to. If the status is 'Inactive', you must then proceed on to the First Purchase Verify request, otherwise just confirm or deny the order. This buyer tree has three legs:

First Purchase Verify

You only need to do this if this purchase is the first for your customer on the Product system. You can tell because the status in the contact leg of the buyer tree says 'Inactive'. Really, anybody can upload any photo to our website; we need the cashier's help to make sure their face, their photo and their driver's license agree. You must write code to go through this procedure because a customer's first purchase could be anywhere.

The screen should show the person's face, from the image branch of the buyer tree. It should also show four option buttons that the cashier must press to continue:

• Three display different driver's licenses from the buyer tree > contact > driversLicenseNumbers.
• One that says 'none'; the cashier presses this only if there is no match (either one of the faces, or the driver's license).

Your cashier must do the following:

• Ask for the person's driver's license.
• Compare the person's face with the picture on their driver's license.
• Compare the person's face with the picture that you must be displaying on the screen (the image url).
• Compare the face on the screen with the picture on their driver's license. (yes, all three comparisons.)
• Look at the license number on the customer's driver's license, and press the appropriate option on the screen.

Confirm Order

If the face matches the photo, send the Confirm Order request. The transaction from the most recent Send Order will then be processed. You must pass the entityid from the entities branch of the buyer tree for the entity to be charged. If there is no Confirm Order request, or if a Send Order request goes through before then, the transaction is not stored, effectively denying and canceling the order. After this request, there is no transaction attached to this token, and so you must do a Send Order again to restart the process.

An argument not shown here is the clerkid, which is just a character string identifying which clerk or waiter finished the transaction. We can keep tips from customers collected by clerkid, so you can pay them later according to the exact tips each received. In addition, ths adds a layer of accountability to your clerks' work.

The reply contains the total price to be collected from the customer, and a count of all of the items ordered. It also contains the orderid and paymentid, which you can use to retrieve the information later (not implemented as of this writing).

Deny Order

If the face doesn't match the photo, send the Deny Order request. After this request, there is no transaction attached to this token, and so a Send Order must be done again to restart the process. Denied orders are not kept on our servers and the information is lost forever. In addition, the customer is marked for a Product security review. This should only be used for situations with serious suspicion. The cashier can say whatever they want.

Cancel Order

If, at the last minute, you need to abort an order, send the Cancel Order request. After this request, there is no transaction attached to this token, and so a Send Order must be done again to restart the process. Canceled orders are not kept on our servers and the information is lost forever. There is no harm in canceling an order other than the need to reenter data. To cancel an order with prejudice against the customer, use Deny Order.

PHP

Here is PHP code that does a Product request:

$http = curl_init("https://api.product.com/orders/json.php");
curl_setopt_array($http, array(
	CURLOPT_POST => true, 
	CURLOPT_RETURNTRANSFER => true,
	CURLOPT_POSTFIELDS => '{"action": "confirmOrder", 
		"apitoken": "tUqdoOUEmV1loFtdIzqE5kfoTFbrHhuM", "entityid": 62201}',
	CURLOPT_HTTPHEADER => array('Content-Type' => 'application/json'),
));
$result = curl_exec($http);
echo "<br>------ data returned: -----------<br>";
echo $result;
echo "<br>-------<br>";
curl_close($http);