Working With The Authorize.net Customer Information Manager (CIM), Part 1: Overview

Update, 2 April 2014: Clearly, I’m not going to follow up here. Instead, use the AuthorizeNet PHP SDK available at github.

I’m going to spend several posts discussing authorize.net’s Customer Information Manager, a Web service for storing and retrieving personally identifiable information about the people who place credit card orders on your Web site.

Today, I’m focusing solely on an overview of CIM: What it is, how it works, why it works that way, and approaches to integrating CIM into your custom storefront / ordering systems. In future posts, I will discuss actual implementation via PHP and MySQL; my intent is to use 2-3 posts to cover the process, but it may take more or less. My intent is to post every day, but there may be a delay of a day or two between posts.

(I’m uncertain on the number and timing of posts on this topic because I’ll be blogging about implementation as I implement CIM for the first time. And lest that gives you pause, I’ve extensively reviewed the documentation, tested the basics of using the service, and have over 10 years’ experience with PHP / XML / MySQL. And because I’m doing the actual implementation for pay, I will have extensively tested the solution for elegance, reliability and security.)

What Is A Web Service?

The Customer Information Manager is a Web service. In its most common implementation on the World Wide Web, you send a Web service an XML document describing information you want, and the service responds with an XML document that contains the information you requested. (Not all Web services work this way; there are many kinds of Web services out there. But rather than bog down the point, let’s stick with this basic description.)

We can therefore think of a Web service as a remote database; the Customer Information Manager Web service is, in fact, a way to get data into and out of a remote database.

In the case of a Web service, rather than connecting to a local database, writing a SQL query and asking it to send us a result set (or Boolean false on failure), such as we would do in PHP / MySQL, we instead write an XML document that provides our authentication credentials and describes the data we want, send that to the CIM Web service via cUrl (or, if your server allows it, fopen), and get back from the CIM an XML document that contains the records we want (or an error code describing any problems encountered).

In other words, for most intents and purposes, the CIM Web service works exactly like a database, only different. So why in the world does authorize.net bother with a Web service, rather than simply giving you access to their database directly?

In a word, security. The primary benefit in providing the Customer Information Manager as a Web service is that it acts as an abstraction, and a fairly limited one at that.

What I mean is, if you had the ability to run any old UPDATE or DELETE query you wanted to run on the Customer Information Manager, you’d be able to do some serious damage, even if you only messed up your own records. (Everyone who has worked with SQL queries for more than a week has totally annihilated database tables with ill-considered UPDATE or DELETE queries.)

The Customer Information Manager APIs (application programming interfaces) allow authorize.net to restrict your activities to some basic tasks; namely, creating new customer database entries (“profiles”), deleting them one at a time; updating them one at a time; or getting a list of profile IDs.

The other benefit to the CIM Web service approach is, by only accepting XML requests and sending back XML in response, authorize.net can impose several levels of protection between the database and you. We don’t know, for example, what database holds our information; we can’t try to hack root; authorize.net is able to insert several layers of intrusion detection / firewall / load balancing between the XML we see and the database we can’t see.

Why Bother With CIM?

The primary reason to work with the Customer Information Manager is that it fully complies with the Payment Card Industry (PCI) Data Security Standard (DSS). Having a secure payment gateway to process online credit cards is one thing; being able to protect the credit card numbers you collect, as well as personally identifiable information about cardholders, is another.

Generally speaking, accepting a payment isn’t of any use in and of itself; in exchange for the money you receive, you usually need to provide some good or service, and in order to do that, you usually need the name and / or address of the person sending you money, if not details about what the customer wants, too.

The DSS doesn’t have Draconian requirements, but you probably can’t ensure those requirements are met on a shared Web hosting account. Or, even if you aren’t on shared hosting, you might want to absolve yourself of the responsibility of complying with DSS. That’s the primary business reason for using CIM.

CIM can also help you work with returning customers or recurring payments. Thanks to its object model, you can associate multiple credit cards and addresses with a given customer (both billing and shipping). In my application, the client sells subscriptions; often, subscribers not only order for themselves, but also for others (e.g., gift subscriptions); some subscribers also want to be auto-rebilled at the end of every subscription term.

