1: <?php
   2: /**
   3:  * Magento
   4:  *
   5:  * NOTICE OF LICENSE
   6:  *
   7:  * This source file is subject to the Open Software License (OSL 3.0)
   8:  * that is bundled with this package in the file LICENSE.txt.
   9:  * It is also available through the world-wide-web at this URL:
  10:  * http://opensource.org/licenses/osl-3.0.php
  11:  * If you did not receive a copy of the license and are unable to
  12:  * obtain it through the world-wide-web, please send an email
  13:  * to license@magentocommerce.com so we can send you a copy immediately.
  14:  *
  15:  * DISCLAIMER
  16:  *
  17:  * Do not edit or add to this file if you wish to upgrade Magento to newer
  18:  * versions in the future. If you wish to customize Magento for your
  19:  * needs please refer to http://www.magentocommerce.com for more information.
  20:  *
  21:  * @category    Mage
  22:  * @package     Mage_Sales
  23:  * @copyright   Copyright (c) 2012 Magento Inc. (http://www.magentocommerce.com)
  24:  * @license     http://opensource.org/licenses/osl-3.0.php  Open Software License (OSL 3.0)
  25:  */
  26: 
  27: /**
  28:  * Order payment information
  29:  *
  30:  * @method Mage_Sales_Model_Resource_Order_Payment _getResource()
  31:  * @method Mage_Sales_Model_Resource_Order_Payment getResource()
  32:  * @method int getParentId()
  33:  * @method Mage_Sales_Model_Order_Payment setParentId(int $value)
  34:  * @method float getBaseShippingCaptured()
  35:  * @method Mage_Sales_Model_Order_Payment setBaseShippingCaptured(float $value)
  36:  * @method float getShippingCaptured()
  37:  * @method Mage_Sales_Model_Order_Payment setShippingCaptured(float $value)
  38:  * @method float getAmountRefunded()
  39:  * @method Mage_Sales_Model_Order_Payment setAmountRefunded(float $value)
  40:  * @method float getBaseAmountPaid()
  41:  * @method Mage_Sales_Model_Order_Payment setBaseAmountPaid(float $value)
  42:  * @method float getAmountCanceled()
  43:  * @method Mage_Sales_Model_Order_Payment setAmountCanceled(float $value)
  44:  * @method float getBaseAmountAuthorized()
  45:  * @method Mage_Sales_Model_Order_Payment setBaseAmountAuthorized(float $value)
  46:  * @method float getBaseAmountPaidOnline()
  47:  * @method Mage_Sales_Model_Order_Payment setBaseAmountPaidOnline(float $value)
  48:  * @method float getBaseAmountRefundedOnline()
  49:  * @method Mage_Sales_Model_Order_Payment setBaseAmountRefundedOnline(float $value)
  50:  * @method float getBaseShippingAmount()
  51:  * @method Mage_Sales_Model_Order_Payment setBaseShippingAmount(float $value)
  52:  * @method float getShippingAmount()
  53:  * @method Mage_Sales_Model_Order_Payment setShippingAmount(float $value)
  54:  * @method float getAmountPaid()
  55:  * @method Mage_Sales_Model_Order_Payment setAmountPaid(float $value)
  56:  * @method float getAmountAuthorized()
  57:  * @method Mage_Sales_Model_Order_Payment setAmountAuthorized(float $value)
  58:  * @method float getBaseAmountOrdered()
  59:  * @method Mage_Sales_Model_Order_Payment setBaseAmountOrdered(float $value)
  60:  * @method float getBaseShippingRefunded()
  61:  * @method Mage_Sales_Model_Order_Payment setBaseShippingRefunded(float $value)
  62:  * @method float getShippingRefunded()
  63:  * @method Mage_Sales_Model_Order_Payment setShippingRefunded(float $value)
  64:  * @method float getBaseAmountRefunded()
  65:  * @method Mage_Sales_Model_Order_Payment setBaseAmountRefunded(float $value)
  66:  * @method float getAmountOrdered()
  67:  * @method Mage_Sales_Model_Order_Payment setAmountOrdered(float $value)
  68:  * @method float getBaseAmountCanceled()
  69:  * @method Mage_Sales_Model_Order_Payment setBaseAmountCanceled(float $value)
  70:  * @method int getIdealTransactionChecked()
  71:  * @method Mage_Sales_Model_Order_Payment setIdealTransactionChecked(int $value)
  72:  * @method int getQuotePaymentId()
  73:  * @method Mage_Sales_Model_Order_Payment setQuotePaymentId(int $value)
  74:  * @method string getAdditionalData()
  75:  * @method Mage_Sales_Model_Order_Payment setAdditionalData(string $value)
  76:  * @method string getCcExpMonth()
  77:  * @method Mage_Sales_Model_Order_Payment setCcExpMonth(string $value)
  78:  * @method string getCcSsStartYear()
  79:  * @method Mage_Sales_Model_Order_Payment setCcSsStartYear(string $value)
  80:  * @method string getEcheckBankName()
  81:  * @method Mage_Sales_Model_Order_Payment setEcheckBankName(string $value)
  82:  * @method string getMethod()
  83:  * @method Mage_Sales_Model_Order_Payment setMethod(string $value)
  84:  * @method string getCcDebugRequestBody()
  85:  * @method Mage_Sales_Model_Order_Payment setCcDebugRequestBody(string $value)
  86:  * @method string getCcSecureVerify()
  87:  * @method Mage_Sales_Model_Order_Payment setCcSecureVerify(string $value)
  88:  * @method string getCybersourceToken()
  89:  * @method Mage_Sales_Model_Order_Payment setCybersourceToken(string $value)
  90:  * @method string getIdealIssuerTitle()
  91:  * @method Mage_Sales_Model_Order_Payment setIdealIssuerTitle(string $value)
  92:  * @method string getProtectionEligibility()
  93:  * @method Mage_Sales_Model_Order_Payment setProtectionEligibility(string $value)
  94:  * @method string getCcApproval()
  95:  * @method Mage_Sales_Model_Order_Payment setCcApproval(string $value)
  96:  * @method string getCcLast4()
  97:  * @method Mage_Sales_Model_Order_Payment setCcLast4(string $value)
  98:  * @method string getCcStatusDescription()
  99:  * @method Mage_Sales_Model_Order_Payment setCcStatusDescription(string $value)
 100:  * @method string getEcheckType()
 101:  * @method Mage_Sales_Model_Order_Payment setEcheckType(string $value)
 102:  * @method string getPayboxQuestionNumber()
 103:  * @method Mage_Sales_Model_Order_Payment setPayboxQuestionNumber(string $value)
 104:  * @method string getCcDebugResponseSerialized()
 105:  * @method Mage_Sales_Model_Order_Payment setCcDebugResponseSerialized(string $value)
 106:  * @method string getCcSsStartMonth()
 107:  * @method Mage_Sales_Model_Order_Payment setCcSsStartMonth(string $value)
 108:  * @method string getEcheckAccountType()
 109:  * @method Mage_Sales_Model_Order_Payment setEcheckAccountType(string $value)
 110:  * @method string getLastTransId()
 111:  * @method Mage_Sales_Model_Order_Payment setLastTransId(string $value)
 112:  * @method string getCcCidStatus()
 113:  * @method Mage_Sales_Model_Order_Payment setCcCidStatus(string $value)
 114:  * @method string getCcOwner()
 115:  * @method Mage_Sales_Model_Order_Payment setCcOwner(string $value)
 116:  * @method string getCcType()
 117:  * @method Mage_Sales_Model_Order_Payment setCcType(string $value)
 118:  * @method string getIdealIssuerId()
 119:  * @method Mage_Sales_Model_Order_Payment setIdealIssuerId(string $value)
 120:  * @method string getPoNumber()
 121:  * @method Mage_Sales_Model_Order_Payment setPoNumber(string $value)
 122:  * @method string getCcExpYear()
 123:  * @method Mage_Sales_Model_Order_Payment setCcExpYear(string $value)
 124:  * @method string getCcStatus()
 125:  * @method Mage_Sales_Model_Order_Payment setCcStatus(string $value)
 126:  * @method string getEcheckRoutingNumber()
 127:  * @method Mage_Sales_Model_Order_Payment setEcheckRoutingNumber(string $value)
 128:  * @method string getAccountStatus()
 129:  * @method Mage_Sales_Model_Order_Payment setAccountStatus(string $value)
 130:  * @method string getAnetTransMethod()
 131:  * @method Mage_Sales_Model_Order_Payment setAnetTransMethod(string $value)
 132:  * @method string getCcDebugResponseBody()
 133:  * @method Mage_Sales_Model_Order_Payment setCcDebugResponseBody(string $value)
 134:  * @method string getCcSsIssue()
 135:  * @method Mage_Sales_Model_Order_Payment setCcSsIssue(string $value)
 136:  * @method string getEcheckAccountName()
 137:  * @method Mage_Sales_Model_Order_Payment setEcheckAccountName(string $value)
 138:  * @method string getCcAvsStatus()
 139:  * @method Mage_Sales_Model_Order_Payment setCcAvsStatus(string $value)
 140:  * @method string getCcNumberEnc()
 141:  * @method Mage_Sales_Model_Order_Payment setCcNumberEnc(string $value)
 142:  * @method string getCcTransId()
 143:  * @method Mage_Sales_Model_Order_Payment setCcTransId(string $value)
 144:  * @method string getFlo2cashAccountId()
 145:  * @method Mage_Sales_Model_Order_Payment setFlo2cashAccountId(string $value)
 146:  * @method string getPayboxRequestNumber()
 147:  * @method Mage_Sales_Model_Order_Payment setPayboxRequestNumber(string $value)
 148:  * @method string getAddressStatus()
 149:  * @method Mage_Sales_Model_Order_Payment setAddressStatus(string $value)
 150:  *
 151:  * @category    Mage
 152:  * @package     Mage_Sales
 153:  * @author      Magento Core Team <core@magentocommerce.com>
 154:  */
 155: class Mage_Sales_Model_Order_Payment extends Mage_Payment_Model_Info
 156: {
 157:     /**
 158:      * Actions for payment when it triggered review state
 159:      *
 160:      * @var string
 161:      */
 162:     const REVIEW_ACTION_ACCEPT = 'accept';
 163:     const REVIEW_ACTION_DENY   = 'deny';
 164:     const REVIEW_ACTION_UPDATE = 'update';
 165: 
 166:     /**
 167:      * Order model object
 168:      *
 169:      * @var Mage_Sales_Model_Order
 170:      */
 171:     protected $_order;
 172: 
 173:     /**
 174:      * Billing agreement instance that may be created during payment processing
 175:      *
 176:      * @var Mage_Sales_Model_Billing_Agreement
 177:      */
 178:     protected $_billingAgreement = null;
 179: 
 180:     /**
 181:      * Whether can void
 182:      * @var string
 183:      */
 184:     protected $_canVoidLookup = null;
 185: 
 186:     /**
 187:      * Transactions registry to spare resource calls
 188:      * array(txn_id => sales/order_payment_transaction)
 189:      * @var array
 190:      */
 191:     protected $_transactionsLookup = array();
 192: 
 193:     protected $_eventPrefix = 'sales_order_payment';
 194:     protected $_eventObject = 'payment';
 195: 
 196:     /**
 197:      * Transaction addditional information container
 198:      *
 199:      * @var array
 200:      */
 201:     protected $_transactionAdditionalInfo = array();
 202: 
 203:     /**
 204:      * Initialize resource model
 205:      */
 206:     protected function _construct()
 207:     {
 208:         $this->_init('sales/order_payment');
 209:     }
 210: 
 211:     /**
 212:      * Declare order model object
 213:      *
 214:      * @param   Mage_Sales_Model_Order $order
 215:      * @return  Mage_Sales_Model_Order_Payment
 216:      */
 217:     public function setOrder(Mage_Sales_Model_Order $order)
 218:     {
 219:         $this->_order = $order;
 220:         return $this;
 221:     }
 222: 
 223:     /**
 224:      * Retrieve order model object
 225:      *
 226:      * @return Mage_Sales_Model_Order
 227:      */
 228:     public function getOrder()
 229:     {
 230:         return $this->_order;
 231:     }
 232: 
 233:     /**
 234:      * Check order payment capture action availability
 235:      *
 236:      * @return bool
 237:      */
 238:     public function canCapture()
 239:     {
 240:         if (!$this->getMethodInstance()->canCapture()) {
 241:             return false;
 242:         }
 243:         // Check Authoriztion transaction state
 244:         $authTransaction = $this->getAuthorizationTransaction();
 245:         if ($authTransaction && $authTransaction->getIsClosed()) {
 246:             $orderTransaction = $this->_lookupTransaction(null, Mage_Sales_Model_Order_Payment_Transaction::TYPE_ORDER);
 247:             if (!$orderTransaction) {
 248:                 return false;
 249:             }
 250:         }
 251:         return true;
 252:     }
 253: 
 254:     public function canRefund()
 255:     {
 256:         return $this->getMethodInstance()->canRefund();
 257:     }
 258: 
 259:     public function canRefundPartialPerInvoice()
 260:     {
 261:         return $this->getMethodInstance()->canRefundPartialPerInvoice();
 262:     }
 263: 
 264:     public function canCapturePartial()
 265:     {
 266:         return $this->getMethodInstance()->canCapturePartial();
 267:     }
 268: 
 269:     /**
 270:      * Authorize or authorize and capture payment on gateway, if applicable
 271:      * This method is supposed to be called only when order is placed
 272:      *
 273:      * @return Mage_Sales_Model_Order_Payment
 274:      */
 275:     public function place()
 276:     {
 277:         Mage::dispatchEvent('sales_order_payment_place_start', array('payment' => $this));
 278:         $order = $this->getOrder();
 279: 
 280:         $this->setAmountOrdered($order->getTotalDue());
 281:         $this->setBaseAmountOrdered($order->getBaseTotalDue());
 282:         $this->setShippingAmount($order->getShippingAmount());
 283:         $this->setBaseShippingAmount($order->getBaseShippingAmount());
 284: 
 285:         $methodInstance = $this->getMethodInstance();
 286:         $methodInstance->setStore($order->getStoreId());
 287: 
 288:         $orderState = Mage_Sales_Model_Order::STATE_NEW;
 289:         $orderStatus= false;
 290: 
 291:         $stateObject = new Varien_Object();
 292: 
 293:         /**
 294:          * Do order payment validation on payment method level
 295:          */
 296:         $methodInstance->validate();
 297:         $action = $methodInstance->getConfigPaymentAction();
 298:         if ($action) {
 299:             if ($methodInstance->isInitializeNeeded()) {
 300:                 /**
 301:                  * For method initialization we have to use original config value for payment action
 302:                  */
 303:                 $methodInstance->initialize($methodInstance->getConfigData('payment_action'), $stateObject);
 304:             } else {
 305:                 $orderState = Mage_Sales_Model_Order::STATE_PROCESSING;
 306:                 switch ($action) {
 307:                     case Mage_Payment_Model_Method_Abstract::ACTION_ORDER:
 308:                         $this->_order($order->getBaseTotalDue());
 309:                         break;
 310:                     case Mage_Payment_Model_Method_Abstract::ACTION_AUTHORIZE:
 311:                         $this->_authorize(true, $order->getBaseTotalDue()); // base amount will be set inside
 312:                         $this->setAmountAuthorized($order->getTotalDue());
 313:                         break;
 314:                     case Mage_Payment_Model_Method_Abstract::ACTION_AUTHORIZE_CAPTURE:
 315:                         $this->setAmountAuthorized($order->getTotalDue());
 316:                         $this->setBaseAmountAuthorized($order->getBaseTotalDue());
 317:                         $this->capture(null);
 318:                         break;
 319:                     default:
 320:                         break;
 321:                 }
 322:             }
 323:         }
 324: 
 325:         $this->_createBillingAgreement();
 326: 
 327:         $orderIsNotified = null;
 328:         if ($stateObject->getState() && $stateObject->getStatus()) {
 329:             $orderState      = $stateObject->getState();
 330:             $orderStatus     = $stateObject->getStatus();
 331:             $orderIsNotified = $stateObject->getIsNotified();
 332:         } else {
 333:             $orderStatus = $methodInstance->getConfigData('order_status');
 334:             if (!$orderStatus) {
 335:                 $orderStatus = $order->getConfig()->getStateDefaultStatus($orderState);
 336:             }
 337:         }
 338:         $isCustomerNotified = (null !== $orderIsNotified) ? $orderIsNotified : $order->getCustomerNoteNotify();
 339:         $message = $order->getCustomerNote();
 340: 
 341:         // add message if order was put into review during authorization or capture
 342:         if ($order->getState() == Mage_Sales_Model_Order::STATE_PAYMENT_REVIEW) {
 343:             if ($message) {
 344:                 $order->addStatusToHistory($order->getStatus(), $message, $isCustomerNotified);
 345:             }
 346:         }
 347:         // add message to history if order state already declared
 348:         elseif ($order->getState() && ($orderStatus !== $order->getStatus() || $message)) {
 349:             $order->setState($orderState, $orderStatus, $message, $isCustomerNotified);
 350:         }
 351:         // set order state
 352:         elseif (($order->getState() != $orderState) || ($order->getStatus() != $orderStatus) || $message) {
 353:             $order->setState($orderState, $orderStatus, $message, $isCustomerNotified);
 354:         }
 355: 
 356:         Mage::dispatchEvent('sales_order_payment_place_end', array('payment' => $this));
 357: 
 358:         return $this;
 359:     }
 360: 
 361:     /**
 362:      * Capture the payment online
 363:      * Requires an invoice. If there is no invoice specified, will automatically prepare an invoice for order
 364:      * Updates transactions hierarchy, if required
 365:      * Updates payment totals, updates order status and adds proper comments
 366:      *
 367:      * TODO: eliminate logic duplication with registerCaptureNotification()
 368:      *
 369:      * @return Mage_Sales_Model_Order_Payment
 370:      * @throws Mage_Core_Exception
 371:      */
 372:     public function capture($invoice)
 373:     {
 374:         if (is_null($invoice)) {
 375:             $invoice = $this->_invoice();
 376:             $this->setCreatedInvoice($invoice);
 377:             return $this; // @see Mage_Sales_Model_Order_Invoice::capture()
 378:         }
 379:         $amountToCapture = $this->_formatAmount($invoice->getBaseGrandTotal());
 380:         $order = $this->getOrder();
 381: 
 382:         // prepare parent transaction and its amount
 383:         $paidWorkaround = 0;
 384:         if (!$invoice->wasPayCalled()) {
 385:             $paidWorkaround = (float)$amountToCapture;
 386:         }
 387:         $this->_isCaptureFinal($paidWorkaround);
 388: 
 389:         $this->_generateTransactionId(
 390:             Mage_Sales_Model_Order_Payment_Transaction::TYPE_CAPTURE,
 391:             $this->getAuthorizationTransaction()
 392:         );
 393: 
 394:         Mage::dispatchEvent('sales_order_payment_capture', array('payment' => $this, 'invoice' => $invoice));
 395: 
 396:         /**
 397:          * Fetch an update about existing transaction. It can determine whether the transaction can be paid
 398:          * Capture attempt will happen only when invoice is not yet paid and the transaction can be paid
 399:          */
 400:         if ($invoice->getTransactionId()) {
 401:             $this->getMethodInstance()
 402:                 ->setStore($order->getStoreId())
 403:                 ->fetchTransactionInfo($this, $invoice->getTransactionId());
 404:         }
 405:         $status = true;
 406:         if (!$invoice->getIsPaid() && !$this->getIsTransactionPending()) {
 407:             // attempt to capture: this can trigger "is_transaction_pending"
 408:             $this->getMethodInstance()->setStore($order->getStoreId())->capture($this, $amountToCapture);
 409: 
 410:             $transaction = $this->_addTransaction(
 411:                 Mage_Sales_Model_Order_Payment_Transaction::TYPE_CAPTURE,
 412:                 $invoice,
 413:                 true
 414:             );
 415: 
 416:             if ($this->getIsTransactionPending()) {
 417:                 $message = Mage::helper('sales')->__('Capturing amount of %s is pending approval on gateway.', $this->_formatPrice($amountToCapture));
 418:                 $state = Mage_Sales_Model_Order::STATE_PAYMENT_REVIEW;
 419:                 if ($this->getIsFraudDetected()) {
 420:                     $status = Mage_Sales_Model_Order::STATUS_FRAUD;
 421:                 }
 422:                 $invoice->setIsPaid(false);
 423:             } else { // normal online capture: invoice is marked as "paid"
 424:                 $message = Mage::helper('sales')->__('Captured amount of %s online.', $this->_formatPrice($amountToCapture));
 425:                 $state = Mage_Sales_Model_Order::STATE_PROCESSING;
 426:                 $invoice->setIsPaid(true);
 427:                 $this->_updateTotals(array('base_amount_paid_online' => $amountToCapture));
 428:             }
 429:             if ($order->isNominal()) {
 430:                 $message = $this->_prependMessage(Mage::helper('sales')->__('Nominal order registered.'));
 431:             } else {
 432:                 $message = $this->_prependMessage($message);
 433:                 $message = $this->_appendTransactionToMessage($transaction, $message);
 434:             }
 435:             $order->setState($state, $status, $message);
 436:             $this->getMethodInstance()->processInvoice($invoice, $this); // should be deprecated
 437:             return $this;
 438:         }
 439:         Mage::throwException(
 440:             Mage::helper('sales')->__('The transaction "%s" cannot be captured yet.', $invoice->getTransactionId())
 441:         );
 442:     }
 443: 
 444:     /**
 445:      * Process a capture notification from a payment gateway for specified amount
 446:      * Creates an invoice automatically if the amount covers the order base grand total completely
 447:      * Updates transactions hierarchy, if required
 448:      * Prevents transaction double processing
 449:      * Updates payment totals, updates order status and adds proper comments
 450:      *
 451:      * TODO: eliminate logic duplication with capture()
 452:      *
 453:      * @param float $amount
 454:      * @return Mage_Sales_Model_Order_Payment
 455:      */
 456:     public function registerCaptureNotification($amount)
 457:     {
 458:         $this->_generateTransactionId(Mage_Sales_Model_Order_Payment_Transaction::TYPE_CAPTURE,
 459:             $this->getAuthorizationTransaction()
 460:         );
 461: 
 462:         $order   = $this->getOrder();
 463:         $amount  = (float)$amount;
 464:         $invoice = $this->_getInvoiceForTransactionId($this->getTransactionId());
 465: 
 466:         // register new capture
 467:         if (!$invoice) {
 468:             if ($this->_isCaptureFinal($amount)) {
 469:                 $invoice = $order->prepareInvoice()->register();
 470:                 $order->addRelatedObject($invoice);
 471:                 $this->setCreatedInvoice($invoice);
 472:             } else {
 473:                 $this->setIsFraudDetected(true);
 474:                 $this->_updateTotals(array('base_amount_paid_online' => $amount));
 475:             }
 476:         }
 477: 
 478:         $status = true;
 479:         if ($this->getIsTransactionPending()) {
 480:             $message = Mage::helper('sales')->__('Capturing amount of %s is pending approval on gateway.', $this->_formatPrice($amount));
 481:             $state = Mage_Sales_Model_Order::STATE_PAYMENT_REVIEW;
 482:             if ($this->getIsFraudDetected()) {
 483:                 $message = Mage::helper('sales')->__('Order is suspended as its capture amount %s is suspected to be fraudulent.', $this->_formatPrice($amount));
 484:                 $status = Mage_Sales_Model_Order::STATUS_FRAUD;
 485:             }
 486:         } else {
 487:             $message = Mage::helper('sales')->__('Registered notification about captured amount of %s.', $this->_formatPrice($amount));
 488:             $state = Mage_Sales_Model_Order::STATE_PROCESSING;
 489:             if ($this->getIsFraudDetected()) {
 490:                 $state = Mage_Sales_Model_Order::STATE_PAYMENT_REVIEW;
 491:                 $message = Mage::helper('sales')->__('Order is suspended as its capture amount %s is suspected to be fraudulent.', $this->_formatPrice($amount));
 492:                 $status = Mage_Sales_Model_Order::STATUS_FRAUD;
 493:             }
 494:             // register capture for an existing invoice
 495:             if ($invoice && Mage_Sales_Model_Order_Invoice::STATE_OPEN == $invoice->getState()) {
 496:                 $invoice->pay();
 497:                 $this->_updateTotals(array('base_amount_paid_online' => $amount));
 498:                 $order->addRelatedObject($invoice);
 499:             }
 500:         }
 501: 
 502:         $transaction = $this->_addTransaction(Mage_Sales_Model_Order_Payment_Transaction::TYPE_CAPTURE, $invoice, true);
 503:         $message = $this->_prependMessage($message);
 504:         $message = $this->_appendTransactionToMessage($transaction, $message);
 505:         $order->setState($state, $status, $message);
 506:         return $this;
 507:     }
 508: 
 509:     /**
 510:      * Process authorization notification
 511:      *
 512:      * @see self::_authorize()
 513:      * @param float $amount
 514:      * @return Mage_Sales_Model_Order_Payment
 515:      */
 516:     public function registerAuthorizationNotification($amount)
 517:     {
 518:         return ($this->_isTransactionExists()) ? $this : $this->_authorize(false, $amount);
 519:     }
 520: 
 521:     /**
 522:      * Register payment fact: update self totals from the invoice
 523:      *
 524:      * @param Mage_Sales_Model_Order_Invoice $invoice
 525:      * @return Mage_Sales_Model_Order_Payment
 526:      */
 527:     public function pay($invoice)
 528:     {
 529:         $this->_updateTotals(array(
 530:             'amount_paid' => $invoice->getGrandTotal(),
 531:             'base_amount_paid' => $invoice->getBaseGrandTotal(),
 532:             'shipping_captured' => $invoice->getShippingAmount(),
 533:             'base_shipping_captured' => $invoice->getBaseShippingAmount(),
 534:         ));
 535:         Mage::dispatchEvent('sales_order_payment_pay', array('payment' => $this, 'invoice' => $invoice));
 536:         return $this;
 537:     }
 538: 
 539:     /**
 540:      * Cancel specified invoice: update self totals from it
 541:      *
 542:      * @param Mage_Sales_Model_Order_Invoice $invoice
 543:      * @return Mage_Sales_Model_Order_Payment
 544:      */
 545:     public function cancelInvoice($invoice)
 546:     {
 547:         $this->_updateTotals(array(
 548:             'amount_paid' => -1 * $invoice->getGrandTotal(),
 549:             'base_amount_paid' => -1 * $invoice->getBaseGrandTotal(),
 550:             'shipping_captured' => -1 * $invoice->getShippingAmount(),
 551:             'base_shipping_captured' => -1 * $invoice->getBaseShippingAmount(),
 552:         ));
 553:         Mage::dispatchEvent('sales_order_payment_cancel_invoice', array('payment' => $this, 'invoice' => $invoice));
 554:         return $this;
 555:     }
 556: 
 557:     /**
 558:      * Create new invoice with maximum qty for invoice for each item
 559:      * register this invoice and capture
 560:      *
 561:      * @return Mage_Sales_Model_Order_Invoice
 562:      */
 563:     protected function _invoice()
 564:     {
 565:         $invoice = $this->getOrder()->prepareInvoice();
 566: 
 567:         $invoice->register();
 568:         if ($this->getMethodInstance()->canCapture()) {
 569:             $invoice->capture();
 570:         }
 571: 
 572:         $this->getOrder()->addRelatedObject($invoice);
 573:         return $invoice;
 574:     }
 575: 
 576:     /**
 577:      * Check order payment void availability
 578:      *
 579:      * @return bool
 580:      */
 581:     public function canVoid(Varien_Object $document)
 582:     {
 583:         if (null === $this->_canVoidLookup) {
 584:             $this->_canVoidLookup = (bool)$this->getMethodInstance()->canVoid($document);
 585:             if ($this->_canVoidLookup) {
 586:                 $authTransaction = $this->getAuthorizationTransaction();
 587:                 $this->_canVoidLookup = (bool)$authTransaction && !(int)$authTransaction->getIsClosed();
 588:             }
 589:         }
 590:         return $this->_canVoidLookup;
 591:     }
 592: 
 593:     /**
 594:      * Void payment online
 595:      *
 596:      * @see self::_void()
 597:      * @param Varien_Object $document
 598:      * @return Mage_Sales_Model_Order_Payment
 599:      */
 600:     public function void(Varien_Object $document)
 601:     {
 602:         $this->_void(true);
 603:         Mage::dispatchEvent('sales_order_payment_void', array('payment' => $this, 'invoice' => $document));
 604:         return $this;
 605:     }
 606: 
 607:     /**
 608:      * Process void notification
 609:      *
 610:      * @see self::_void()
 611:      * @param float $amount
 612:      * @return Mage_Sales_Model_Payment
 613:      */
 614:     public function registerVoidNotification($amount = null)
 615:     {
 616:         if (!$this->hasMessage()) {
 617:             $this->setMessage(Mage::helper('sales')->__('Registered a Void notification.'));
 618:         }
 619:         return $this->_void(false, $amount);
 620:     }
 621: 
 622:     /**
 623:      * Refund payment online or offline, depending on whether there is invoice set in the creditmemo instance
 624:      * Updates transactions hierarchy, if required
 625:      * Updates payment totals, updates order status and adds proper comments
 626:      *
 627:      * @param Mage_Sales_Model_Order_Creditmemo $creditmemo
 628:      * @return Mage_Sales_Model_Order_Payment
 629:      */
 630:     public function refund($creditmemo)
 631:     {
 632:         $baseAmountToRefund = $this->_formatAmount($creditmemo->getBaseGrandTotal());
 633:         $order = $this->getOrder();
 634: 
 635:         $this->_generateTransactionId(Mage_Sales_Model_Order_Payment_Transaction::TYPE_REFUND);
 636: 
 637:         // call refund from gateway if required
 638:         $isOnline = false;
 639:         $gateway = $this->getMethodInstance();
 640:         $invoice = null;
 641:         if ($gateway->canRefund() && $creditmemo->getDoTransaction()) {
 642:             $this->setCreditmemo($creditmemo);
 643:             $invoice = $creditmemo->getInvoice();
 644:             if ($invoice) {
 645:                 $isOnline = true;
 646:                 $captureTxn = $this->_lookupTransaction($invoice->getTransactionId());
 647:                 if ($captureTxn) {
 648:                     $this->setParentTransactionId($captureTxn->getTxnId());
 649:                 }
 650:                 $this->setShouldCloseParentTransaction(true); // TODO: implement multiple refunds per capture
 651:                 try {
 652:                     $gateway->setStore($this->getOrder()->getStoreId())
 653:                         ->processBeforeRefund($invoice, $this)
 654:                         ->refund($this, $baseAmountToRefund)
 655:                         ->processCreditmemo($creditmemo, $this)
 656:                     ;
 657:                 } catch (Mage_Core_Exception $e) {
 658:                     if (!$captureTxn) {
 659:                         $e->setMessage(' ' . Mage::helper('sales')->__('If the invoice was created offline, try creating an offline creditmemo.'), true);
 660:                     }
 661:                     throw $e;
 662:                 }
 663:             }
 664:         }
 665: 
 666:         // update self totals from creditmemo
 667:         $this->_updateTotals(array(
 668:             'amount_refunded' => $creditmemo->getGrandTotal(),
 669:             'base_amount_refunded' => $baseAmountToRefund,
 670:             'base_amount_refunded_online' => $isOnline ? $baseAmountToRefund : null,
 671:             'shipping_refunded' => $creditmemo->getShippingAmount(),
 672:             'base_shipping_refunded' => $creditmemo->getBaseShippingAmount(),
 673:         ));
 674: 
 675:         // update transactions and order state
 676:         $transaction = $this->_addTransaction(
 677:             Mage_Sales_Model_Order_Payment_Transaction::TYPE_REFUND,
 678:             $creditmemo,
 679:             $isOnline
 680:         );
 681:         if ($invoice) {
 682:             $message = Mage::helper('sales')->__('Refunded amount of %s online.', $this->_formatPrice($baseAmountToRefund));
 683:         } else {
 684:             $message = $this->hasMessage() ? $this->getMessage()
 685:                 : Mage::helper('sales')->__('Refunded amount of %s offline.', $this->_formatPrice($baseAmountToRefund));
 686:         }
 687:         $message = $message = $this->_prependMessage($message);
 688:         $message = $this->_appendTransactionToMessage($transaction, $message);
 689:         $order->setState(Mage_Sales_Model_Order::STATE_PROCESSING, true, $message);
 690: 
 691:         Mage::dispatchEvent('sales_order_payment_refund', array('payment' => $this, 'creditmemo' => $creditmemo));
 692:         return $this;
 693:     }
 694: 
 695:     /**
 696:      * Process payment refund notification
 697:      * Updates transactions hierarchy, if required
 698:      * Prevents transaction double processing
 699:      * Updates payment totals, updates order status and adds proper comments
 700:      * TODO: potentially a full capture can be refunded. In this case if there was only one invoice for that transaction
 701:      *       then we should create a creditmemo from invoice and also refund it offline
 702:      * TODO: implement logic of chargebacks reimbursements (via negative amount)
 703:      *
 704:      * @param float $amount
 705:      * @return Mage_Sales_Model_Order_Payment
 706:      */
 707:     public function registerRefundNotification($amount)
 708:     {
 709:         $notificationAmount = $amount;
 710:         $this->_generateTransactionId(Mage_Sales_Model_Order_Payment_Transaction::TYPE_REFUND,
 711:             $this->_lookupTransaction($this->getParentTransactionId())
 712:         );
 713:         if ($this->_isTransactionExists()) {
 714:             return $this;
 715:         }
 716:         $order = $this->getOrder();
 717:         $invoice = $this->_getInvoiceForTransactionId($this->getParentTransactionId());
 718: 
 719:         if ($invoice) {
 720:             $baseGrandTotal = $invoice->getBaseGrandTotal();
 721:             $amountRefundLeft = $baseGrandTotal - $invoice->getBaseTotalRefunded();
 722:         } else {
 723:             $baseGrandTotal = $order->getBaseGrandTotal();
 724:             $amountRefundLeft = $baseGrandTotal - $order->getBaseTotalRefunded();
 725:         }
 726: 
 727:         if ($amountRefundLeft < $amount) {
 728:             $amount = $amountRefundLeft;
 729:         }
 730: 
 731:         if ($amount <= 0) {
 732:             $order->addStatusHistoryComment(Mage::helper('sales')->__('IPN "Refunded". Refund issued by merchant. Registered notification about refunded amount of %s. Transaction ID: "%s"', $this->_formatPrice($notificationAmount), $this->getTransactionId()), false);
 733:             return $this;
 734:         }
 735: 
 736:         $serviceModel = Mage::getModel('sales/service_order', $order);
 737:         if ($invoice) {
 738:             if ($invoice->getBaseTotalRefunded() > 0) {
 739:                 $adjustment = array('adjustment_positive' => $amount);
 740:             } else {
 741:                 $adjustment = array('adjustment_negative' => $baseGrandTotal - $amount);
 742:             }
 743:             $creditmemo = $serviceModel->prepareInvoiceCreditmemo($invoice, $adjustment);
 744:             if ($creditmemo) {
 745:                 $totalRefunded = $invoice->getBaseTotalRefunded() + $creditmemo->getBaseGrandTotal();
 746:                 $this->setShouldCloseParentTransaction($invoice->getBaseGrandTotal() <= $totalRefunded);
 747:             }
 748:         } else {
 749:             if ($order->getBaseTotalRefunded() > 0) {
 750:                 $adjustment = array('adjustment_positive' => $amount);
 751:             } else {
 752:                 $adjustment = array('adjustment_negative' => $baseGrandTotal - $amount);
 753:             }
 754:             $creditmemo = $serviceModel->prepareCreditmemo($adjustment);
 755:             if ($creditmemo) {
 756:                 $totalRefunded = $order->getBaseTotalRefunded() + $creditmemo->getBaseGrandTotal();
 757:                 $this->setShouldCloseParentTransaction($order->getBaseGrandTotal() <= $totalRefunded);
 758:             }
 759:         }
 760: 
 761:         $creditmemo->setPaymentRefundDisallowed(true)
 762:             ->setAutomaticallyCreated(true)
 763:             ->register()
 764:             ->addComment(Mage::helper('sales')->__('Credit memo has been created automatically'))
 765:             ->save();
 766: 
 767:         $this->_updateTotals(array(
 768:             'amount_refunded' => $creditmemo->getGrandTotal(),
 769:             'base_amount_refunded_online' => $amount
 770:         ));
 771: 
 772:         $this->setCreatedCreditmemo($creditmemo);
 773:         // update transactions and order state
 774:         $transaction = $this->_addTransaction(Mage_Sales_Model_Order_Payment_Transaction::TYPE_REFUND, $creditmemo);
 775:         $message = $this->_prependMessage(
 776:             Mage::helper('sales')->__('Registered notification about refunded amount of %s.', $this->_formatPrice($amount))
 777:         );
 778:         $message = $this->_appendTransactionToMessage($transaction, $message);
 779:         $order->setState(Mage_Sales_Model_Order::STATE_PROCESSING, true, $message);
 780:         return $this;
 781:     }
 782: 
 783:     /**
 784:      * Cancel a creditmemo: substract its totals from the payment
 785:      *
 786:      * @param Mage_Sales_Model_Order_Creditmemo $creditmemo
 787:      * @return Mage_Sales_Model_Order_Payment
 788:      */
 789:     public function cancelCreditmemo($creditmemo)
 790:     {
 791:         $this->_updateTotals(array(
 792:             'amount_refunded' => -1 * $creditmemo->getGrandTotal(),
 793:             'base_amount_refunded' => -1 * $creditmemo->getBaseGrandTotal(),
 794:             'shipping_refunded' => -1 * $creditmemo->getShippingAmount(),
 795:             'base_shipping_refunded' => -1 * $creditmemo->getBaseShippingAmount()
 796:         ));
 797:         Mage::dispatchEvent('sales_order_payment_cancel_creditmemo',
 798:             array('payment' => $this, 'creditmemo' => $creditmemo)
 799:         );
 800:         return $this;
 801:     }
 802: 
 803:     /**
 804:      * Order cancellation hook for payment method instance
 805:      * Adds void transaction if needed
 806:      * @return Mage_Sales_Model_Order_Payment
 807:      */
 808:     public function cancel()
 809:     {
 810:         $isOnline = true;
 811:         if (!$this->canVoid(new Varien_Object())) {
 812:             $isOnline = false;
 813:         }
 814: 
 815:         if (!$this->hasMessage()) {
 816:             $this->setMessage($isOnline ? Mage::helper('sales')->__('Canceled order online.')
 817:                 : Mage::helper('sales')->__('Canceled order offline.')
 818:             );
 819:         }
 820: 
 821:         if ($isOnline) {
 822:             $this->_void($isOnline, null, 'cancel');
 823:         }
 824: 
 825:         Mage::dispatchEvent('sales_order_payment_cancel', array('payment' => $this));
 826: 
 827:         return $this;
 828:     }
 829: 
 830:     /**
 831:      * Check order payment review availability
 832:      *
 833:      * @return bool
 834:      */
 835:     public function canReviewPayment()
 836:     {
 837:         return (bool)$this->getMethodInstance()->canReviewPayment($this);
 838:     }
 839: 
 840:     public function canFetchTransactionInfo()
 841:     {
 842:         return (bool)$this->getMethodInstance()->canFetchTransactionInfo();
 843:     }
 844: 
 845:     /**
 846:      * Accept online a payment that is in review state
 847:      *
 848:      * @return Mage_Sales_Model_Order_Payment
 849:      */
 850:     public function accept()
 851:     {
 852:         $this->registerPaymentReviewAction(self::REVIEW_ACTION_ACCEPT, true);
 853:         return $this;
 854:     }
 855: 
 856:     /**
 857:      * Accept order with payment method instance
 858:      *
 859:      * @return Mage_Sales_Model_Order_Payment
 860:      */
 861:     public function deny()
 862:     {
 863:         $this->registerPaymentReviewAction(self::REVIEW_ACTION_DENY, true);
 864:         return $this;
 865:     }
 866: 
 867:     /**
 868:      * Perform the payment review action: either initiated by merchant or by a notification
 869:      *
 870:      * Sets order to processing state and optionally approves invoice or cancels the order
 871:      *
 872:      * @param string $action
 873:      * @param bool $isOnline
 874:      * @return Mage_Sales_Model_Order_Payment
 875:      */
 876:     public function registerPaymentReviewAction($action, $isOnline)
 877:     {
 878:         $order = $this->getOrder();
 879: 
 880:         $transactionId = $isOnline ? $this->getLastTransId() : $this->getTransactionId();
 881:         $invoice = $this->_getInvoiceForTransactionId($transactionId);
 882: 
 883:         // invoke the payment method to determine what to do with the transaction
 884:         $result = null; $message = null;
 885:         switch ($action) {
 886:             case self::REVIEW_ACTION_ACCEPT:
 887:                 if ($isOnline) {
 888:                     if ($this->getMethodInstance()->setStore($order->getStoreId())->acceptPayment($this)) {
 889:                         $result = true;
 890:                         $message = Mage::helper('sales')->__('Approved the payment online.');
 891:                     } else {
 892:                         $result = -1;
 893:                         $message = Mage::helper('sales')->__('There is no need to approve this payment.');
 894:                     }
 895:                 } else {
 896:                     $result = (bool)$this->getNotificationResult() ? true : -1;
 897:                     $message = Mage::helper('sales')->__('Registered notification about approved payment.');
 898:                 }
 899:                 break;
 900:             case self::REVIEW_ACTION_DENY:
 901:                 if ($isOnline) {
 902:                     if ($this->getMethodInstance()->setStore($order->getStoreId())->denyPayment($this)) {
 903:                         $result = false;
 904:                         $message = Mage::helper('sales')->__('Denied the payment online.');
 905:                     } else {
 906:                         $result = -1;
 907:                         $message = Mage::helper('sales')->__('There is no need to deny this payment.');
 908:                     }
 909:                 } else {
 910:                     $result = (bool)$this->getNotificationResult() ? false : -1;
 911:                     $message = Mage::helper('sales')->__('Registered notification about denied payment.');
 912:                 }
 913:                 break;
 914:             case self::REVIEW_ACTION_UPDATE:
 915:                 if ($isOnline) {
 916:                     $this->getMethodInstance()
 917:                         ->setStore($order->getStoreId())
 918:                         ->fetchTransactionInfo($this, $transactionId);
 919:                 } else {
 920:                     // notification mechanism is responsible to update the payment object first
 921:                 }
 922:                 if ($this->getIsTransactionApproved()) {
 923:                     $result = true;
 924:                     $message = Mage::helper('sales')->__('Registered update about approved payment.');
 925:                 } elseif ($this->getIsTransactionDenied()) {
 926:                     $result = false;
 927:                     $message = Mage::helper('sales')->__('Registered update about denied payment.');
 928:                 } else {
 929:                     $result = -1;
 930:                     $message = Mage::helper('sales')->__('There is no update for the payment.');
 931:                 }
 932:                 break;
 933:             default:
 934:                 throw new Exception('Not implemented.');
 935:         }
 936:         $message = $this->_prependMessage($message);
 937:         if ($transactionId) {
 938:             $message = $this->_appendTransactionToMessage($transactionId, $message);
 939:         }
 940: 
 941:         // process payment in case of positive or negative result, or add a comment
 942:         if (-1 === $result) { // switch won't work with such $result!
 943:             $order->addStatusHistoryComment($message);
 944:         } elseif (true === $result) {
 945:             if ($invoice) {
 946:                 $invoice->pay();
 947:                 $this->_updateTotals(array('base_amount_paid_online' => $invoice->getBaseGrandTotal()));
 948:                 $order->addRelatedObject($invoice);
 949:             }
 950:             $order->setState(Mage_Sales_Model_Order::STATE_PROCESSING, true, $message);
 951:         } elseif (false === $result) {
 952:             if ($invoice) {
 953:                 $invoice->cancel();
 954:                 $order->addRelatedObject($invoice);
 955:             }
 956:             $order->registerCancellation($message, false);
 957:         }
 958:         return $this;
 959:     }
 960: 
 961:     /**
 962:      * Order payment either online
 963:      * Updates transactions hierarchy, if required
 964:      * Prevents transaction double processing
 965:      * Updates payment totals, updates order status and adds proper comments
 966:      *
 967:      * @param float $amount
 968:      * @return Mage_Sales_Model_Order_Payment
 969:      */
 970:     protected function _order($amount)
 971:     {
 972:         // update totals
 973:         $amount = $this->_formatAmount($amount, true);
 974: 
 975:         // do ordering
 976:         $order  = $this->getOrder();
 977:         $state  = Mage_Sales_Model_Order::STATE_PROCESSING;
 978:         $status = true;
 979:         $this->getMethodInstance()->setStore($order->getStoreId())->order($this, $amount);
 980: 
 981:         if ($this->getSkipOrderProcessing()) {
 982:             return $this;
 983:         }
 984: 
 985:         // similar logic of "payment review" order as in capturing
 986:         if ($this->getIsTransactionPending()) {
 987:             $message = Mage::helper('sales')->__('Ordering amount of %s is pending approval on gateway.', $this->_formatPrice($amount));
 988:             $state = Mage_Sales_Model_Order::STATE_PAYMENT_REVIEW;
 989:             if ($this->getIsFraudDetected()) {
 990:                 $status = Mage_Sales_Model_Order::STATUS_FRAUD;
 991:             }
 992:         } else {
 993:             $message = Mage::helper('sales')->__('Ordered amount of %s.', $this->_formatPrice($amount));
 994:         }
 995: 
 996:         // update transactions, order state and add comments
 997:         $transaction = $this->_addTransaction(Mage_Sales_Model_Order_Payment_Transaction::TYPE_ORDER);
 998:         $message = $this->_prependMessage($message);
 999:         $message = $this->_appendTransactionToMessage($transaction, $message);
1000:         $order->setState($state, $status, $message);
1001:         return $this;
1002:     }
1003: 
1004:     /**
1005:      * Authorize payment either online or offline (process auth notification)
1006:      * Updates transactions hierarchy, if required
1007:      * Prevents transaction double processing
1008:      * Updates payment totals, updates order status and adds proper comments
1009:      *
1010:      * @param bool $isOnline
1011:      * @param float $amount
1012:      * @return Mage_Sales_Model_Order_Payment
1013:      */
1014:     protected function _authorize($isOnline, $amount)
1015:     {
1016:         // update totals
1017:         $amount = $this->_formatAmount($amount, true);
1018:         $this->setBaseAmountAuthorized($amount);
1019: 
1020:         // do authorization
1021:         $order  = $this->getOrder();
1022:         $state  = Mage_Sales_Model_Order::STATE_PROCESSING;
1023:         $status = true;
1024:         if ($isOnline) {
1025:             // invoke authorization on gateway
1026:             $this->getMethodInstance()->setStore($order->getStoreId())->authorize($this, $amount);
1027:         }
1028: 
1029:         // similar logic of "payment review" order as in capturing
1030:         if ($this->getIsTransactionPending()) {
1031:             $message = Mage::helper('sales')->__('Authorizing amount of %s is pending approval on gateway.', $this->_formatPrice($amount));
1032:             $state = Mage_Sales_Model_Order::STATE_PAYMENT_REVIEW;
1033:             if ($this->getIsFraudDetected()) {
1034:                 $status = Mage_Sales_Model_Order::STATUS_FRAUD;
1035:             }
1036:         } else {
1037:             $message = Mage::helper('sales')->__('Authorized amount of %s.', $this->_formatPrice($amount));
1038:         }
1039: 
1040:         // update transactions, order state and add comments
1041:         $transaction = $this->_addTransaction(Mage_Sales_Model_Order_Payment_Transaction::TYPE_AUTH);
1042:         if ($order->isNominal()) {
1043:             $message = $this->_prependMessage(Mage::helper('sales')->__('Nominal order registered.'));
1044:         } else {
1045:             $message = $this->_prependMessage($message);
1046:             $message = $this->_appendTransactionToMessage($transaction, $message);
1047:         }
1048:         $order->setState($state, $status, $message);
1049: 
1050:         return $this;
1051:     }
1052: 
1053:     /**
1054:      * Public access to _authorize method
1055:      * @param bool $isOnline
1056:      * @param float $amount
1057:      */
1058:     public function authorize($isOnline, $amount)
1059:     {
1060:         return $this->_authorize($isOnline, $amount);
1061:     }
1062: 
1063:     /**
1064:      * Void payment either online or offline (process void notification)
1065:      * NOTE: that in some cases authorization can be voided after a capture. In such case it makes sense to use
1066:      *       the amount void amount, for informational purposes.
1067:      * Updates payment totals, updates order status and adds proper comments
1068:      *
1069:      * @param bool $isOnline
1070:      * @param float $amount
1071:      * @param string $gatewayCallback
1072:      * @return Mage_Sales_Model_Order_Payment
1073:      */
1074:     protected function _void($isOnline, $amount = null, $gatewayCallback = 'void')
1075:     {
1076:         $order = $this->getOrder();
1077:         $authTransaction = $this->getAuthorizationTransaction();
1078:         $this->_generateTransactionId(Mage_Sales_Model_Order_Payment_Transaction::TYPE_VOID, $authTransaction);
1079:         $this->setShouldCloseParentTransaction(true);
1080: 
1081:         // attempt to void
1082:         if ($isOnline) {
1083:             $this->getMethodInstance()->setStore($order->getStoreId())->$gatewayCallback($this);
1084:         }
1085:         if ($this->_isTransactionExists()) {
1086:             return $this;
1087:         }
1088: 
1089:         // if the authorization was untouched, we may assume voided amount = order grand total
1090:         // but only if the payment auth amount equals to order grand total
1091:         if ($authTransaction && ($order->getBaseGrandTotal() == $this->getBaseAmountAuthorized())
1092:             && (0 == $this->getBaseAmountCanceled())) {
1093:             if ($authTransaction->canVoidAuthorizationCompletely()) {
1094:                 $amount = (float)$order->getBaseGrandTotal();
1095:             }
1096:         }
1097: 
1098:         if ($amount) {
1099:             $amount = $this->_formatAmount($amount);
1100:         }
1101: 
1102:         // update transactions, order state and add comments
1103:         $transaction = $this->_addTransaction(Mage_Sales_Model_Order_Payment_Transaction::TYPE_VOID, null, true);
1104:         $message = $this->hasMessage() ? $this->getMessage() : Mage::helper('sales')->__('Voided authorization.');
1105:         $message = $this->_prependMessage($message);
1106:         if ($amount) {
1107:             $message .= ' ' . Mage::helper('sales')->__('Amount: %s.', $this->_formatPrice($amount));
1108:         }
1109:         $message = $this->_appendTransactionToMessage($transaction, $message);
1110:         $order->setState(Mage_Sales_Model_Order::STATE_PROCESSING, true, $message);
1111:         return $this;
1112:     }
1113: 
1114: //    /**
1115: //     * TODO: implement this
1116: //     * @param Mage_Sales_Model_Order_Invoice $invoice
1117: //     * @return Mage_Sales_Model_Order_Payment
1118: //     */
1119: //    public function cancelCapture($invoice = null)
1120: //    {
1121: //    }
1122: 
1123:     /**
1124:      * Create transaction,
1125:      * prepare its insertion into hierarchy and add its information to payment and comments
1126:      *
1127:      * To add transactions and related information,
1128:      * the following information should be set to payment before processing:
1129:      * - transaction_id
1130:      * - is_transaction_closed (optional) - whether transaction should be closed or open (closed by default)
1131:      * - parent_transaction_id (optional)
1132:      * - should_close_parent_transaction (optional) - whether to close parent transaction (closed by default)
1133:      *
1134:      * If the sales document is specified, it will be linked to the transaction as related for future usage.
1135:      * Currently transaction ID is set into the sales object
1136:      * This method writes the added transaction ID into last_trans_id field of the payment object
1137:      *
1138:      * To make sure transaction object won't cause trouble before saving, use $failsafe = true
1139:      *
1140:      * @param string $type
1141:      * @param Mage_Sales_Model_Abstract $salesDocument
1142:      * @param bool $failsafe
1143:      * @return null|Mage_Sales_Model_Order_Payment_Transaction
1144:      */
1145:     protected function _addTransaction($type, $salesDocument = null, $failsafe = false)
1146:     {
1147:         if ($this->getSkipTransactionCreation()) {
1148:             $this->unsTransactionId();
1149:             return null;
1150:         }
1151: 
1152:         // look for set transaction ids
1153:         $transactionId = $this->getTransactionId();
1154:         if (null !== $transactionId) {
1155:             // set transaction parameters
1156:             $transaction = false;
1157:             if ($this->getOrder()->getId()) {
1158:                 $transaction = $this->_lookupTransaction($transactionId);
1159:             }
1160:             if (!$transaction) {
1161:                 $transaction = Mage::getModel('sales/order_payment_transaction')->setTxnId($transactionId);
1162:             }
1163:             $transaction
1164:                 ->setOrderPaymentObject($this)
1165:                 ->setTxnType($type)
1166:                 ->isFailsafe($failsafe);
1167: 
1168:             if ($this->hasIsTransactionClosed()) {
1169:                 $transaction->setIsClosed((int)$this->getIsTransactionClosed());
1170:             }
1171: 
1172:             //set transaction addition information
1173:             if ($this->_transactionAdditionalInfo) {
1174:                 foreach ($this->_transactionAdditionalInfo as $key => $value) {
1175:                     $transaction->setAdditionalInformation($key, $value);
1176:                 }
1177:             }
1178: 
1179:             // link with sales entities
1180:             $this->setLastTransId($transactionId);
1181:             $this->setCreatedTransaction($transaction);
1182:             $this->getOrder()->addRelatedObject($transaction);
1183:             if ($salesDocument && $salesDocument instanceof Mage_Sales_Model_Abstract) {
1184:                 $salesDocument->setTransactionId($transactionId);
1185:                 // TODO: linking transaction with the sales document
1186:             }
1187: 
1188:             // link with parent transaction
1189:             $parentTransactionId = $this->getParentTransactionId();
1190: 
1191:             if ($parentTransactionId) {
1192:                 $transaction->setParentTxnId($parentTransactionId);
1193:                 if ($this->getShouldCloseParentTransaction()) {
1194:                     $parentTransaction = $this->_lookupTransaction($parentTransactionId);
1195:                     if ($parentTransaction) {
1196:                         if (!$parentTransaction->getIsClosed()) {
1197:                             $parentTransaction->isFailsafe($failsafe)->close(false);
1198:                         }
1199:                         $this->getOrder()->addRelatedObject($parentTransaction);
1200:                     }
1201:                 }
1202:             }
1203:             return $transaction;
1204:         }
1205:     }
1206: 
1207:     /**
1208:      * Public acces to _addTransaction method
1209:      *
1210:      * @param string $type
1211:      * @param Mage_Sales_Model_Abstract $salesDocument
1212:      * @param bool $failsafe
1213:      * @param string $message
1214:      * @return null|Mage_Sales_Model_Order_Payment_Transaction
1215:      */
1216:     public function addTransaction($type, $salesDocument = null, $failsafe = false, $message = false)
1217:     {
1218:         $transaction = $this->_addTransaction($type, $salesDocument, $failsafe);
1219: 
1220:         if ($message) {
1221:             $order = $this->getOrder();
1222:             $message = $this->_appendTransactionToMessage($transaction, $message);
1223:             $order->addStatusHistoryComment($message);
1224:         }
1225: 
1226:         return $transaction;
1227:     }
1228: 
1229:     /**
1230:      * Import details data of specified transaction
1231:      *
1232:      * @param Mage_Sales_Model_Order_Payment_Transaction $transactionTo
1233:      * @return Mage_Sales_Model_Order_Payment
1234:      */
1235:     public function importTransactionInfo(Mage_Sales_Model_Order_Payment_Transaction $transactionTo)
1236:     {
1237:         $data = $this->getMethodInstance()
1238:             ->setStore($this->getOrder()->getStoreId())
1239:             ->fetchTransactionInfo($this, $transactionTo->getTxnId());
1240:         if ($data) {
1241:             $transactionTo->setAdditionalInformation(Mage_Sales_Model_Order_Payment_Transaction::RAW_DETAILS, $data);
1242:         }
1243:         return $this;
1244:     }
1245: 
1246:     /**
1247:      * Get the billing agreement, if any
1248:      *
1249:      * @return Mage_Sales_Model_Billing_Agreement|null
1250:      */
1251:     public function getBillingAgreement()
1252:     {
1253:         return $this->_billingAgreement;
1254:     }
1255: 
1256:     /**
1257:      * Totals updater utility method
1258:      * Updates self totals by keys in data array('key' => $delta)
1259:      *
1260:      * @param array $data
1261:      */
1262:     protected function _updateTotals($data)
1263:     {
1264:         foreach ($data as $key => $amount) {
1265:             if (null !== $amount) {
1266:                 $was = $this->getDataUsingMethod($key);
1267:                 $this->setDataUsingMethod($key, $was + $amount);
1268:             }
1269:         }
1270:     }
1271: 
1272:     /**
1273:      * Prevent double processing of the same transaction by a payment notification
1274:      * Uses either specified txn_id or the transaction id that was set before
1275:      *
1276:      * @deprecated after 1.4.0.1
1277:      * @param string $txnId
1278:      * @throws Mage_Core_Exception
1279:      */
1280:     protected function _avoidDoubleTransactionProcessing($txnId = null)
1281:     {
1282:         if ($this->_isTransactionExists($txnId)) {
1283:             Mage::throwException(
1284:                 Mage::helper('sales')->__('Transaction "%s" was already processed.', $txnId)
1285:             );
1286:         }
1287:     }
1288: 
1289:     /**
1290:      * Check transaction existence by specified transaction id
1291:      *
1292:      * @param string $txnId
1293:      * @return boolean
1294:      */
1295:     protected function _isTransactionExists($txnId = null)
1296:     {
1297:         if (null === $txnId) {
1298:             $txnId = $this->getTransactionId();
1299:         }
1300:         return $txnId && $this->_lookupTransaction($txnId);
1301:     }
1302: 
1303:     /**
1304:      * Append transaction ID (if any) message to the specified message
1305:      *
1306:      * @param Mage_Sales_Model_Order_Payment_Transaction|null $transaction
1307:      * @param string $message
1308:      * @return string
1309:      */
1310:     protected function _appendTransactionToMessage($transaction, $message)
1311:     {
1312:         if ($transaction) {
1313:             $txnId = is_object($transaction) ? $transaction->getTxnId() : $transaction;
1314:             $message .= ' ' . Mage::helper('sales')->__('Transaction ID: "%s".', $txnId);
1315:         }
1316:         return $message;
1317:     }
1318: 
1319:     /**
1320:      * Prepend a "prepared_message" that may be set to the payment instance before, to the specified message
1321:      * Prepends value to the specified string or to the comment of specified order status history item instance
1322:      *
1323:      * @param string|Mage_Sales_Model_Order_Status_History $messagePrependTo
1324:      * @return string|Mage_Sales_Model_Order_Status_History
1325:      */
1326:     protected function _prependMessage($messagePrependTo)
1327:     {
1328:         $preparedMessage = $this->getPreparedMessage();
1329:         if ($preparedMessage) {
1330:             if (is_string($preparedMessage)) {
1331:                 return $preparedMessage . ' ' . $messagePrependTo;
1332:             } elseif (is_object($preparedMessage)
1333:                 && ($preparedMessage instanceof Mage_Sales_Model_Order_Status_History)
1334:             ) {
1335:                 $comment = $preparedMessage->getComment() . ' ' . $messagePrependTo;
1336:                 $preparedMessage->setComment($comment);
1337:                 return $comment;
1338:             }
1339:         }
1340:         return $messagePrependTo;
1341:     }
1342: 
1343:     /**
1344:      * Round up and cast specified amount to float or string
1345:      *
1346:      * @param string|float $amount
1347:      * @param bool $asFloat
1348:      * @return string|float
1349:      */
1350:     protected function _formatAmount($amount, $asFloat = false)
1351:     {
1352:          $amount = Mage::app()->getStore()->roundPrice($amount);
1353:          return !$asFloat ? (string)$amount : $amount;
1354:     }
1355: 
1356:     /**
1357:      * Format price with currency sign
1358:      * @param float $amount
1359:      * @return string
1360:      */
1361:     protected function _formatPrice($amount)
1362:     {
1363:         return $this->getOrder()->getBaseCurrency()->formatTxt($amount);
1364:     }
1365: 
1366:     /**
1367:      * Find one transaction by ID or type
1368:      * @param string $txnId
1369:      * @param string $txnType
1370:      * @return Mage_Sales_Model_Order_Payment_Transaction|false
1371:      */
1372:     protected function _lookupTransaction($txnId, $txnType = false)
1373:     {
1374:         if (!$txnId) {
1375:             if ($txnType && $this->getId()) {
1376:                 $collection = Mage::getModel('sales/order_payment_transaction')->getCollection()
1377:                     ->setOrderFilter($this->getOrder())
1378:                     ->addPaymentIdFilter($this->getId())
1379:                     ->addTxnTypeFilter($txnType)
1380:                     ->setOrder('created_at', Varien_Data_Collection::SORT_ORDER_DESC)
1381:                     ->setOrder('transaction_id', Varien_Data_Collection::SORT_ORDER_DESC);
1382:                 foreach ($collection as $txn) {
1383:                     $txn->setOrderPaymentObject($this);
1384:                     $this->_transactionsLookup[$txn->getTxnId()] = $txn;
1385:                     return $txn;
1386:                 }
1387:             }
1388:             return false;
1389:         }
1390:         if (isset($this->_transactionsLookup[$txnId])) {
1391:             return $this->_transactionsLookup[$txnId];
1392:         }
1393:         $txn = Mage::getModel('sales/order_payment_transaction')
1394:             ->setOrderPaymentObject($this)
1395:             ->loadByTxnId($txnId);
1396:         if ($txn->getId()) {
1397:             $this->_transactionsLookup[$txnId] = $txn;
1398:         } else {
1399:             $this->_transactionsLookup[$txnId] = false;
1400:         }
1401:         return $this->_transactionsLookup[$txnId];
1402:     }
1403: 
1404:     /**
1405:      * Find one transaction by ID or type
1406:      * @param string $txnId
1407:      * @param string $txnType
1408:      * @return Mage_Sales_Model_Order_Payment_Transaction|false
1409:      */
1410:     public function lookupTransaction($txnId, $txnType = false)
1411:     {
1412:         return $this->_lookupTransaction($txnId, $txnType);
1413:     }
1414: 
1415:     /**
1416:      * Lookup an authorization transaction using parent transaction id, if set
1417:      * @return Mage_Sales_Model_Order_Payment_Transaction|false
1418:      */
1419:     public function getAuthorizationTransaction()
1420:     {
1421:         if ($this->getParentTransactionId()) {
1422:             $txn = $this->_lookupTransaction($this->getParentTransactionId());
1423:         } else {
1424:             $txn = false;
1425:         }
1426: 
1427:         if (!$txn) {
1428:             $txn = $this->_lookupTransaction(false, Mage_Sales_Model_Order_Payment_Transaction::TYPE_AUTH);
1429:         }
1430:         return $txn;
1431:     }
1432: 
1433:     /**
1434:      * Lookup the transaction by id
1435:      * @param string $transactionId
1436:      * @return Mage_Sales_Model_Order_Payment_Transaction|false
1437:      */
1438:     public function getTransaction($transactionId)
1439:     {
1440:         return $this->_lookupTransaction($transactionId);
1441:     }
1442: 
1443:     /**
1444:      * Update transaction ids for further processing
1445:      * If no transactions were set before invoking, may generate an "offline" transaction id
1446:      *
1447:      * @param string $type
1448:      * @param Mage_Sales_Model_Order_Payment_Transaction $transactionBasedOn
1449:      */
1450:     protected function _generateTransactionId($type, $transactionBasedOn = false)
1451:     {
1452:         if (!$this->getParentTransactionId() && !$this->getTransactionId() && $transactionBasedOn) {
1453:             $this->setParentTransactionId($transactionBasedOn->getTxnId());
1454:         }
1455:         // generate transaction id for an offline action or payment method that didn't set it
1456:         if (($parentTxnId = $this->getParentTransactionId()) && !$this->getTransactionId()) {
1457:             $this->setTransactionId("{$parentTxnId}-{$type}");
1458:         }
1459:     }
1460: 
1461:     /**
1462:      * Decide whether authorization transaction may close (if the amount to capture will cover entire order)
1463:      * @param float $amountToCapture
1464:      * @return bool
1465:      */
1466:     protected function _isCaptureFinal($amountToCapture)
1467:     {
1468:         $amountToCapture = $this->_formatAmount($amountToCapture, true);
1469:         $orderGrandTotal = $this->_formatAmount($this->getOrder()->getBaseGrandTotal(), true);
1470:         if ($orderGrandTotal == $this->_formatAmount($this->getBaseAmountPaid(), true) + $amountToCapture) {
1471:             if (false !== $this->getShouldCloseParentTransaction()) {
1472:                 $this->setShouldCloseParentTransaction(true);
1473:             }
1474:             return true;
1475:         }
1476:         return false;
1477:     }
1478: 
1479:     /**
1480:      * Before object save manipulations
1481:      *
1482:      * @return Mage_Sales_Model_Order_Payment
1483:      */
1484:     protected function _beforeSave()
1485:     {
1486:         parent::_beforeSave();
1487: 
1488:         if (!$this->getParentId() && $this->getOrder()) {
1489:             $this->setParentId($this->getOrder()->getId());
1490:         }
1491: 
1492:         return $this;
1493:     }
1494: 
1495:     /**
1496:      * Generate billing agreement object if there is billing agreement data
1497:      * Adds it to order as related object
1498:      */
1499:     protected function _createBillingAgreement()
1500:     {
1501:         if ($this->getBillingAgreementData()) {
1502:             $order = $this->getOrder();
1503:             $agreement = Mage::getModel('sales/billing_agreement')->importOrderPayment($this);
1504:             if ($agreement->isValid()) {
1505:                 $message = Mage::helper('sales')->__('Created billing agreement #%s.', $agreement->getReferenceId());
1506:                 $order->addRelatedObject($agreement);
1507:                 $this->_billingAgreement = $agreement;
1508:             } else {
1509:                 $message = Mage::helper('sales')->__('Failed to create billing agreement for this order.');
1510:             }
1511:             $comment = $order->addStatusHistoryComment($message);
1512:             $order->addRelatedObject($comment);
1513:         }
1514:     }
1515: 
1516:     /**
1517:      * Additionnal transaction info setter
1518:      *
1519:      * @param sting $key
1520:      * @param string $value
1521:      */
1522:     public function setTransactionAdditionalInfo($key, $value)
1523:     {
1524:         if (is_array($key)) {
1525:             $this->_transactionAdditionalInfo = $key;
1526:         } else {
1527:             $this->_transactionAdditionalInfo[$key] = $value;
1528:         }
1529:     }
1530: 
1531:     /**
1532:      * Additionnal transaction info getter
1533:      *
1534:      * @param sting $key
1535:      * @return mixed
1536:      */
1537:     public function getTransactionAdditionalInfo($key = null)
1538:     {
1539:         if (is_null($key)) {
1540:             return $this->_transactionAdditionalInfo;
1541:         }
1542:         return isset($this->_transactionAdditionalInfo[$key]) ? $this->_transactionAdditionalInfo[$key] : null;
1543:     }
1544: 
1545:     /**
1546:      * Reset transaction additional info property
1547:      *
1548:      * @return Mage_Sales_Model_Order_Payment
1549:      */
1550:     public function resetTransactionAdditionalInfo()
1551:     {
1552:         $this->_transactionAdditionalInfo = array();
1553:         return $this;
1554:     }
1555: 
1556:     /**
1557:      * Return invoice model for transaction
1558:      *
1559:      * @param string $transactionId
1560:      * @return Mage_Sales_Model_Order_Invoice
1561:      */
1562:     protected function _getInvoiceForTransactionId($transactionId)
1563:     {
1564:         foreach ($this->getOrder()->getInvoiceCollection() as $invoice) {
1565:             if ($invoice->getTransactionId() == $transactionId) {
1566:                 $invoice->load($invoice->getId()); // to make sure all data will properly load (maybe not required)
1567:                 return $invoice;
1568:             }
1569:         }
1570:         foreach ($this->getOrder()->getInvoiceCollection() as $invoice) {
1571:             if ($invoice->getState() == Mage_Sales_Model_Order_Invoice::STATE_OPEN
1572:                 && $invoice->load($invoice->getId())
1573:             ) {
1574:                 $invoice->setTransactionId($transactionId);
1575:                 return $invoice;
1576:             }
1577:         }
1578:         return false;
1579:     }
1580: }
1581: