CRM/Core/Payment/Elavon.php

   1 <?php
   2 /*
   3  +----------------------------------------------------------------------------+
   4  | Elavon (Nova) Virtual Merchant Core Payment Module for CiviCRM version 4.4 |
   5  +----------------------------------------------------------------------------+
   6  | Licensed to CiviCRM under the Academic Free License version 3.0            |
   7  |                                                                            |
   8  | Written & Contributed by Eileen McNaughton - Nov March 2008                |
   9  +----------------------------------------------------------------------------+
  10 */
  11
  12 /**
  13  -----------------------------------------------------------------------------------------------
  14  The basic functionality of this processor is that variables from the $params object are transformed
  15  into xml. The xml is submitted to the processor's https site
  16  using curl and the response is translated back into an array using the processor's function.
  17
  18  If an array ($params) is returned to the calling function the values from
  19  the array are merged into the calling functions array.
  20
  21  If an result of class error is returned it is treated as a failure. No error denotes a success. Be
  22  WARY of this when coding
  23
  24  -----------------------------------------------------------------------------------------------
  25  **/
  26 class CRM_Core_Payment_Elavon extends CRM_Core_Payment {
  27   // (not used, implicit in the API, might need to convert?)
  28   CONST
  29   CHARSET = 'UFT-8';
  30
  31   /**
  32    * We only need one instance of this object. So we use the singleton
  33    * pattern and cache the instance in this variable
  34    *
  35    * @var object
  36    * @static
  37    */
  38   static private $_singleton = NULL;
  39
  40   /**********************************************************
  41    * Constructor
  42    *
  43    * @param string $mode the mode of operation: live or test
  44    *
  45    * @return void
  46    **********************************************************/ function __construct($mode, &$paymentProcessor) {
  47     // live or test
  48     $this->_mode = $mode;
  49     $this->_paymentProcessor = $paymentProcessor;
  50     $this->_processorName = ts('Elavon');
  51   }
  52
  53   /**
  54    * singleton function used to manage this object
  55    *
  56    * @param string $mode the mode of operation: live or test
  57    *
  58    * @return object
  59    * @static
  60    *
  61    */
  62   static function &singleton($mode, &$paymentProcessor) {
  63     $processorName = $paymentProcessor['name'];
  64     if (self::$_singleton[$processorName] === NULL) {
  65       self::$_singleton[$processorName] = new CRM_Core_Payment_Elavon($mode, $paymentProcessor);
  66     }
  67     return self::$_singleton[$processorName];
  68   }
  69
  70   /**********************************************************
  71    * This function is set up and put here to make the mapping of fields
  72    * from the params object  as visually clear as possible for easy editing
  73    *
  74    *  Comment out irrelevant fields
  75    **********************************************************/
  76   function mapProcessorFieldstoParams($params) {
  77
  78     /**********************************************************
  79      * compile array
  80      * Payment Processor field name fields from $params array
  81      **********************************************************/
  82     // credit card name
  83     $requestFields['ssl_first_name'] = $params['billing_first_name'];
  84     // credit card name
  85     //$requestFields['ssl_middle_name']       = $params['billing_middle_name'];
  86     // credit card name
  87     $requestFields['ssl_last_name'] = $params['billing_last_name'];
  88     // contact name
  89     $requestFields['ssl_ship_to_first_name'] = $params['first_name'];
  90     // contact name
  91     $requestFields['ssl_ship_to_last_name'] = $params['last_name'];
  92     $requestFields['ssl_card_number'] = $params['credit_card_number'];
  93     $requestFields['ssl_amount'] = trim($params['amount']);
  94     $requestFields['ssl_exp_date'] = sprintf('%02d', (int) $params['month']) . substr($params['year'], 2, 2);;
  95     $requestFields['ssl_cvv2cvc2'] = $params['cvv2'];
  96     // CVV field passed to processor
  97     $requestFields['ssl_cvv2cvc2_indicator'] = "1";
  98     $requestFields['ssl_avs_address'] = $params['street_address'];
  99     $requestFields['ssl_city'] = $params['city'];
 100     $requestFields['ssl_state'] = $params['state_province'];
 101     $requestFields['ssl_avs_zip'] = $params['postal_code'];
 102     $requestFields['ssl_country'] = $params['country'];
 103     $requestFields['ssl_email'] = $params['email'];
 104     // 32 character string
 105     $requestFields['ssl_invoice_number'] = $params['invoiceID'];
 106     $requestFields['ssl_transaction_type'] = "CCSALE";
 107     $requestFields['ssl_description'] = empty($params['description']) ? "backoffice payment" : $params['description'];
 108     $requestFields['ssl_customer_number'] = substr($params['credit_card_number'], -4);
 109     // Added two lines below to allow commercial cards to go through as per page 15 of Elavon developer guide
 110     $requestFields['ssl_customer_code'] = '1111';
 111     $requestFields['ssl_salestax'] = 0.0;
 112
 113
 114     /************************************************************************************
 115      *  Fields available from civiCRM not implemented for Elavon
 116      *
 117      *  $params['qfKey'];
 118      *  $params['amount_other'];
 119      *  $params['ip_address'];
 120      *  $params['contributionType_name'  ];
 121      *  $params['contributionPageID'];
 122      *  $params['contributionType_accounting_code'];
 123      *  $params['amount_level'];
 124      *  $params['credit_card_type'];
 125      ************************************************************************************/
 126     return $requestFields;
 127   }
 128
 129   /**********************************************************
 130    * This function sends request and receives response from
 131    * the processor
 132    **********************************************************/
 133   function doDirectPayment(&$params) {
 134     if (isset($params['is_recur']) && $params['is_recur'] == TRUE) {
 135       CRM_Core_Error::fatal(ts('Elavon - recurring payments not implemented'));
 136     }
 137
 138     if (!defined('CURLOPT_SSLCERT')) {
 139       CRM_Core_Error::fatal(ts('Elavon / Nova Virtual Merchant Gateway requires curl with SSL support'));
 140     }
 141
 142     /*
 143          *Create the array of variables to be sent to the processor from the $params array
 144          * passed into this function
 145          */
 146
 147     $requestFields = self::mapProcessorFieldstoParams($params);
 148
 149     /*
 150          * define variables for connecting with the gateway
 151          */
 152
 153     $requestFields['ssl_merchant_id'] = $this->_paymentProcessor['user_name'];
 154     $requestFields['ssl_user_id'] = $this->_paymentProcessor['password'];
 155     $requestFields['ssl_pin'] = $this->_paymentProcessor['signature'];
 156     $host = $this->_paymentProcessor['url_site'];
 157
 158     if ($this->_mode == "test") {
 159       $requestFields['ssl_test_mode'] = "TRUE";
 160     }
 161
 162     // Allow further manipulation of the arguments via custom hooks ..
 163     CRM_Utils_Hook::alterPaymentProcessorParams($this, $params, $requestFields);
 164
 165     /**********************************************************
 166      * Check to see if we have a duplicate before we send
 167      **********************************************************/
 168     if ($this->_checkDupe($params['invoiceID'])) {
 169       return self::errorExit(9003, 'It appears that this transaction is a duplicate.  Have you already submitted the form once?  If so there may have been a connection problem.  Check your email for a receipt.  If you do not receive a receipt within 2 hours you can try your transaction again.  If you continue to have problems please contact the site administrator.');
 170     }
 171
 172     /**********************************************************
 173      * Convert to XML using function below
 174      **********************************************************/
 175     $xml = self::buildXML($requestFields);
 176
 177     /**********************************************************
 178      * Send to the payment processor using cURL
 179      **********************************************************/
 180
 181     $chHost = $host . '?xmldata=' . $xml;
 182
 183     $ch = curl_init($chHost);
 184     if (!$ch) {
 185       return self::errorExit(9004, 'Could not initiate connection to payment gateway');
 186     }
 187
 188     curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, CRM_Core_BAO_Setting::getItem(CRM_Core_BAO_Setting::SYSTEM_PREFERENCES_NAME, 'verifySSL') ? 2 : 0);
 189     curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, CRM_Core_BAO_Setting::getItem(CRM_Core_BAO_Setting::SYSTEM_PREFERENCES_NAME, 'verifySSL'));
 190     // return the result on success, FALSE on failure
 191     curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
 192     curl_setopt($ch, CURLOPT_TIMEOUT, 36000);
 193     // set this for debugging -look for output in apache error log
 194     //curl_setopt ($ch,CURLOPT_VERBOSE,1 );
 195     // ensures any Location headers are followed
 196     curl_setopt($ch, CURLOPT_FOLLOWLOCATION, 1);
 197
 198     /**********************************************************
 199      * Send the data out over the wire
 200      **********************************************************/
 201     $responseData = curl_exec($ch);
 202
 203     /**********************************************************
 204      * See if we had a curl error - if so tell 'em and bail out
 205      *
 206      * NOTE: curl_error does not return a logical value (see its documentation), but
 207      *       a string, which is empty when there was no error.
 208      **********************************************************/
 209     if ((curl_errno($ch) > 0) || (strlen(curl_error($ch)) > 0)) {
 210       curl_close($ch);
 211       $errorNum = curl_errno($ch);
 212       $errorDesc = curl_error($ch);
 213
 214       // Paranoia - in the unlikley event that 'curl' errno fails
 215       if ($errorNum == 0)
 216       $errorNum = 9005;
 217
 218       // Paranoia - in the unlikley event that 'curl' error fails
 219       if (strlen($errorDesc) == 0)
 220       $errorDesc = "Connection to payment gateway failed";
 221       if ($errorNum = 60) {
 222         return self::errorExit($errorNum, "Curl error - " . $errorDesc . " Try this link for more information http://curl.haxx.se/docs/sslcerts.html");
 223       }
 224
 225       return self::errorExit($errorNum, "Curl error - " . $errorDesc . " your key is located at " . $key . " the url is " . $host . " xml is " . $requestxml . " processor response = " . $processorResponse);
 226     }
 227
 228     /**********************************************************
 229      * If null data returned - tell 'em and bail out
 230      *
 231      * NOTE: You will not necessarily get a string back, if the request failed for
 232      *       any reason, the return value will be the boolean false.
 233      **********************************************************/
 234     if (($responseData === FALSE) || (strlen($responseData) == 0)) {
 235       curl_close($ch);
 236       return self::errorExit(9006, "Error: Connection to payment gateway failed - no data returned.");
 237     }
 238
 239     /**********************************************************
 240      // If gateway returned no data - tell 'em and bail out
 241      **********************************************************/
 242     if (empty($responseData)) {
 243       curl_close($ch);
 244       return self::errorExit(9007, "Error: No data returned from payment gateway.");
 245     }
 246
 247     /**********************************************************
 248      // Success so far - close the curl and check the data
 249      **********************************************************/
 250     curl_close($ch);
 251
 252     /**********************************************************
 253      * Payment successfully sent to gateway - process the response now
 254      **********************************************************/
 255
 256     $processorResponse = self::decodeXMLResponse($responseData);
 257     /*success in test mode returns response "APPROVED"
 258          * test mode always returns trxn_id = 0
 259          * fix for CRM-2566
 260          **********************************************************/
 261
 262
 263     if ($processorResponse['errorCode']) {
 264       return self::errorExit(9010, "Error: [" . $processorResponse['errorCode'] . " " . $processorResponse['errorName'] . " " . $processorResponse['errorMessage'] . "] - from payment processor");
 265     }
 266     if ($processorResponse['ssl_result_message'] == "APPROVED") {
 267       if ($this->_mode == 'test') {
 268         $query             = "SELECT MAX(trxn_id) FROM civicrm_contribution WHERE trxn_id LIKE 'test%'";
 269         $p                 = array();
 270         $trxn_id           = strval(CRM_Core_Dao::singleValueQuery($query, $p));
 271         $trxn_id           = str_replace('test', '', $trxn_id);
 272         $trxn_id           = intval($trxn_id) + 1;
 273         $params['trxn_id'] = sprintf('test%08d', $trxn_id);
 274         return $params;
 275       }
 276       else {
 277         return self::errorExit(9099, "Error: [approval code related to test transaction but mode was " . $this->_mode);
 278       }
 279     }
 280
 281     // transaction failed, print the reason
 282     if ($processorResponse['ssl_result_message'] != "APPROVAL") {
 283       return self::errorExit(9009, "Error: [" . $processorResponse['ssl_result_message'] . " " . $processorResponse['ssl_result'] . "] - from payment processor");
 284     }
 285     else {
 286       /*
 287              * Success !
 288              */
 289
 290       if ($this->_mode == 'test') {}
 291       else {
 292         // 'trxn_id' is varchar(255) field. returned value is length 37
 293         $params['trxn_id'] = $processorResponse['ssl_txn_id'];
 294       }
 295
 296       $params['trxn_result_code'] = $processorResponse['ssl_approval_code'] . "-Cvv2:" . $processorResponse['ssl_cvv2_response'] . "-avs:" . $processorResponse['ssl_avs_response'];
 297
 298       return $params;
 299     }
 300   }
 301   // end function doDirectPayment
 302
 303   /**
 304    * Checks to see if invoice_id already exists in db
 305    *
 306    * @param  int     $invoiceId   The ID to check
 307    *
 308    * @return bool                  True if ID exists, else false
 309    */
 310   function _checkDupe($invoiceId) {
 311     $contribution = new CRM_Contribute_DAO_Contribution();
 312     $contribution->invoice_id = $invoiceId;
 313     return $contribution->find();
 314   }
 315
 316   /**************************************************
 317    * Produces error message and returns from class
 318    **************************************************/
 319   function &errorExit($errorCode = NULL, $errorMessage = NULL) {
 320     $e = CRM_Core_Error::singleton();
 321     if ($errorCode) {
 322       $e->push($errorCode, 0, NULL, $errorMessage);
 323     }
 324     else {
 325       $e->push(9000, 0, NULL, 'Unknown System Error.');
 326     }
 327     return $e;
 328   }
 329
 330   /**************************************************
 331    * NOTE: 'doTransferCheckout' not implemented
 332    **************************************************/
 333   function doTransferCheckout(&$params, $component) {
 334     CRM_Core_Error::fatal(ts('This function is not implemented'));
 335   }
 336
 337   /********************************************************************************************
 338    * This public function checks to see if we have the right processor config values set
 339    *
 340    * NOTE: Called by Events and Contribute to check config params are set prior to trying
 341    *  register any credit card details
 342    *
 343    * @param string $mode the mode we are operating in (live or test) - not used
 344    *
 345    * returns string $errorMsg if any errors found - null if OK
 346    *
 347    ********************************************************************************************/
 348   //  function checkConfig( $mode )          // CiviCRM V1.9 Declaration
 349   // CiviCRM V2.0 Declaration
 350   function checkConfig() {
 351     $errorMsg = array();
 352
 353     if (empty($this->_paymentProcessor['user_name'])) {
 354       $errorMsg[] = ' ' . ts('ssl_merchant_id is not set for this payment processor');
 355     }
 356
 357     if (empty($this->_paymentProcessor['url_site'])) {
 358       $errorMsg[] = ' ' . ts('URL is not set for this payment processor');
 359     }
 360
 361     if (!empty($errorMsg)) {
 362       return implode('<p>', $errorMsg);
 363     }
 364     else {
 365       return NULL;
 366     }
 367   }
 368   //end check config
 369   function buildXML($requestFields) {
 370     $xmlFieldLength['ssl_first_name'] = 15;
 371     // credit card name
 372     $xmlFieldLength['ssl_last_name'] = 15;
 373     // contact name
 374     $xmlFieldLength['ssl_ship_to_first_name'] = 15;
 375     // contact name
 376     $xmlFieldLength['ssl_ship_to_last_name'] = 15;
 377     $xmlFieldLength['ssl_card_number'] = 19;
 378     $xmlFieldLength['ssl_amount'] = 13;
 379     $xmlFieldLength['ssl_exp_date'] = 4;
 380     $xmlFieldLength['ssl_cvv2cvc2'] = 4;
 381     $xmlFieldLength['ssl_cvv2cvc2_indicator'] = 1;
 382     $xmlFieldLength['ssl_avs_address'] = 20;
 383     $xmlFieldLength['ssl_city'] = 20;
 384     $xmlFieldLength['ssl_state'] = 30;
 385     $xmlFieldLength['ssl_avs_zip'] = 9;
 386     $xmlFieldLength['ssl_country'] = 50;
 387     $xmlFieldLength['ssl_email'] = 100;
 388     // 32 character string
 389     $xmlFieldLength['ssl_invoice_number'] = 25;
 390     $xmlFieldLength['ssl_transaction_type'] = 20;
 391     $xmlFieldLength['ssl_description'] = 255;
 392     $xmlFieldLength['ssl_merchant_id'] = 15;
 393     $xmlFieldLength['ssl_user_id'] = 15;
 394     $xmlFieldLength['ssl_pin'] = 128;
 395     $xmlFieldLength['ssl_test_mode'] = 5;
 396     $xmlFieldLength['ssl_salestax'] = 10;
 397     $xmlFieldLength['ssl_customer_code'] = 17;
 398     $xmlFieldLength['ssl_customer_number'] = 25;
 399
 400     $xml = '<txn>';
 401     foreach ($requestFields as $key => $value) {
 402       $xml .= '<' . $key . '>' . self::tidyStringforXML($value, $xmlFieldLength[$key]) . '</' . $key . '>';
 403     }
 404     $xml .= '</txn>';
 405     return $xml;
 406   }
 407
 408   function tidyStringforXML($value, $fieldlength) {
 409     // the xml is posted to a url so must not contain spaces etc. It also needs to be cut off at a certain
 410     // length to match the processor's field length. The cut needs to be made after spaces etc are
 411     // transformed but must not include a partial transformed character e.g. %20 must be in or out not half-way
 412     $xmlString = substr(rawurlencode($value), 0, $fieldlength);
 413     $lastPercent = strrpos($xmlString, '%');
 414     if ($lastPercent > $fieldlength - 3) {
 415       $xmlString = substr($xmlString, 0, $lastPercent);
 416     }
 417     return $xmlString;
 418   }
 419
 420   /************************************************************************
 421    * Simple function to use in place of the 'simplexml_load_string' call.
 422    *
 423    * It returns the NodeValue for a given NodeName
 424    * or returns an empty string.
 425    ************************************************************************/
 426   function GetNodeValue($NodeName, &$strXML) {
 427     $OpeningNodeName = "<" . $NodeName . ">";
 428     $ClosingNodeName = "</" . $NodeName . ">";
 429
 430     $pos1 = stripos($strXML, $OpeningNodeName);
 431     $pos2 = stripos($strXML, $ClosingNodeName);
 432
 433     if (($pos1 === FALSE) || ($pos2 === FALSE)) {
 434
 435       return "";
 436
 437     }
 438
 439     $pos1 += strlen($OpeningNodeName);
 440     $len = $pos2 - $pos1;
 441
 442     $return = substr($strXML, $pos1, $len);
 443     // check out rtn values for debug
 444     // echo " $NodeName &nbsp &nbsp $return <br>";
 445     return ($return);
 446   }
 447
 448   function decodeXMLresponse($Xml) {
 449
 450     /**
 451      * $xtr = simplexml_load_string($Xml) or die ("Unable to load XML string!");
 452      **/
 453
 454     $processorResponse['ssl_result'] = self::GetNodeValue("ssl_result", $Xml);
 455     $processorResponse['ssl_result_message'] = self::GetNodeValue("ssl_result_message", $Xml);
 456     $processorResponse['ssl_txn_id'] = self::GetNodeValue("ssl_txn_id", $Xml);
 457     $processorResponse['ssl_cvv2_response'] = self::GetNodeValue("ssl_cvv2_response", $Xml);
 458     $processorResponse['ssl_avs_response'] = self::GetNodeValue("ssl_avs_response", $Xml);
 459     $processorResponse['ssl_approval_code'] = self::GetNodeValue("ssl_approval_code", $Xml);
 460     $processorResponse['errorCode'] = self::GetNodeValue("errorCode", $Xml);
 461     $processorResponse['errorName'] = self::GetNodeValue("errorName", $Xml);
 462     $processorResponse['errorMessage'] = self::GetNodeValue("errorMessage", $Xml);
 463
 464     return $processorResponse;
 465   }
 466 }
 467