Using the Customer Information Manager will allow my client to not only quickly relate each customer to all the subscriptions he has purchased, it will make rebilling as simple as asking the server to round up all rebill clients set for a given date, get their billing information and credit card from CIM, and batch submit them. (I won’t cover this last bit immediately, as my client wants to hold off on the rebilling part until he sees how successful online sales prove.)

So what that boils down to is, I can completely ignore AIM — the API most authorize.net developers know, and which is most commonly used to process transactions through authorize.net — in favor of CIM.

What CIM Is Not

As I describe what the Customer Information Manager can do, I should take a moment to address the things CIM does not do.

The APIs for CIM and AIM are not integrated and do not use the same methodologies. AIM — the authorize.net API that allows you to get money from credit cards — accepts POSTed form variables from your request and sends a delimited string back as a response. CIM is a Web service; it accepts and returns XML.

This isn’t a problem if you use CIM to handle all aspects of your online payments; you just cut out AIM altogether, as I plan to do.

However, some situations — such as sites using third-party e-commerce programs (e.g., Zen Cart or osCommerce), or custom software integrated with AIM that cannot be easily modified to use CIM — call for using CIM to only hold customer data. If you fall into the group that needs to use both CIM and AIM, most of what I discuss in upcoming posts will be of value, but keep in mind that CIM and AIM don’t work the same way.

While CIM stores lots of customer information, it isn’t extensible, nor is it very flexible. Again, you can associate multiple credit cards and billing / shipping addresses with each customer profile. But if you want to store additional information about a customer, you’re out of luck. CIM gives you 20-character “refId” and “merchantCustomerId” fields, as well as a 255-character “description” field, for each customer.

We can store information about individual transactions made by each customer profile, too. In other words, not only can each customer profile have multiple credit cards and addresses associated with it, but we can also record basic information about items purchased by the customer — such as item IDs, quantities and descriptions — for each order the customer places.

Even so, this may not be enough flexibility for your application. Technically speaking, you can store some information about a customer on your local server, and so long as it is not personally identifiable, you’ll still comply with DSS requirements.

For example, if you keep a small memo field on your local server that uses no names, addresses, phone numbers, etc. that can be used to identify the customer, you can simply key that memo field to the CIM customer profile ID and still be in compliance with DSS (as there is no local correlation to the customer’s personal information and the memo you are keeping). To ensure compliance with DSS, you might want to consider using a hash / encryption scheme to obfuscate the CIM customer ID key.

The Methodology I’ll Use

I am going to take a fairly pragmatic and direct approach to the application I write. That is, I’m going to keep it simple and direct.

My initial intent was to create a series of classes that represent the objects in the Customer Information Manager API. I actually got as far as defining all the objects’ properties and a significant number of the methods needed, before I decided it was consuming too much time and becoming a $1,000 solution to a 37-cent problem.

So, I’m simply going to use PHP 5, a little MySQL, and DomDocument to integrate the XML API for the Customer Information Manager. I’ll use cUrl to send requests.

I could have used the SOAP API. However, at least in the CIM API implementation, SOAP is fundamentally XML, only with the side aggravation of namespaces. Since that’s the case, and since I believe most readers of this blog will understand XML better than SOAP, that’s the way I will go.

5 thoughts on “Working With The Authorize.net Customer Information Manager (CIM), Part 1: Overview

  1. Doug Vanderweide

    My extensive apologies for not having followed up as promised. I have a boatload of excuses, none of which make any difference to people who are expecting me to get around to delivering as promised.

    And it turns out I won’t be delivering what I advertised: I will be providing a series of classes. I’ve got a working model but it needs significant cleaning before it’s ready for distribution. Expect it to come sometime next week; I’m fairly certain that’s when I will have it ready.

    I’m also debating whether to put the solution on SourceForge or to provide it here. Probably I’ll start with it here and then go the SourceForge route if it turns out to be very popular.

  2. Anu

    Hello,
    I have developed my Solution using SIM + ARB … now i want to use CIM to store Customers Credit card information which ill be using in ARB Creation … but im not able to retrive Actual Credit card number stored in CIM which returns in XXXX format … Is there any solution to retrive it ?

    Thanks & Regards,
    Anu

Leave a Reply