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_Payment
 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:  * Payment method abstract model
 29:  *
 30:  * @author      Magento Core Team <core@magentocommerce.com>
 31:  */
 32: abstract class Mage_Payment_Model_Method_Abstract extends Varien_Object
 33: {
 34:     const ACTION_ORDER              = 'order';
 35:     const ACTION_AUTHORIZE          = 'authorize';
 36:     const ACTION_AUTHORIZE_CAPTURE  = 'authorize_capture';
 37: 
 38:     const STATUS_UNKNOWN    = 'UNKNOWN';
 39:     const STATUS_APPROVED   = 'APPROVED';
 40:     const STATUS_ERROR      = 'ERROR';
 41:     const STATUS_DECLINED   = 'DECLINED';
 42:     const STATUS_VOID       = 'VOID';
 43:     const STATUS_SUCCESS    = 'SUCCESS';
 44: 
 45:     protected $_code;
 46:     protected $_formBlockType = 'payment/form';
 47:     protected $_infoBlockType = 'payment/info';
 48: 
 49:     /**
 50:      * Payment Method features
 51:      * @var bool
 52:      */
 53:     protected $_isGateway                   = false;
 54:     protected $_canOrder                    = false;
 55:     protected $_canAuthorize                = false;
 56:     protected $_canCapture                  = false;
 57:     protected $_canCapturePartial           = false;
 58:     protected $_canRefund                   = false;
 59:     protected $_canRefundInvoicePartial     = false;
 60:     protected $_canVoid                     = false;
 61:     protected $_canUseInternal              = true;
 62:     protected $_canUseCheckout              = true;
 63:     protected $_canUseForMultishipping      = true;
 64:     protected $_isInitializeNeeded          = false;
 65:     protected $_canFetchTransactionInfo     = false;
 66:     protected $_canReviewPayment            = false;
 67:     protected $_canCreateBillingAgreement   = false;
 68:     protected $_canManageRecurringProfiles  = true;
 69:     /**
 70:      * TODO: whether a captured transaction may be voided by this gateway
 71:      * This may happen when amount is captured, but not settled
 72:      * @var bool
 73:      */
 74:     protected $_canCancelInvoice        = false;
 75: 
 76:     /**
 77:      * Fields that should be replaced in debug with '***'
 78:      *
 79:      * @var array
 80:      */
 81:     protected $_debugReplacePrivateDataKeys = array();
 82: 
 83:     public function __construct()
 84:     {
 85: 
 86:     }
 87: 
 88:     /**
 89:      * Check order availability
 90:      *
 91:      * @return bool
 92:      */
 93:     public function canOrder()
 94:     {
 95:         return $this->_canOrder;
 96:     }
 97: 
 98:     /**
 99:      * Check authorise availability
100:      *
101:      * @return bool
102:      */
103:     public function canAuthorize()
104:     {
105:         return $this->_canAuthorize;
106:     }
107: 
108:     /**
109:      * Check capture availability
110:      *
111:      * @return bool
112:      */
113:     public function canCapture()
114:     {
115:         return $this->_canCapture;
116:     }
117: 
118:     /**
119:      * Check partial capture availability
120:      *
121:      * @return bool
122:      */
123:     public function canCapturePartial()
124:     {
125:         return $this->_canCapturePartial;
126:     }
127: 
128:     /**
129:      * Check refund availability
130:      *
131:      * @return bool
132:      */
133:     public function canRefund()
134:     {
135:         return $this->_canRefund;
136:     }
137: 
138:     /**
139:      * Check partial refund availability for invoice
140:      *
141:      * @return bool
142:      */
143:     public function canRefundPartialPerInvoice()
144:     {
145:         return $this->_canRefundInvoicePartial;
146:     }
147: 
148:     /**
149:      * Check void availability
150:      *
151:      * @param   Varien_Object $payment
152:      * @return  bool
153:      */
154:     public function canVoid(Varien_Object $payment)
155:     {
156:         return $this->_canVoid;
157:     }
158: 
159:     /**
160:      * Using internal pages for input payment data
161:      * Can be used in admin
162:      *
163:      * @return bool
164:      */
165:     public function canUseInternal()
166:     {
167:         return $this->_canUseInternal;
168:     }
169: 
170:     /**
171:      * Can be used in regular checkout
172:      *
173:      * @return bool
174:      */
175:     public function canUseCheckout()
176:     {
177:         return $this->_canUseCheckout;
178:     }
179: 
180:     /**
181:      * Using for multiple shipping address
182:      *
183:      * @return bool
184:      */
185:     public function canUseForMultishipping()
186:     {
187:         return $this->_canUseForMultishipping;
188:     }
189: 
190:     /**
191:      * Can be edit order (renew order)
192:      *
193:      * @return bool
194:      */
195:     public function canEdit()
196:     {
197:         return true;
198:     }
199: 
200:     /**
201:      * Check fetch transaction info availability
202:      *
203:      * @return bool
204:      */
205:     public function canFetchTransactionInfo()
206:     {
207:         return $this->_canFetchTransactionInfo;
208:     }
209: 
210:     /**
211:      * Check whether payment method instance can create billing agreements
212:      *
213:      * @return bool
214:      */
215:     public function canCreateBillingAgreement()
216:     {
217:         return $this->_canCreateBillingAgreement;
218:     }
219: 
220:     /**
221:      * Fetch transaction info
222:      *
223:      * @param Mage_Payment_Model_Info $payment
224:      * @param string $transactionId
225:      * @return array
226:      */
227:     public function fetchTransactionInfo(Mage_Payment_Model_Info $payment, $transactionId)
228:     {
229:         return array();
230:     }
231: 
232:     /**
233:      * Retrieve payment system relation flag
234:      *
235:      * @return bool
236:      */
237:     public function isGateway()
238:     {
239:         return $this->_isGateway;
240:     }
241: 
242:     /**
243:      * flag if we need to run payment initialize while order place
244:      *
245:      * @return bool
246:      */
247:     public function isInitializeNeeded()
248:     {
249:         return $this->_isInitializeNeeded;
250:     }
251: 
252:     /**
253:      * To check billing country is allowed for the payment method
254:      *
255:      * @return bool
256:      */
257:     public function canUseForCountry($country)
258:     {
259:         /*
260:         for specific country, the flag will set up as 1
261:         */
262:         if($this->getConfigData('allowspecific')==1){
263:             $availableCountries = explode(',', $this->getConfigData('specificcountry'));
264:             if(!in_array($country, $availableCountries)){
265:                 return false;
266:             }
267: 
268:         }
269:         return true;
270:     }
271: 
272:     /**
273:      * Check method for processing with base currency
274:      *
275:      * @param string $currencyCode
276:      * @return boolean
277:      */
278:     public function canUseForCurrency($currencyCode)
279:     {
280:         return true;
281:     }
282: 
283:     /**
284:      * Check manage billing agreements availability
285:      *
286:      * @return bool
287:      */
288:     public function canManageBillingAgreements()
289:     {
290:         return ($this instanceof Mage_Payment_Model_Billing_Agreement_MethodInterface);
291:     }
292: 
293:     /**
294:      * Whether can manage recurring profiles
295:      *
296:      * @return bool
297:      */
298:     public function canManageRecurringProfiles()
299:     {
300:         return $this->_canManageRecurringProfiles
301:                && ($this instanceof Mage_Payment_Model_Recurring_Profile_MethodInterface);
302:     }
303: 
304:     /**
305:      * Retrieve model helper
306:      *
307:      * @return Mage_Payment_Helper_Data
308:      */
309:     protected function _getHelper()
310:     {
311:         return Mage::helper('payment');
312:     }
313: 
314:     /**
315:      * Retrieve payment method code
316:      *
317:      * @return string
318:      */
319:     public function getCode()
320:     {
321:         if (empty($this->_code)) {
322:             Mage::throwException(Mage::helper('payment')->__('Cannot retrieve the payment method code.'));
323:         }
324:         return $this->_code;
325:     }
326: 
327:     /**
328:      * Retrieve block type for method form generation
329:      *
330:      * @return string
331:      */
332:     public function getFormBlockType()
333:     {
334:         return $this->_formBlockType;
335:     }
336: 
337:     /**
338:      * Retrieve block type for display method information
339:      *
340:      * @return string
341:      */
342:     public function getInfoBlockType()
343:     {
344:         return $this->_infoBlockType;
345:     }
346: 
347:     /**
348:      * Retrieve payment iformation model object
349:      *
350:      * @return Mage_Payment_Model_Info
351:      */
352:     public function getInfoInstance()
353:     {
354:         $instance = $this->getData('info_instance');
355:         if (!($instance instanceof Mage_Payment_Model_Info)) {
356:             Mage::throwException(Mage::helper('payment')->__('Cannot retrieve the payment information object instance.'));
357:         }
358:         return $instance;
359:     }
360: 
361:     /**
362:      * Validate payment method information object
363:      *
364:      * @return Mage_Payment_Model_Abstract
365:      */
366:     public function validate()
367:     {
368:          /**
369:           * to validate payment method is allowed for billing country or not
370:           */
371:          $paymentInfo = $this->getInfoInstance();
372:          if ($paymentInfo instanceof Mage_Sales_Model_Order_Payment) {
373:              $billingCountry = $paymentInfo->getOrder()->getBillingAddress()->getCountryId();
374:          } else {
375:              $billingCountry = $paymentInfo->getQuote()->getBillingAddress()->getCountryId();
376:          }
377:          if (!$this->canUseForCountry($billingCountry)) {
378:              Mage::throwException(Mage::helper('payment')->__('Selected payment type is not allowed for billing country.'));
379:          }
380:          return $this;
381:     }
382: 
383:     /**
384:      * Order payment abstract method
385:      *
386:      * @param Varien_Object $payment
387:      * @param float $amount
388:      *
389:      * @return Mage_Payment_Model_Abstract
390:      */
391:     public function order(Varien_Object $payment, $amount)
392:     {
393:         if (!$this->canOrder()) {
394:             Mage::throwException(Mage::helper('payment')->__('Order action is not available.'));
395:         }
396:         return $this;
397:     }
398: 
399:     /**
400:      * Authorize payment abstract method
401:      *
402:      * @param Varien_Object $payment
403:      * @param float $amount
404:      *
405:      * @return Mage_Payment_Model_Abstract
406:      */
407:     public function authorize(Varien_Object $payment, $amount)
408:     {
409:         if (!$this->canAuthorize()) {
410:             Mage::throwException(Mage::helper('payment')->__('Authorize action is not available.'));
411:         }
412:         return $this;
413:     }
414: 
415:     /**
416:      * Capture payment abstract method
417:      *
418:      * @param Varien_Object $payment
419:      * @param float $amount
420:      *
421:      * @return Mage_Payment_Model_Abstract
422:      */
423:     public function capture(Varien_Object $payment, $amount)
424:     {
425:         if (!$this->canCapture()) {
426:             Mage::throwException(Mage::helper('payment')->__('Capture action is not available.'));
427:         }
428: 
429:         return $this;
430:     }
431: 
432:     /**
433:      * Set capture transaction ID to invoice for informational purposes
434:      * @param Mage_Sales_Model_Order_Invoice $invoice
435:      * @param Mage_Sales_Model_Order_Payment $payment
436:      * @return Mage_Payment_Model_Method_Abstract
437:      */
438:     public function processInvoice($invoice, $payment)
439:     {
440:         $invoice->setTransactionId($payment->getLastTransId());
441:         return $this;
442:     }
443: 
444:     /**
445:      * Set refund transaction id to payment object for informational purposes
446:      * Candidate to be deprecated:
447:      * there can be multiple refunds per payment, thus payment.refund_transaction_id doesn't make big sense
448:      *
449:      * @param Mage_Sales_Model_Order_Invoice $invoice
450:      * @param Mage_Sales_Model_Order_Payment $payment
451:      * @return Mage_Payment_Model_Method_Abstract
452:      */
453:     public function processBeforeRefund($invoice, $payment)
454:     {
455:         $payment->setRefundTransactionId($invoice->getTransactionId());
456:         return $this;
457:     }
458: 
459:     /**
460:      * Refund specified amount for payment
461:      *
462:      * @param Varien_Object $payment
463:      * @param float $amount
464:      *
465:      * @return Mage_Payment_Model_Abstract
466:      */
467:     public function refund(Varien_Object $payment, $amount)
468:     {
469: 
470:         if (!$this->canRefund()) {
471:             Mage::throwException(Mage::helper('payment')->__('Refund action is not available.'));
472:         }
473: 
474: 
475:         return $this;
476:     }
477: 
478:     /**
479:      * Set transaction ID into creditmemo for informational purposes
480:      * @param Mage_Sales_Model_Order_Creditmemo $creditmemo
481:      * @param Mage_Sales_Model_Order_Payment $payment
482:      * @return Mage_Payment_Model_Method_Abstract
483:      */
484:     public function processCreditmemo($creditmemo, $payment)
485:     {
486:         $creditmemo->setTransactionId($payment->getLastTransId());
487:         return $this;
488:     }
489: 
490:     /**
491:      * Cancel payment abstract method
492:      *
493:      * @param Varien_Object $payment
494:      *
495:      * @return Mage_Payment_Model_Abstract
496:      */
497:     public function cancel(Varien_Object $payment)
498:     {
499:         return $this;
500:     }
501: 
502:     /**
503:      * @deprecated after 1.4.0.0-alpha3
504:      * this method doesn't make sense, because invoice must not void entire authorization
505:      * there should be method for invoice cancellation
506:      * @param Mage_Sales_Model_Order_Invoice $invoice
507:      * @param Mage_Sales_Model_Order_Payment $payment
508:      * @return Mage_Payment_Model_Method_Abstract
509:      */
510:     public function processBeforeVoid($invoice, $payment)
511:     {
512:         $payment->setVoidTransactionId($invoice->getTransactionId());
513:         return $this;
514:     }
515: 
516:     /**
517:      * Void payment abstract method
518:      *
519:      * @param Varien_Object $payment
520:      *
521:      * @return Mage_Payment_Model_Abstract
522:      */
523:     public function void(Varien_Object $payment)
524:     {
525:         if (!$this->canVoid($payment)) {
526:             Mage::throwException(Mage::helper('payment')->__('Void action is not available.'));
527:         }
528:         return $this;
529:     }
530: 
531:     /**
532:      * Whether this method can accept or deny payment
533:      *
534:      * @param Mage_Payment_Model_Info $payment
535:      *
536:      * @return bool
537:      */
538:     public function canReviewPayment(Mage_Payment_Model_Info $payment)
539:     {
540:         return $this->_canReviewPayment;
541:     }
542: 
543:     /**
544:      * Attempt to accept a payment that us under review
545:      *
546:      * @param Mage_Payment_Model_Info $payment
547:      * @return bool
548:      * @throws Mage_Core_Exception
549:      */
550:     public function acceptPayment(Mage_Payment_Model_Info $payment)
551:     {
552:         if (!$this->canReviewPayment($payment)) {
553:             Mage::throwException(Mage::helper('payment')->__('The payment review action is unavailable.'));
554:         }
555:         return false;
556:     }
557: 
558:     /**
559:      * Attempt to deny a payment that us under review
560:      *
561:      * @param Mage_Payment_Model_Info $payment
562:      * @return bool
563:      * @throws Mage_Core_Exception
564:      */
565:     public function denyPayment(Mage_Payment_Model_Info $payment)
566:     {
567:         if (!$this->canReviewPayment($payment)) {
568:             Mage::throwException(Mage::helper('payment')->__('The payment review action is unavailable.'));
569:         }
570:         return false;
571:     }
572: 
573:     /**
574:      * Retrieve payment method title
575:      *
576:      * @return string
577:      */
578:     public function getTitle()
579:     {
580:         return $this->getConfigData('title');
581:     }
582: 
583:     /**
584:      * Retrieve information from payment configuration
585:      *
586:      * @param string $field
587:      * @param int|string|null|Mage_Core_Model_Store $storeId
588:      *
589:      * @return mixed
590:      */
591:     public function getConfigData($field, $storeId = null)
592:     {
593:         if (null === $storeId) {
594:             $storeId = $this->getStore();
595:         }
596:         $path = 'payment/'.$this->getCode().'/'.$field;
597:         return Mage::getStoreConfig($path, $storeId);
598:     }
599: 
600:     /**
601:      * Assign data to info model instance
602:      *
603:      * @param   mixed $data
604:      * @return  Mage_Payment_Model_Info
605:      */
606:     public function assignData($data)
607:     {
608:         if (is_array($data)) {
609:             $this->getInfoInstance()->addData($data);
610:         }
611:         elseif ($data instanceof Varien_Object) {
612:             $this->getInfoInstance()->addData($data->getData());
613:         }
614:         return $this;
615:     }
616: 
617:    /**
618:      * Parepare info instance for save
619:      *
620:      * @return Mage_Payment_Model_Abstract
621:      */
622:     public function prepareSave()
623:     {
624:         return $this;
625:     }
626: 
627:     /**
628:      * Check whether payment method can be used
629:      *
630:      * TODO: payment method instance is not supposed to know about quote
631:      *
632:      * @param Mage_Sales_Model_Quote|null $quote
633:      *
634:      * @return bool
635:      */
636:     public function isAvailable($quote = null)
637:     {
638:         $checkResult = new StdClass;
639:         $isActive = (bool)(int)$this->getConfigData('active', $quote ? $quote->getStoreId() : null);
640:         $checkResult->isAvailable = $isActive;
641:         $checkResult->isDeniedInConfig = !$isActive; // for future use in observers
642:         Mage::dispatchEvent('payment_method_is_active', array(
643:             'result'          => $checkResult,
644:             'method_instance' => $this,
645:             'quote'           => $quote,
646:         ));
647: 
648:         // disable method if it cannot implement recurring profiles management and there are recurring items in quote
649:         if ($checkResult->isAvailable) {
650:             $implementsRecurring = $this->canManageRecurringProfiles();
651:             // the $quote->hasRecurringItems() causes big performance impact, thus it has to be called last
652:             if ($quote && !$implementsRecurring && $quote->hasRecurringItems()) {
653:                 $checkResult->isAvailable = false;
654:             }
655:         }
656:         return $checkResult->isAvailable;
657:     }
658: 
659:     /**
660:      * Method that will be executed instead of authorize or capture
661:      * if flag isInitializeNeeded set to true
662:      *
663:      * @param string $paymentAction
664:      * @param object $stateObject
665:      *
666:      * @return Mage_Payment_Model_Abstract
667:      */
668:     public function initialize($paymentAction, $stateObject)
669:     {
670:         return $this;
671:     }
672: 
673:     /**
674:      * Get config payment action url
675:      * Used to universalize payment actions when processing payment place
676:      *
677:      * @return string
678:      */
679:     public function getConfigPaymentAction()
680:     {
681:         return $this->getConfigData('payment_action');
682:     }
683: 
684:     /**
685:      * Log debug data to file
686:      *
687:      * @param mixed $debugData
688:      */
689:     protected function _debug($debugData)
690:     {
691:         if ($this->getDebugFlag()) {
692:             Mage::getModel('core/log_adapter', 'payment_' . $this->getCode() . '.log')
693:                ->setFilterDataKeys($this->_debugReplacePrivateDataKeys)
694:                ->log($debugData);
695:         }
696:     }
697: 
698:     /**
699:      * Define if debugging is enabled
700:      *
701:      * @return bool
702:      */
703:     public function getDebugFlag()
704:     {
705:         return $this->getConfigData('debug');
706:     }
707: 
708:     /**
709:      * Used to call debug method from not Payment Method context
710:      *
711:      * @param mixed $debugData
712:      */
713:     public function debugData($debugData)
714:     {
715:         $this->_debug($debugData);
716:     }
717: }
718: