topic Basic CIM questions in Integration and Testing

Basic CIM questions

sneakyimp — Sun, 04 Mar 2012 21:16:49 GMT

I've been reading some of the other posts here on the forum regarding CIM but still have some questions:

1) Am I correct in thinking that I should have only one CustomerProfile for each for each of my customers? Does the authorize.net system prevent me from using a single merchantCustomerID more than once? There was a post on here that referred to a duplicate profile error returned by the authorize.net API but I have seen no information to tell me under what circumstances that would occur.

2) Is a credit card or bank account number required when creating a CustomerProfile? The CIM documentation neglects to explicitly specify if this information is required, optional, or conditional.

3) Is it possible to look up an authorize.net customer profile using merchantCustomerId? Looking at GetCustomerProfile, this does not appear to the case.

4) While I find the PDF documentation for CIM linked here to be pretty useful, it is pretty narrowly focused on the inputs and outputs of the API. Is there a more general source of documentation to show the ins and outs of CIM -- perhaps an overview or tutorial-based documentation?

5) What is the difference between SOAP and XML guides? If I'm using the PHP code provided by authorize.net, do I even care? From what I can tell, there is no way for me to specify whether I use SOAP or XML.

6) Where does one specify the web service location when setting up one's PHP code? The documentation refers to Production, Test, and WSDL variants without describing why one would choose one or the other. Additionally, all urls contain 'soap' in them, suggesting they might be inappropriate for an XML implementation.

7) In some of the AIM code examples, I see definition of such constants as AUTHORIZENET_API_LOGIN_ID, AUTHORIZENET_TRANSACTION_KEY, and AUTHORIZENET_SANDBOX. Is defining these in one's own code the proper approach to configuring the authorize.net PHP code? Are there other such constants? Where is this configuration documented?

Re: Basic CIM questions

TJPride — Sun, 04 Mar 2012 22:22:38 GMT

1) Depends on how you set up your system. If you have users on your site and associate a customer ID with each user as you create it, then obviously you don't have to worry about duplicate profiles unless the user signs up more than once. If you don't have user profiles, then you might have more than one customer profile per person depending on what info they put in. Shouldn't matter much from a payment perspective, however, since each instance of the person will work equally well so long as the billing info is good. Look in the pdf documentation for the words "Duplicate Profile Verification" and you'll get a list of fields that determine dupes.

2) No. You can create a profile with very little info - either an email, merchant customer ID, or description. Billing profiles can be assigned separately.

3) Not as far as I know. You should associate lookup values with profile ID's in your own database.

4) If you're using PHP, you can get a fairly good overview by looking at the CIM.markdown file in the doc folder of the SDK. Note that this is for regular CIM - if using hosted CIM to avoid PCI requirements, you'll need to look in the documentation to find out how to do that, or try to reverse-engineer the demo application.

5) No idea. I use the XML guide.

6) If you're using the PHP API, the URL's are set in the AuthorizeNetCim.php file in the lib folder. No need to mess with them, however, since the API chooses where to send the transaction depending on whether you set sandbox mode or not. I always set it at the class level, something like this (for a developer / sandbox account):

$request = new AuthorizeNetCIM;
$request->setSandbox(true);

Always use your account in live mode, incidently - test mode isn't as good at simulating things.

7) It's generally bad practice (in my opinion) to set those in the overall config. I always use a fresh, totally unconfigured SDK, and set things at the transaction level. To add to the above:

$request = new AuthorizeNetCIM(
    'login_id', 'transaction_key');
$request->setSandbox(true);

// or...

$request = new AuthorizeNetCIM(
    $GLOBALS['_login_id'], $GLOBALS['_transaction_key']);
$request->setSandbox(true);

// Where the globals are set in some master settings file for your site, separate from the SDK.

The best illustration of all the options is in the AIM.markdown file in your doc folder. It shows all the variants.

Re: Basic CIM questions

sneakyimp — Mon, 19 Mar 2012 04:51:55 GMT

OK thanks so much for the response! For some reason I was not notified.

