{"id":217,"date":"2010-02-08T12:18:47","date_gmt":"2010-02-08T16:18:47","guid":{"rendered":"http:\/\/www.johnconde.net\/blog\/?p=217"},"modified":"2012-03-18T15:51:18","modified_gmt":"2012-03-18T19:51:18","slug":"tutorial-integrate-the-authorize-net-cim-api-with-php","status":"publish","type":"post","link":"https:\/\/website-0f9bf4a4.hpx.ppi.temporary.site\/blog\/tutorial-integrate-the-authorize-net-cim-api-with-php\/","title":{"rendered":"Tutorial: Integrate the Authorize.Net CIM API with PHP"},"content":{"rendered":"

\n This tutorial has been deprecated. You should read the new tutorial, “Tutorial: Integrate All Authorize.Net XML APIs With One Universal PHP Class (AIM, ARB, CIM, Transaction Details)<\/a>” which offers new code for working with Authorize.Net’s XML APIs including sample code for every API call.\n<\/p>\n

Just like Authorize.Net’s Advanced Integration Method (AIM) API<\/acronym> and Automated Recurring Billing (ARB) APIs, working with their Customer Information Manager (CIM) API isn’t difficult if you have suitable code to work with. The sample code offered by Authorize.Net will demonstrate how to work with their API but is not production ready. As with their AIM<\/acronym> API<\/a> and ARB<\/acronym> API<\/a> I have created a class that abstracts their CIM<\/acronym> API into something easier to use and maintain.<\/p>\n

To follow this tutorial and integrate CIM API into your PHP website follow these steps:<\/p>\n

    \n
  1. If you don’t already have one sign up for a Authorize.Net Developer Account<\/a>. This will allow you to test your code without having an actual Authorize.Net account or incurring any processing fees.<\/li>\n
  2. Download the CIM Integration Guide<\/a> (for reference)<\/li>\n
  3. Download the PHP code for CIM<\/a><\/li>\n<\/ol>\n

    To begin you will need to include the class using PHP’s require()<\/code> function:<\/p>\n

    require('AuthnetCIM.class.php');<\/pre>\n
    As with any class\/object the first thing we need to do is instantiate it. Up to three parameters are accepted in the constructor with the first two being required. myapilogin<\/code> is the API login for the account. mYtRaNsaCTiOnKEy<\/code> is the transaction key generated in the Authorize.Net control panel (or assigned to you with your test account information). If you have an Authorize.Net developer account you can use it with this script by setting the third parameters to TRUE<\/code> (you may omit the third parameter if you are using this with the live server):<\/p>\n
    $payment = new AuthnetCIM('myapilogin', 'mYtRaNsaCTiOnKEy', true);<\/pre>\n
    There are quite a few things you can do through the CIM API all of which fall into one of three categories: createXXXXXXX, updateXXXXXX, and deleteXXXXXX where XXXXXXX is the request type (CustomerProfileRequest, CustomerPaymentProfileRequest, CustomerShippingAddressRequest, and CustomerProfileTransactionRequest). Since updating a profile is almost identical to creating a profile (you just call a updateXXXXXX instead of createXXXXXX) and deleting a profile is very straightforward this tutorial will focus solely on the creating of profiles and processing payments.<\/p>\n
    There can be as many as four API calls to create profiles and process a payment although only three are actually necessary. They are:<\/p>\n
      \n
    1. createCustomerProfile()<\/code> – Creates the customer’s payment profile which serves as their master record. There should be only one payment profile per customer.<\/li>\n
    2. createCustomerPaymentProfile()<\/code> – Creates a payment profile for a customer. There should be one of these for every credit card or checking account the customer wishes to use.<\/li>\n
    3. createCustomerShippingAddress()<\/code> – (Optional) Creates a shipping profile for a customer. There should be one of these for every shipping address the customer wishes to use.<\/li>\n
    4. createCustomerProfileTransaction()<\/code> – Processes a transaction for a customer.<\/li>\n<\/ol>\n
      Before we can process any payments for a customer we must create their main profile. There are two fields you should provide although I am going to show three since combined they serve a significant purpose. These three fields are important because if all three fields match another profile exactly<\/em>, meaning all three fields are identical between both profiles in every way, the profile will not<\/em> be created. If one of the fields is different, it doesn’t matter which one, the profile will be created.<\/p>\n
      To create customer profile you can use this code (naturally you can change the values passed to each parameter):<\/p>\n
      $cim->setParameter('email', 'fakeemail@example.com');\r\n$cim->setParameter('description', 'Profile for Joe Smith'); \/\/ Optional\r\n$cim->setParameter('merchantCustomerId', '123456789');\r\n$cim->createCustomerProfile();\r\n$profile_id = $cim->getProfileID();<\/pre>\n
      The first three lines set the necessary parameters for createCustomerProfile()<\/code> to function properly. email<\/code> is the customer email address, description<\/code> is a description of the profile, and merchantCustomerId<\/code> is your<\/em> customer ID number (e.g. one generated by your system). The fourth line calls the CIM API to create the customer profile. The fifth line retrieves the customer profile ID created by Authorize.Net. This number is important as it is required to process all CIM requests for this profile. This means you should store it along with any other data you store in your database for this customer.<\/p>\n
      Now that we have created our customer profile we need to create at least one payment profile to use to process their payments:<\/p>\n
      $cim->setParameter('customerProfileId', $profile_id);\r\n$cim->setParameter('billToFirstName', 'Joe');\r\n$cim->setParameter('billToLastName', 'Smith');\r\n$cim->setParameter('billToAddress', '123 Main Street');\r\n$cim->setParameter('billToCity', 'Townsville');\r\n$cim->setParameter('billToState', 'NJ');\r\n$cim->setParameter('billToZip', '12345');\r\n$cim->setParameter('billToCountry', 'US');\r\n$cim->setParameter('billToPhoneNumber', '800-555-1234');\r\n$cim->setParameter('billToFaxNumber', '800-555-2345');\r\n$cim->setParameter('cardNumber', '4111111111111111');\r\n$cim->setParameter('expirationDate', '2016-12');\r\n$cim->createCustomerPaymentProfile();\r\n$payment_profile_id = $cim->getPaymentProfileId();<\/pre>\n
      The first line refers to the profile we wish to attach this payment profile to. The next nine lines set the billing information for the user’s credit card including their billing address (i.e. the address they have on file with their credit card issuing bank). The next two lines set the credit card information for the payment profile. The last two lines call the CIM API to create the payment profile and retrieve its ID which should be stored in your database.<\/p>\n
      Now we can create our shipping profile:<\/p>\n
      $cim->setParameter('customerProfileId', $profile_id);\r\n$cim->setParameter('shipToFirstName', 'Joe');\r\n$cim->setParameter('shipToLastName', 'Smith');\r\n$cim->setParameter('shipToAddress', '123 Main Street');\r\n$cim->setParameter('shipToCity', 'Townsville');\r\n$cim->setParameter('shipToState', 'NJ');\r\n$cim->setParameter('shipToZip', '12345');\r\n$cim->setParameter('shipToCountry', 'US');\r\n$cim->setParameter('shipToPhoneNumber', '800-555-1234');\r\n$cim->setParameter('shipToFaxNumber', '800-555-2345');\r\n$cim->createCustomerShippingAddress();\r\n$shipping_profile_id = $cim->getCustomerAddressId();<\/pre>\n
      Since creating a shipping profile is nearly identical to creating a billing profile I won’t elaborate on it other then to say the names of the parameters are different and no payment information is provided.<\/p>\n
      The final step is to process a payment:<\/p>\n
      $cim->setParameter('amount', $purchase_amount);\r\n$cim->setParameter('customerProfileId', $profile_id);\r\n$cim->setParameter('customerPaymentProfileId', $payment_profile_id);\r\n$cim->setParameter('customerShippingAddressId', $shipping_profile_id);\r\n$cim->createCustomerProfileTransaction();\r\n$approval_code = $cim->getAuthCode();<\/pre>\n
      This is pretty straight forward. We start by setting the amount we wish to charge. Then we tell the CIM API which customer profile, payment profile, and shipping profile to use. Finally we use the CIM API to process the transaction and we retrieve the approval code.<\/p>\n
      The AuthnetCIM class takes advantage of exceptions which are new in PHP5. These are only generated when an “exceptional” event occurs. The only exceptional event that might occur when using this class is cURL may fail. This may be due to server, network, or user errors. To catch these exceptions and handle them use code similar to this:<\/p>\n
      try\r\n{\r\n    $cim = new AuthnetCIM('myapilogin', 'mYtRaNsaCTiOnKEy');\r\n    \/\/ Do more CIM stuff here\r\n}\r\ncatch (AuthnetCIMException $e)\r\n{\r\n    echo 'There was an error processing the transaction. Here is the error message: ';\r\n    echo $e->__toString();\r\n}<\/pre>\n
      Now that we have an idea of how to use CIM to create profiles and process transactions, let’s put it all together into one script to demonstrate how it all works together. This one has some minor changes and additions that should better demonstrate how to use the AuthnetCIM class and should also make tinkering with this code easier to do:<\/p>\n
      < ?php\r\n\/\/ Include AuthnetCIM class. Nothing works without it!\r\nrequire('AuthnetCIM.class.php');\r\n\r\n\/\/ Use try\/catch so if an exception is thrown we can catch it\r\n\/\/ and figure out what happened\r\ntry\r\n{\r\n    \/\/ Create AuthnetCIM object. Set third parameter to \"true\" for developer account\r\n    \/\/ or use the built in constant USE_DEVELOPMENT_SERVER for better readability.\r\n    $cim = new AuthnetCIM('myapilogin', 'mYtRaNsaCTiOnKEy',\r\n                                               AuthnetCIM::USE_DEVELOPMENT_SERVER);\r\n\r\n    \/\/ Step 1: create Customer Profile\r\n    \/\/\r\n    \/\/ Create unique fake email address, description, and customer ID\r\n    $email_address = 'user' . time() . '@domain.com';\r\n    $description   = 'Monthly Membership No. ' . md5(uniqid(rand(), true));\r\n    $customer_id   = substr(md5(uniqid(rand(), true)), 16, 16);\r\n\r\n    \/\/ Create the profile\r\n    $cim->setParameter('email', $email_address);\r\n    $cim->setParameter('description', $description);\r\n    $cim->setParameter('merchantCustomerId', $customer_id);\r\n    $cim->createCustomerProfile();\r\n\r\n    \/\/ Get the profile ID returned from the request\r\n    if ($cim->isSuccessful())\r\n    {\r\n        $profile_id = $cim->getProfileID();\r\n    }\r\n\r\n    \/\/ Print the results of the request\r\n    echo 'createCustomerProfileRequest Response Summary:<\/strong> ' .\r\n                                          $cim->getResponseSummary() . '';\r\n    echo 'Profile ID:<\/strong> ' . $profile_id . '\r\n\r\n';\r\n\r\n    \/\/ Step 2: create Payment Profile\r\n    \/\/\r\n    \/\/ Create fake user billing information\r\n    $b_first_name   = 'John';\r\n    $b_last_name    = 'Conde';\r\n    $b_address      = '123 Main Street';\r\n    $b_city         = 'Townsville';\r\n    $b_state        = 'NJ';\r\n    $b_zip          = '12345';\r\n    $b_country      = 'US';\r\n    $b_phone_number = '800-555-1234';\r\n    $b_fax_number   = '800-555-2345';\r\n    $credit_card    = '4111111111111111';\r\n    $expiration     = (date(\"Y\") + 1) . '-12';\r\n\r\n    \/\/ Create the Payment Profile\r\n    $cim->setParameter('customerProfileId', $profile_id);\r\n    $cim->setParameter('billToFirstName', $b_first_name);\r\n    $cim->setParameter('billToLastName', $b_last_name);\r\n    $cim->setParameter('billToAddress', $b_address);\r\n    $cim->setParameter('billToCity', $b_city);\r\n    $cim->setParameter('billToState', $b_state);\r\n    $cim->setParameter('billToZip', $b_zip);\r\n    $cim->setParameter('billToCountry', $b_country);\r\n    $cim->setParameter('billToPhoneNumber', $b_phone_number);\r\n    $cim->setParameter('billToFaxNumber', $b_fax_number);\r\n    $cim->setParameter('cardNumber', $credit_card);\r\n    $cim->setParameter('expirationDate', $expiration);\r\n    $cim->createCustomerPaymentProfile();\r\n\r\n    \/\/ Get the payment profile ID returned from the request\r\n    if ($cim->isSuccessful())\r\n    {\r\n        $payment_profile_id = $cim->getPaymentProfileId();\r\n    }\r\n\r\n    \/\/ Print the results of the request\r\n    echo 'createCustomerPaymentProfileRequest Response Summary:<\/strong> ' .\r\n                                              $cim->getResponseSummary() . '';\r\n    echo 'Payment Profile ID:<\/strong> ' . $payment_profile_id . '\r\n\r\n';\r\n\r\n    \/\/ Step 3: create Shipping Profile\r\n    \/\/\r\n    \/\/ Create fake user shipping information\r\n    $s_first_name   = 'John';\r\n    $s_last_name    = 'Conde';\r\n    $s_address      = '1001 Other Road';\r\n    $s_city         = 'Townsville';\r\n    $s_state        = 'NJ';\r\n    $s_zip          = '12345';\r\n    $s_country      = 'US';\r\n    $s_phone_number = '800-555-3456';\r\n    $s_fax_number   = '800-555-4567';\r\n\r\n    \/\/ Create the shipping profile\r\n    $cim->setParameter('customerProfileId', $profile_id);\r\n    $cim->setParameter('shipToFirstName', $s_first_name);\r\n    $cim->setParameter('shipToLastName', $s_last_name);\r\n    $cim->setParameter('shipToAddress', $s_address);\r\n    $cim->setParameter('shipToCity', $s_city);\r\n    $cim->setParameter('shipToState', $s_state);\r\n    $cim->setParameter('shipToZip', $s_zip);\r\n    $cim->setParameter('shipToCountry', $s_country);\r\n    $cim->setParameter('shipToPhoneNumber', $s_phone_number);\r\n    $cim->setParameter('shipToFaxNumber', $s_fax_number);\r\n    $cim->createCustomerShippingAddress();\r\n\r\n    \/\/ Get the payment profile ID returned from the request\r\n    if ($cim->isSuccessful())\r\n    {\r\n        $shipping_profile_id = $cim->getCustomerAddressId();\r\n    }\r\n\r\n    \/\/ Print the results of the request\r\n    echo 'createCustomerShippingAddressRequest Response Summary:<\/strong> ' .\r\n                                               $cim->getResponseSummary() . '';\r\n    echo 'Shipping Profile ID:<\/strong> ' . $shipping_profile_id . '\r\n\r\n';\r\n\r\n    \/\/ Step 4: Process a transaction\r\n    \/\/\r\n    \/\/ Create fake transaction information\r\n    $purchase_amount = '5.00';\r\n\r\n    \/\/ Process the transaction\r\n    $cim->setParameter('amount', $purchase_amount);\r\n    $cim->setParameter('customerProfileId', $profile_id);\r\n    $cim->setParameter('customerPaymentProfileId', $payment_profile_id);\r\n    $cim->setParameter('customerShippingAddressId', $shipping_profile_id);\r\n    $cim->setParameter('cardCode', '123');\r\n    $cim->setLineItem('12', 'test item', 'it lets you test stuff', '1', '1.00');\r\n    $cim->createCustomerProfileTransaction();\r\n\r\n    \/\/ Get the payment profile ID returned from the request\r\n    if ($cim->isSuccessful())\r\n    {\r\n        $approval_code = $cim->getAuthCode();\r\n    }\r\n\r\n    \/\/ Print the results of the request\r\n    echo 'createCustomerProfileTransactionRequest Response Summary:<\/strong> ' .\r\n                               $cim->getResponseSummary() . '';\r\n    echo 'Approval code:<\/strong> ' . $approval_code;\r\n}\r\ncatch (AuthnetCIMException $e)\r\n{\r\n    echo $e;\r\n    echo $cim;\r\n}\r\n?><\/pre>\n
      Obviously this code is just one part of a larger system of managing user data. But this should make interacting with the Authorize.Net CIM API much easier to do allowing you to focus more on your user experience then learning new APIs.<\/p>\n","protected":false},"excerpt":{"rendered":"
      This tutorial has been deprecated. You should read the new tutorial, “Tutorial: Integrate All Authorize.Net XML APIs With One Universal PHP Class (AIM, ARB, CIM, Transaction Details)” which offers new code for working with Authorize.Net’s XML APIs including sample code … Continue reading →<\/span><\/a><\/p>\n","protected":false},"author":2,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"_jetpack_newsletter_access":"","_jetpack_dont_email_post_to_subs":false,"_jetpack_newsletter_tier_id":0,"_jetpack_memberships_contains_paywalled_content":false,"_jetpack_memberships_contains_paid_content":false,"footnotes":"","jetpack_publicize_message":"","jetpack_publicize_feature_enabled":true,"jetpack_social_post_already_shared":false,"jetpack_social_options":{"image_generator_settings":{"template":"highway","default_image_id":0,"font":"","enabled":false},"version":2},"jetpack_post_was_ever_published":false},"categories":[16],"tags":[60,50],"class_list":["post-217","post","type-post","status-publish","format-standard","hentry","category-programming","tag-authorizenet","tag-php"],"jetpack_publicize_connections":[],"jetpack_featured_media_url":"","jetpack_shortlink":"https:\/\/wp.me\/pwpo4-3v","jetpack_sharing_enabled":true,"_links":{"self":[{"href":"https:\/\/website-0f9bf4a4.hpx.ppi.temporary.site\/blog\/wp-json\/wp\/v2\/posts\/217","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/website-0f9bf4a4.hpx.ppi.temporary.site\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/website-0f9bf4a4.hpx.ppi.temporary.site\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/website-0f9bf4a4.hpx.ppi.temporary.site\/blog\/wp-json\/wp\/v2\/users\/2"}],"replies":[{"embeddable":true,"href":"https:\/\/website-0f9bf4a4.hpx.ppi.temporary.site\/blog\/wp-json\/wp\/v2\/comments?post=217"}],"version-history":[{"count":12,"href":"https:\/\/website-0f9bf4a4.hpx.ppi.temporary.site\/blog\/wp-json\/wp\/v2\/posts\/217\/revisions"}],"predecessor-version":[{"id":243,"href":"https:\/\/website-0f9bf4a4.hpx.ppi.temporary.site\/blog\/wp-json\/wp\/v2\/posts\/217\/revisions\/243"}],"wp:attachment":[{"href":"https:\/\/website-0f9bf4a4.hpx.ppi.temporary.site\/blog\/wp-json\/wp\/v2\/media?parent=217"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/website-0f9bf4a4.hpx.ppi.temporary.site\/blog\/wp-json\/wp\/v2\/categories?post=217"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/website-0f9bf4a4.hpx.ppi.temporary.site\/blog\/wp-json\/wp\/v2\/tags?post=217"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}