api/v3/Contribution.php

   1 <?php
   2
   3 /*
   4  +--------------------------------------------------------------------+
   5  | CiviCRM version 4.5                                                |
   6  +--------------------------------------------------------------------+
   7  | Copyright CiviCRM LLC (c) 2004-2014                                |
   8  +--------------------------------------------------------------------+
   9  | This file is a part of CiviCRM.                                    |
  10  |                                                                    |
  11  | CiviCRM is free software; you can copy, modify, and distribute it  |
  12  | under the terms of the GNU Affero General Public License           |
  13  | Version 3, 19 November 2007 and the CiviCRM Licensing Exception.   |
  14  |                                                                    |
  15  | CiviCRM is distributed in the hope that it will be useful, but     |
  16  | WITHOUT ANY WARRANTY; without even the implied warranty of         |
  17  | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.               |
  18  | See the GNU Affero General Public License for more details.        |
  19  |                                                                    |
  20  | You should have received a copy of the GNU Affero General Public   |
  21  | License and the CiviCRM Licensing Exception along                  |
  22  | with this program; if not, contact CiviCRM LLC                     |
  23  | at info[AT]civicrm[DOT]org. If you have questions about the        |
  24  | GNU Affero General Public License or the licensing of CiviCRM,     |
  25  | see the CiviCRM license FAQ at http://civicrm.org/licensing        |
  26  +--------------------------------------------------------------------+
  27 */
  28
  29 /**
  30  * File for the CiviCRM APIv3 Contribution functions
  31  *
  32  * @package CiviCRM_APIv3
  33  * @subpackage API_Contribute
  34  *
  35  * @copyright CiviCRM LLC (c) 2004-2014
  36  * @version $Id: Contribution.php 30486 2010-11-02 16:12:09Z shot $
  37  *
  38  */
  39
  40 /**
  41  * Add or update a contribution
  42  *
  43  * @param  array $params (reference ) input parameters
  44  *
  45  * @throws API_Exception
  46  * @return array  Api result array
  47  * @static void
  48  * @access public
  49  * @example ContributionCreate.php
  50  * {@getfields Contribution_create}
  51  */
  52 function civicrm_api3_contribution_create(&$params) {
  53   $values = array();
  54   _civicrm_api3_custom_format_params($params, $values, 'Contribution');
  55   $params = array_merge($params, $values);
  56
  57   if (!empty($params['id']) && !empty($params['contribution_status_id'])) {
  58     $error = array();
  59     //throw error for invalid status change such as setting completed back to pending
  60     //@todo this sort of validation belongs in the BAO not the API - if it is not an OK
  61     // action it needs to be blocked there. If it is Ok through a form it needs to be OK through the api
  62     CRM_Contribute_BAO_Contribution::checkStatusValidation(NULL, $params, $error);
  63     if (array_key_exists('contribution_status_id', $error)) {
  64       throw new API_Exception($error['contribution_status_id']);
  65     }
  66   }
  67
  68   _civicrm_api3_contribution_create_legacy_support_45($params);
  69
  70   // make sure tax calculation is handled via api
  71   $params = CRM_Contribute_BAO_Contribution::checkTaxAmount($params);
  72
  73   return _civicrm_api3_basic_create(_civicrm_api3_get_BAO(__FUNCTION__), $params, 'Contribution');
  74 }
  75
  76 /**
  77  * Adjust Metadata for Create action
  78  *
  79  * The metadata is used for setting defaults, documentation & validation
  80  * @param array $params array or parameters determined by getfields
  81  */
  82 function _civicrm_api3_contribution_create_spec(&$params) {
  83   $params['contact_id']['api.required'] = 1;
  84   $params['total_amount']['api.required'] = 1;
  85   $params['payment_instrument_id']['api.aliases'] = array('payment_instrument');
  86   $params['receive_date']['api.default'] = 'now';
  87   $params['payment_processor'] = array(
  88     'name' => 'payment_processor',
  89     'title' => 'Payment Processor ID',
  90     'description' => 'ID of payment processor used for this contribution',
  91     // field is called payment processor - not payment processor id but can only be one id so
  92     // it seems likely someone will fix it up one day to be more consistent - lets alias it from the start
  93     'api.aliases' => array('payment_processor_id'),
  94   );
  95   $params['financial_type_id']['api.aliases'] = array('contribution_type_id', 'contribution_type');
  96   $params['financial_type_id']['api.required'] = 1;
  97   $params['note'] = array(
  98     'name' => 'note',
  99     'uniqueName' => 'contribution_note',
 100     'title' => 'note',
 101     'type' => 2,
 102     'description' => 'Associated Note in the notes table',
 103   );
 104   $params['soft_credit_to'] = array(
 105     'name' => 'soft_credit_to',
 106     'title' => 'Soft Credit contact ID (legacy)',
 107     'type' => 1,
 108     'description' => 'ID of Contact to be Soft credited to (deprecated - use contribution_soft api)',
 109     'FKClassName' => 'CRM_Contact_DAO_Contact',
 110   );
 111   $params['honor_contact_id'] = array(
 112     'name' => 'honor_contact_id',
 113     'title' => 'Honoree contact ID (legacy)',
 114     'type' => 1,
 115     'description' => 'ID of honoree contact (deprecated - use contribution_soft api)',
 116     'FKClassName' => 'CRM_Contact_DAO_Contact',
 117   );
 118   $params['honor_type_id'] = array(
 119     'name' => 'honor_type_id',
 120     'title' => 'Honoree Type (legacy)',
 121     'type' => 1,
 122     'description' => 'Type of honoree contact (deprecated - use contribution_soft api)',
 123     'pseudoconstant' => TRUE,
 124   );
 125   // note this is a recommended option but not adding as a default to avoid
 126   // creating unnecessary changes for the dev
 127   $params['skipRecentView'] = array(
 128     'name' => 'skipRecentView',
 129     'title' => 'Skip adding to recent view',
 130     'type' => CRM_Utils_Type::T_BOOLEAN,
 131     'description' => 'Do not add to recent view (setting this improves performance)',
 132   );
 133   $params['skipLineItem'] = array(
 134     'name' => 'skipLineItem',
 135     'title' => 'Skip adding line items',
 136     'type' => 1,
 137     'api.default' => 0,
 138     'description' => 'Do not add line items by default (if you wish to add your own)',
 139   );
 140   $params['batch_id'] = array(
 141     'title' => 'Batch',
 142     'type' => 1,
 143     'description' => 'Batch which relevant transactions should be added to',
 144   );
 145 }
 146
 147 /**
 148 * Support for schema changes made in 4.5
 149 * The main purpose of the API is to provide integrators a level of stability not provided by
 150 * the core code or schema - this means we have to provide support for api calls (where possible)
 151 * across schema changes.
 152 */
 153 function _civicrm_api3_contribution_create_legacy_support_45(&$params){
 154   //legacy soft credit handling - recommended approach is chaining
 155   if(!empty($params['soft_credit_to'])){
 156     $params['soft_credit'][] = array(
 157       'contact_id'          => $params['soft_credit_to'],
 158       'amount'              => $params['total_amount'],
 159       'soft_credit_type_id' => CRM_Core_OptionGroup::getDefaultValue("soft_credit_type")
 160     );
 161   }
 162   if(!empty($params['honor_contact_id'])){
 163     $params['soft_credit'][] = array(
 164       'contact_id'          => $params['honor_contact_id'],
 165       'amount'              => $params['total_amount'],
 166       'soft_credit_type_id' => CRM_Utils_Array::value('honor_type_id', $params, CRM_Core_OptionGroup::getValue('soft_credit_type', 'in_honor_of', 'name'))
 167     );
 168   }
 169 }
 170
 171 /**
 172  * Delete a contribution
 173  *
 174  * @param  array   $params           (reference ) input parameters
 175  *
 176  * @return boolean        true if success, else false
 177  * @static void
 178  * @access public
 179  * {@getfields Contribution_delete}
 180  * @example ContributionDelete.php
 181  */
 182 function civicrm_api3_contribution_delete($params) {
 183
 184   $contributionID = !empty($params['contribution_id']) ? $params['contribution_id'] : $params['id'];
 185   if (CRM_Contribute_BAO_Contribution::deleteContribution($contributionID)) {
 186     return civicrm_api3_create_success(array($contributionID => 1));
 187   }
 188   else {
 189     return civicrm_api3_create_error('Could not delete contribution');
 190   }
 191 }
 192
 193 /**
 194  * modify metadata. Legacy support for contribution_id
 195  */
 196 function _civicrm_api3_contribution_delete_spec(&$params) {
 197   $params['id']['api.aliases'] = array('contribution_id');
 198 }
 199
 200 /**
 201  * Retrieve a set of contributions, given a set of input params
 202  *
 203  * @param  array $params (reference ) input parameters
 204  *
 205  * @internal param array $returnProperties Which properties should be included in the
 206  * returned Contribution object. If NULL, the default
 207  * set of properties will be included.
 208  *
 209  * @return array (reference )        array of contributions, if error an array with an error id and error message
 210  * @static void
 211  * @access public
 212  * {@getfields Contribution_get}
 213  * @example ContributionGet.php
 214  */
 215 function civicrm_api3_contribution_get($params) {
 216
 217   $mode = CRM_Contact_BAO_Query::MODE_CONTRIBUTE;
 218   $entity = 'contribution';
 219   list($dao, $query) = _civicrm_api3_get_query_object($params, $mode, $entity);
 220
 221   $contribution = array();
 222   while ($dao->fetch()) {
 223     //CRM-8662
 224     $contribution_details = $query->store($dao);
 225     $softContribution = CRM_Contribute_BAO_ContributionSoft::getSoftContribution($dao->contribution_id , TRUE);
 226     $contribution[$dao->contribution_id] = array_merge($contribution_details, $softContribution);
 227     if(isset($contribution[$dao->contribution_id]['financial_type_id'])){
 228       $contribution[$dao->contribution_id]['financial_type_id'] = $contribution[$dao->contribution_id]['financial_type_id'];
 229     }
 230     // format soft credit for backward compatibility
 231     _civicrm_api3_format_soft_credit($contribution[$dao->contribution_id]);
 232   }
 233   return civicrm_api3_create_success($contribution, $params, 'contribution', 'get', $dao);
 234 }
 235
 236 /**
 237  * This function is used to format the soft credit for backward compatibility
 238  * as of v4.4 we support multiple soft credit, so now contribution returns array with 'soft_credit' as key
 239  * but we still return first soft credit as a part of contribution array
 240  */
 241 function _civicrm_api3_format_soft_credit(&$contribution) {
 242   if (!empty($contribution['soft_credit'])) {
 243     $contribution['soft_credit_to'] = $contribution['soft_credit'][1]['contact_id'];
 244     $contribution['soft_credit_id'] = $contribution['soft_credit'][1]['soft_credit_id'];
 245   }
 246 }
 247
 248 /**
 249  * Adjust Metadata for Get action
 250  *
 251  * The metadata is used for setting defaults, documentation & validation
 252  * @param array $params array or parameters determined by getfields
 253  */
 254 function _civicrm_api3_contribution_get_spec(&$params) {
 255   $params['contribution_test']['api.default'] = 0;
 256   $params['contribution_test']['title'] = 'Get Test Contributions?';
 257   $params['financial_type_id']['api.aliases'] = array('contribution_type_id');
 258   $params['contact_id'] = $params['contribution_contact_id'];
 259   $params['contact_id']['api.aliases'] = array('contribution_contact_id');
 260   unset($params['contribution_contact_id']);
 261 }
 262
 263 /**
 264  * take the input parameter list as specified in the data model and
 265  * convert it into the same format that we use in QF and BAO object
 266  *
 267  * @param array $params Associative array of property name/value
 268  * pairs to insert in new contact.
 269  * @param array $values The reformatted properties that we can use internally
 270  * '
 271  *
 272  * @param bool $create
 273  *
 274  * @return array|CRM_Error
 275  * @access public
 276  */
 277 function _civicrm_api3_contribute_format_params($params, &$values, $create = FALSE) {
 278 //legacy way of formatting from v2 api - v3 way is to define metadata & do it in the api layer
 279   _civicrm_api3_filter_fields_for_bao('Contribution', $params, $values);
 280   return array();
 281 }
 282
 283 /**
 284  * Adjust Metadata for Transact action
 285  *
 286  * The metadata is used for setting defaults, documentation & validation
 287  * @param array $params array or parameters determined by getfields
 288  */
 289 function _civicrm_api3_contribution_transact_spec(&$params) {
 290   $fields = civicrm_api3('contribution', 'getfields', array('action' => 'create'));
 291   $params = array_merge($params, $fields['values']);
 292   $params['receive_date']['api.default'] = 'now';
 293 }
 294
 295 /**
 296  * Process a transaction and record it against the contact.
 297  *
 298  * @param  array   $params           (reference ) input parameters
 299  *
 300  * @return array (reference )        contribution of created or updated record (or a civicrm error)
 301  * @static void
 302  * @access public
 303  *
 304  */
 305 function civicrm_api3_contribution_transact($params) {
 306   // Set some params specific to payment processing
 307   $params['payment_processor_mode'] = empty($params['is_test']) ? 'live' : 'test';
 308   $params['amount'] = $params['total_amount'];
 309   if (!isset($params['net_amount'])) {
 310     $params['net_amount'] = $params['amount'];
 311   }
 312   if (!isset($params['invoiceID']) && isset($params['invoice_id'])) {
 313     $params['invoiceID'] = $params['invoice_id'];
 314   }
 315
 316   $paymentProcessor = CRM_Financial_BAO_PaymentProcessor::getPayment($params['payment_processor'], $params['payment_processor_mode']);
 317   if (civicrm_error($paymentProcessor)) {
 318     return $paymentProcessor;
 319   }
 320
 321   $payment = CRM_Core_Payment::singleton($params['payment_processor_mode'], $paymentProcessor);
 322   if (civicrm_error($payment)) {
 323     return $payment;
 324   }
 325
 326   $transaction = $payment->doDirectPayment($params);
 327   if (civicrm_error($transaction)) {
 328     return $transaction;
 329   }
 330
 331   // but actually, $payment->doDirectPayment() doesn't return a
 332   // CRM_Core_Error by itself
 333   if (is_object($transaction) && get_class($transaction) == 'CRM_Core_Error') {
 334     $errs = $transaction->getErrors();
 335     if (!empty($errs)) {
 336       $last_error = array_shift($errs);
 337       return CRM_Core_Error::createApiError($last_error['message']);
 338     }
 339   }
 340   $params['payment_instrument_id'] = CRM_Core_DAO::getFieldValue('CRM_Financial_DAO_PaymentProcessorType', $paymentProcessor['payment_processor_type_id'], 'payment_type') == 1 ? 'Credit Card' : 'Debit Card';
 341   return civicrm_api('contribution', 'create', $params);
 342 }
 343
 344 /**
 345  * Send a contribution confirmation (receipt or invoice)
 346  * The appropriate online template will be used (the existence of related objects
 347  * (e.g. memberships ) will affect this selection
 348  *
 349  * @param array $params input parameters
 350  * {@getfields Contribution_sendconfirmation}
 351  *
 352  * @throws Exception
 353  * @return array  Api result array
 354  * @static void
 355  * @access public
 356  */
 357 function civicrm_api3_contribution_sendconfirmation($params) {
 358   $contribution = new CRM_Contribute_BAO_Contribution();
 359   $contribution->id = $params['id'];
 360   if (! $contribution->find(TRUE)) {
 361     throw new Exception('Contribution does not exist');
 362 }
 363   $input = $ids = $cvalues = array('receipt_from_email' => $params['receipt_from_email']);
 364   $contribution->loadRelatedObjects($input, $ids, FALSE, TRUE);
 365   $contribution->composeMessageArray($input, $ids, $cvalues, FALSE, FALSE);
 366 }
 367
 368 /**
 369  * Adjust Metadata for sendconfirmation action
 370  *
 371  * The metadata is used for setting defaults, documentation & validation
 372  * @param array $params array or parameters determined by getfields
 373  */
 374 function _civicrm_api3_contribution_sendconfirmation_spec(&$params) {
 375   $params['id'] = array(
 376     'api.required' => 1,
 377     'title' => 'Contribution ID'
 378   );
 379   $params['receipt_from_email'] = array(
 380     'api.required' =>1,
 381     'title' => 'From Email address (string) required until someone provides a patch :-)',
 382   );
 383   $params['receipt_from_name'] = array(
 384     'title' => 'From Name (string)',
 385   );
 386   $params['cc_receipt'] = array(
 387     'title' => 'CC Email address (string)',
 388   );
 389   $params['bcc_receipt'] = array(
 390     'title' => 'BCC Email address (string)',
 391   );
 392   $params['receipt_text'] = array(
 393     'title' => 'Message (string)',
 394   );
 395 }
 396
 397 /**
 398  * Complete an existing (pending) transaction, updating related entities (participant, membership, pledge etc)
 399  * and taking any complete actions from the contribution page (e.g. send receipt)
 400  *
 401  * @todo - most of this should live in the BAO layer but as we want it to be an addition
 402  * to 4.3 which is already stable we should add it to the api layer & re-factor into the BAO layer later
 403  *
 404  * @param array $params input parameters
 405  * {@getfields Contribution_completetransaction}
 406  *
 407  * @throws API_Exception
 408  * @return array  Api result array
 409  * @static void
 410  * @access public
 411  */
 412 function civicrm_api3_contribution_completetransaction(&$params) {
 413
 414   $input = $ids = array();
 415   $contribution = new CRM_Contribute_BAO_Contribution();
 416   $contribution->id = $params['id'];
 417   $contribution->find(TRUE);
 418   if(!$contribution->id == $params['id']){
 419     throw new API_Exception('A valid contribution ID is required', 'invalid_data');
 420   }
 421   try {
 422     if(!$contribution->loadRelatedObjects($input, $ids, FALSE, TRUE)){
 423       throw new API_Exception('failed to load related objects');
 424     }
 425     elseif ($contribution->contribution_status_id == CRM_Core_OptionGroup::getValue('contribution_status', 'Completed', 'name')) {
 426       throw new API_Exception(ts('Contribution already completed'));
 427     }
 428     $objects = $contribution->_relatedObjects;
 429     $objects['contribution'] = &$contribution;
 430     $input['component'] = $contribution->_component;
 431     $input['is_test'] = $contribution->is_test;
 432     $input['trxn_id']= !empty($params['trxn_id']) ? $params['trxn_id'] : $contribution->trxn_id;
 433     $input['amount'] = $contribution->total_amount;
 434     if(isset($params['is_email_receipt'])){
 435       $input['is_email_receipt'] = $params['is_email_receipt'];
 436     }
 437     // @todo required for base ipn but problematic as api layer handles this
 438     $transaction = new CRM_Core_Transaction();
 439     $ipn = new CRM_Core_Payment_BaseIPN();
 440     $ipn->completeTransaction($input, $ids, $objects, $transaction, !empty($contribution->contribution_recur_id));
 441   }
 442   catch(Exception $e) {
 443     throw new API_Exception('failed to load related objects' . $e->getMessage() . "\n" . $e->getTraceAsString());
 444   }
 445 }
 446
 447 /**
 448  * provide function metadata
 449  * @param $params
 450  */
 451 function _civicrm_api3_contribution_completetransaction_spec(&$params) {
 452   $params['id'] = array(
 453     'title' => 'Contribution ID',
 454     'type' => CRM_Utils_Type::T_INT,
 455     'api.required' => TRUE,
 456   );
 457   $params['trxn_id'] = array(
 458     'title' => 'Transaction ID',
 459     'type' => CRM_Utils_Type::T_STRING,
 460   );
 461   $params['is_email_receipt'] = array(
 462     'title' => 'Send email Receipt?',
 463     'type' => CRM_Utils_Type::T_BOOLEAN,
 464   );
 465 }