I have made some progress. The markdown files are somewhat useful (and I've been reading some of the source) but I still wonder how certain things work. There are a few test cases I expect to deal with. NOTE that I am using CIM exclusively here via the PHP API:

1) A customer has no existing customer profile or payment profiles at authorize.net.

In this situation, I look at my records for a given user and there are *NO* id's stored for any customer profiles or payment profiles at authorize.net. I therefore need to create them both. I assume in this case that I can more or less construct a AuthorizeNetCustomer object with nested AuthorizeNetPaymentProfile (assigned like so: $customerProfile->paymentProfiles[] = $paymentProfile;) as detailed in the markdown file and then call the api thusly:

$request = new AuthorizeNetCIM(MY_API_LOGIN, MY_API_TRANSACTION_KEY);
$request->setSandbox(MY_SANDBOX_VALUE);
$request->setLogFile(MY_LOG_LOCATION);

$response = $request->createCustomerProfile($customerProfile);

Q1: What methods of the $response object are valid for this particular request? I see two different methods defined in the $response class for both getting a customer profile id and for getting a payment profile id:

            $response->getPaymentProfileId();
           $response->getCustomerPaymentProfileIds();
           $response->getCustomerProfileId();
           $response->getCustomerProfileIds();

2) Scenario 2 is where I have previously stored an authorizenet customer profile id in my system so I am guessing it's safe to assume this profile exists on the authorize.net system. I am guessing that I must take care in my code to use the different request createCustomerPaymentProfile and supply the customer profile id I had stored before. More questions come to mind

Q2: What would happen if I assembled a createCustomerProfile call just like I did in scenario 1. Would it cause an error? Or is authorize.net's gateway smart enough to know that I just want to attach a new payment profile to the existing customer profile?

Q3: Are there any circumstances under which authorize.net may have dropped a customer profile such that when I attempt createCustomerPaymentProfile there is an error? How would I know this had happened? The markdown documents don't show any error-handling examples.

Q4: Suppose a customer opted not to use an existing payment profile but instead wanted to enter a new card number but they mistakenly re-entered a cc number for which a payment profile already exists. Will that cause an error? Will the system permit an identical record?

Re: Basic CIM questions

sneakyimp — Mon, 19 Mar 2012 05:30:03 GMT

I'm also wondering a couple of other things:

* Can one re-use a $request object after performing some other function? E.g.:

// build $customerProfile object here

$response = $request->createCustomerProfile($customerProfile);

// build $transaction object here and re-use $reqest object

$response = $request->createCustomerProfileTransaction("AuthCapture", $transaction);

Does that work or must we create a new $request object?

* The examples I've seen in the markdown files don't show any error checking for profile and payment profile and transaction requests. Given that we're making a request via ssl across a network, it seems obvious that failure is a possibility for a variety of reasons. Where might I find some examples of best practices here? Do these functions throw exceptions when they fail? Is there an error condition we can check for after they complete to make sure they were successful? What about response codes for createCustomerProfileTransactionRequest? Does one use the same techniques shown in the AIM markdown?

$response = $request->createCustomerProfileTransaction("AuthCapture", $transaction);
$response->response_code;
$response->response_subcode;
$response->response_reason_code;
$response->transaction_id;

Re: Basic CIM questions

TJPride — Mon, 19 Mar 2012 07:29:16 GMT

Probably these:

$response->getCustomerProfileId();

$response->getCustomerPaymentProfileIds();

You could theoretically create the profile with more than one payment profile. There will, however, only ever be one customer profile in the response.

If you try to create a profile for a customer who already has a profile, you get CIM error E00039 and the duplicate profile ID is returned. Just use that. Figuring out what to do with the duplicate profile is a more complicated issue, since there will already be a payment entry and it may not be the same as the one the customer entered the second time.

Creating a profile can fail, just like any operation. Check for errors, proceed accordingly. Your best bet is to trigger some errors on purpose and do a print_r of the $response so you can see what you get back.

If you don't want to deal with the hassle of managing payment or shipping profiles, just implement hosted CIM for those. Essentially, you'd use iframe popups hosted by Authorize.net, then update your page once the user is done using them and use getCustomerProfile to populate pulldowns with masked card numbers and so on so the user can choose which payment profile to pay with.

Overall, your best strategy is probably to call things and print_r($response). That'll make most things fairly obvious.

Re: Basic CIM questions

sneakyimp — Fri, 23 Mar 2012 04:06:47 GMT

Thanks yet again for your helpful response.

Unfortunately, I have been using print_r to see the response and I see that an AuthorizeNetCIM_Response is what comes back and this object has 3 member variables:

* xml - SimpleXMLElement object

* response - a lengthy string that appears to contain the raw xml of the response

* xpath_xml - another, separate SimpleXMLElement object.

I'd prefer, if possible, to use the PHP code provided by authorize.net to parse these objects and extract the data I need rather than attempting some misguided effort at parsing XML myself or trying to navigate these objects. I'm shocked that not one of the markdown documents in the 'doc' folder for CIM's PHP library even bothers to mention the word 'error'.

I see that this call:

$response = $request->createCustomerProfile($customerProfile);

returns a response object where I can do the following:

echo $response->getResultCode()

* returns 'Ok' for successful attempt.

* returns 'Error' for unsuccessful attempt?

I find it surprising that the possible results of this function are not documented in the PHP source. One must go to the raw API document to find it. Having looked at the PHP source, the functions $response->isOK() and $response->isError() just check $response->getResultCode() to see if it is Ok or Error, respectively.

$response->getCustomerProfileId();

* returns the authorize.net ID for the newly created profile as a string rather than a numeric value.

* populated on error?? not specified.

$response->getCustomerPaymentProfileIds();

* although the name implies an array or collection of some kind, this also seems to return a single string containing the authorize.net id for a customer payment profile

* returns ??? if more than one profile is created?

I've also tried to take the customer payment profile and create a transaction with it using more or less the same code in the markdown example:

        $transaction = new AuthorizeNetTransaction;
       $transaction->amount = MY_ANNUAL_SUBSCRIPTION_COST;
        $transaction->customerProfileId = $authorizenet_customer_profile_id;
       $transaction->customerPaymentProfileId = $authorizenet_payment_profile_id;

       $lineItem              = new AuthorizeNetLineItem;
       //$lineItem->itemId      = "4";
       $lineItem->name        = "Annual Subscription to example.com";
       $lineItem->description = "An annual subscription to allow enhanced activities on example.com";
       $lineItem->quantity    = "1";
       $lineItem->unitPrice   = MY_ANNUAL_SUBSCRIPTION_COST;

       $transaction->lineItems[] = $lineItem;

        $response = $request->createCustomerProfileTransaction("AuthCapture", $transaction);
        print_r($response);

The result is an another triple-xml object that appears to have an error:

[code] => E00003
[text] => The element 'lineItems' in namespace 'AnetApi/xml/v1/schema/AnetApiSchema.xsd' has invalid child element 'name' in namespace 'AnetApi/xml/v1/schema/AnetApiSchema.xsd'. List of possible elements expected: 'itemId' in namespace 'AnetApi/xml/v1/schema/AnetApiSchema.xsd'.

I don't understand why 'name' would cause a problem because it is explicitly mentioned in the api documentation and also used in the markdown examples.

Also, itemId is specified in the markdown examples but the documentation doesn't say what this is for -- is it a product id on my system? Is it only meaningful in the context of one transaction?

Any answers would be much appreciated. I'm making progress but have been dramatically slowed down by the ad-hoc nature of the documentation.

Re: Basic CIM questions

TJPride — Fri, 23 Mar 2012 06:41:47 GMT

The xml part of the response may be -named- xml, but should actually be nested arrays representing the xml after it's been parsed. I generally use that myself. Go ahead and do a print_r of your response, then view source on your page (so it nests properly) and copy and paste it here.

The profile ID obviously won't be populated unless one is created. I imagine you'll get an array back from getCustomerPaymentProfileIds() if there's more than one - just check the field type.

Item ID is just whatever internal product code you decide to supply. Authorize.net doesn't care what it is. The specific error you're getting is a bug having to do with the fields being out of order, probably because itemId is expected but not being included. Finding the specific line of code that causes that might be a bit difficult, though.

Re: Basic CIM questions

sneakyimp — Mon, 26 Mar 2012 00:09:54 GMT

Thank you so much.

OK I think I'm starting to feel somewhat comfortable with the idea of handling these transaction responses.

I'm moving on to actually completing transactions. My primary consideration is that I'd like to store details about each transaction on my system, but I am unsure what the nature of the responses are. For instance, there's a whole comprehensive list of properties defined in the class AuthorizeNetResponse but I have no idea what the data format of these items is or how I might define my database table to accommodate these data values. For example, what's the maximum length required for response_reason_text? The response to a createCustomerProfileTransaction call is apparently an object of type AuthorizeNetAIM_Response and I've checked the AIM documentation but this document doesn't seem to describe any data types or values for the response elements. Is there somewhere I can find out the data types/sizes for elements of a AuthorizeNetAIM_Response object (which inherits from AuthorizeNetResponse?

Also, how consistent can I expect the responses to be in data format? I see that the constructor function for AuthorizeNetAIM_Response accepts a $custom_fields parameter. I reckon that if I want a comprehensive archive of all my transaction responses, I'll need to just log a text file as the responses may have extra data depending on circumstances?

Re: Basic CIM questions

sneakyimp — Mon, 26 Mar 2012 00:56:26 GMT

Ah! I see the docs do record information about how lengthy these fields are. My mistake.

Still wondering how consistent gateway responses might be.

Re: Basic CIM questions

TJPride — Mon, 26 Mar 2012 01:25:36 GMT

The CIM XML documentation should give you a pretty good idea of what's coming back. See the Responses -> CIM Responses section and also the Response Codes section.

http://www.authorize.net/support/CIM_XML_guide.pdf

Personally, for logging purposes I just log print_r() output to a text file or to a TEXT field in my MySQL database (up to 65536 characters, variable-length). That way I don't really need to worry about what format the response is in.

Re: Basic CIM questions

sneakyimp — Wed, 28 Mar 2012 22:12:14 GMT

OK I finally have some transactions happening. Lots of trial and erorr involved.

The problem I'm having now is that a comma is a really poor choice for delimiter -- or there's something wrong with the gateway's response.

I see that a CIM response ALWAYS constructs a response using a comma as a delimiter:

class AuthorizeNetCIM_Response extends AuthorizeNetXMLResponse
{
    /**
     * @return AuthorizeNetAIM_Response
     */
    public function getTransactionResponse()
    {

        // NOTE THE SECOND PARAMETER IS A COMMA
        return new AuthorizeNetAIM_Response($this->_getElementContents("directResponse"), ",", "", array());
    }
...

}

It's my understanding that one must tell the gateway with the outgoing request what delimiter to use so that when the response arrives, it is using the correct delimiters. Is there some way to specify this using the PHP api? As we see i the code sample above, the comma appears to be hard-wired for parsing CIM transaction results.

Re: Basic CIM questions

TJPride — Thu, 29 Mar 2012 04:21:15 GMT

I think the results come back as XML, and you should be able to access the parsed XML rather than going through the functions. directResponse is only one of the returned elements. Try doing a print_r() and exploring the structure.

EDIT: And yes, you can go into your control panel and change the delimiter with Settings -> Transaction Response Settings -> Direct Response, then edit the functions for the new delimiter. However, this may affect other API's as well, so keep that in mind.

Re: Basic CIM questions

sneakyimp — Sun, 01 Apr 2012 23:46:34 GMT

I suspect I will need to modify the PHP library files in order to effectively get a non-comma delimiter working, which bums me out a bit. I'll probably call tech support and let them know that someone should fix that.

I truly appreciate your generous assistance here. I have another fairly critical question. I see that the gateway can return a response_code of 'held' and I'm wondering how to deal with a response like this. I'm guessing that this might result when I attempt a transaction pending some kind of approval, but I totally unsure how I am to be notified of the held funds being delivered/released at a later time.

Do I need to also configure some other page so that authorize.net might deliver asynchronous events to my system? I.e., something like a silent post form or something? Does authorize.net support asynchronous payment events with this PHP library?

Re: Basic CIM questions

Trevor — Tue, 03 Apr 2012 22:35:16 GMT

There is no specific functionality in the php SDK designed to let you change the delmiting character. However, it is possible to pass the x_delim_char variable within the extraOptions tag which is exposed by the SDK. In regards to your second question about asynchronous communication, this is not relevant to our CIM APIs.

Re: Basic CIM questions

sneakyimp — Tue, 03 Apr 2012 22:56:22 GMT

I believe that passing any $extraOptions via the PHP SDK would likely cause a failure when your PHP library tries to parse any results from the gateway because your PHP code has no means by which you could change the expected delimiter. As you can see in my post from 3/28 above, the method getTransactionResponse of the class AuthorizeNetCIM_Response has a hard-coded reference to the comma as a delimiter. This seems like a pretty simple fix and would be very nice to have as commas frequently appear on my data -- especially addresses.

As for the need for asynchronous notifications, I believe it IS relevant to your CIM APIS because I have instantiated an AuthorizeNETCIM object:

$request = new AuthorizeNetCIM(AUTHORIZENET_API_LOGIN_ID, AUTHORIZENET_TRANSACTION_KEY);

I have used that CIM object to create a transaction with a CIM customerProfile and customerPaymentProfile:

$response = $request->createCustomerProfileTransaction("AuthCapture", $transaction);

And when I extract the response of my CIM object:

$transactionResponse = $response->getTransactionResponse();

Then the response might yield a value of AuthorizeNetResponse::HELD.

If the result of this transaction is HELD, it is my guess that I will probably need to respond to some future event asynchronously, correct?

Re: Basic CIM questions

Trevor — Thu, 05 Apr 2012 21:02:09 GMT

Transactions that are "held" require a manual review by the merchant within their Authorize.Net account. There is no API notification whether these transactions are manually approved or declined at a later time. It is up to the merchant to make any necessary modificaiton in thier order management system or shopping cart after they have determined what action to take on the order.

Re: Basic CIM questions

sneakyimp — Sun, 15 Apr 2012 00:41:31 GMT

Thanks for the clarification, Trevor.

Another question. When i try to create a Customer Profile and the gateway returns error type E00039:

A duplicate record with ID 1234567 already exists

Is it safe for me to parse that error and use the other ID? Can anyone think of any reason why this might compromise security? Also, is the format of this error likely to change? If I plan to parse it and the text is changed, I could end up with the wrong id.

Re: Basic CIM questions

Trevor — Mon, 16 Apr 2012 22:03:44 GMT

This is a bit of an interesting question. Our general policy is not to make any guarantees about the precise text for responses, but obviously this response is unique. My expectation is that this this error text will never change, but there is always a possibility that changes to the API make a change unavoidable. I can tell you that we always try to avoid any changes to our existing API behavior and we announce changes in advance if they have a chance of breaking existing implementations.

With all of that being said, I cannot currently think of any reason that we would have a need to change this text.

Re: Basic CIM questions

sneakyimp — Tue, 24 Apr 2012 19:02:12 GMT

I'm pleased to report that I've made progress and am testing my form. I'm still wondering how to respond to circumstances where my locally stored profile data is in conflict with the information stored by the gateway. IN particular, these:

1) Local data has no payment profiles stored for a user but gateway returns "E00039 A duplicate customer payment profile already exists." The gateway doesn't tell us what the profile id is so we can't delete it or fetch it or use it.

2) Local data has a customerProfileId stored which the gateway doesn't recognize. I'm guessing I should wipe all of my customer profile data (and payment profile data) and try to re-create them but I'm worried about the duplicate profile and duplicate payment profile errors.

Re: Basic CIM questions

Trevor — Thu, 26 Apr 2012 21:57:08 GMT

When a "duplicate customer payment profile" message is returned, the simplest action is to run a "getCustomerProfileRequest" to update the list of payment profiles that you have on file for the customer. This should avoid any sync issues between your database and what is in Authorize.Net.