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  * @return array of contributions, if error an array with an error id and error message
 206  * @static void
 207  * @access public
 208  * {@getfields Contribution_get}
 209  * @example ContributionGet.php
 210  */
 211 function civicrm_api3_contribution_get($params) {
 212
 213   $mode = CRM_Contact_BAO_Query::MODE_CONTRIBUTE;
 214   $entity = 'contribution';
 215   list($dao, $query) = _civicrm_api3_get_query_object($params, $mode, $entity);
 216
 217   $contribution = array();
 218   while ($dao->fetch()) {
 219     //CRM-8662
 220     $contribution_details = $query->store($dao);
 221     $softContribution = CRM_Contribute_BAO_ContributionSoft::getSoftContribution($dao->contribution_id , TRUE);
 222     $contribution[$dao->contribution_id] = array_merge($contribution_details, $softContribution);
 223     if(isset($contribution[$dao->contribution_id]['financial_type_id'])){
 224       $contribution[$dao->contribution_id]['financial_type_id'] = $contribution[$dao->contribution_id]['financial_type_id'];
 225     }
 226     // format soft credit for backward compatibility
 227     _civicrm_api3_format_soft_credit($contribution[$dao->contribution_id]);
 228   }
 229   return civicrm_api3_create_success($contribution, $params, 'contribution', 'get', $dao);
 230 }
 231
 232 /**
 233  * This function is used to format the soft credit for backward compatibility
 234  * as of v4.4 we support multiple soft credit, so now contribution returns array with 'soft_credit' as key
 235  * but we still return first soft credit as a part of contribution array
 236  */
 237 function _civicrm_api3_format_soft_credit(&$contribution) {
 238   if (!empty($contribution['soft_credit'])) {
 239     $contribution['soft_credit_to'] = $contribution['soft_credit'][1]['contact_id'];
 240     $contribution['soft_credit_id'] = $contribution['soft_credit'][1]['soft_credit_id'];
 241   }
 242 }
 243
 244 /**
 245  * Adjust Metadata for Get action
 246  *
 247  * The metadata is used for setting defaults, documentation & validation
 248  * @param array $params array or parameters determined by getfields
 249  */
 250 function _civicrm_api3_contribution_get_spec(&$params) {
 251   $params['contribution_test']['api.default'] = 0;
 252   $params['contribution_test']['title'] = 'Get Test Contributions?';
 253   $params['financial_type_id']['api.aliases'] = array('contribution_type_id');
 254   $params['contact_id'] = $params['contribution_contact_id'];
 255   $params['contact_id']['api.aliases'] = array('contribution_contact_id');
 256   unset($params['contribution_contact_id']);
 257 }
 258
 259 /**
 260  * take the input parameter list as specified in the data model and
 261  * convert it into the same format that we use in QF and BAO object
 262  *
 263  * @param array $params Associative array of property name/value
 264  * pairs to insert in new contact.
 265  * @param array $values The reformatted properties that we can use internally
 266  * '
 267  *
 268  * @param bool $create
 269  *
 270  * @return array|CRM_Error
 271  * @access public
 272  */
 273 function _civicrm_api3_contribute_format_params($params, &$values, $create = FALSE) {
 274 //legacy way of formatting from v2 api - v3 way is to define metadata & do it in the api layer
 275   _civicrm_api3_filter_fields_for_bao('Contribution', $params, $values);
 276   return array();
 277 }
 278
 279 /**
 280  * Adjust Metadata for Transact action
 281  *
 282  * The metadata is used for setting defaults, documentation & validation
 283  * @param array $params array or parameters determined by getfields
 284  */
 285 function _civicrm_api3_contribution_transact_spec(&$params) {
 286   $fields = civicrm_api3('contribution', 'getfields', array('action' => 'create'));
 287   $params = array_merge($params, $fields['values']);
 288   $params['receive_date']['api.default'] = 'now';
 289 }
 290
 291 /**
 292  * Process a transaction and record it against the contact.
 293  *
 294  * @param  array   $params           (reference ) input parameters
 295  *
 296  * @return array (reference )        contribution of created or updated record (or a civicrm error)
 297  * @static void
 298  * @access public
 299  *
 300  */
 301 function civicrm_api3_contribution_transact($params) {
 302   // Set some params specific to payment processing
 303   $params['payment_processor_mode'] = empty($params['is_test']) ? 'live' : 'test';
 304   $params['amount'] = $params['total_amount'];
 305   if (!isset($params['net_amount'])) {
 306     $params['net_amount'] = $params['amount'];
 307   }
 308   if (!isset($params['invoiceID']) && isset($params['invoice_id'])) {
 309     $params['invoiceID'] = $params['invoice_id'];
 310   }
 311
 312   $paymentProcessor = CRM_Financial_BAO_PaymentProcessor::getPayment($params['payment_processor'], $params['payment_processor_mode']);
 313   if (civicrm_error($paymentProcessor)) {
 314     return $paymentProcessor;
 315   }
 316
 317   $payment = CRM_Core_Payment::singleton($params['payment_processor_mode'], $paymentProcessor);
 318   if (civicrm_error($payment)) {
 319     return $payment;
 320   }
 321
 322   $transaction = $payment->doDirectPayment($params);
 323   if (civicrm_error($transaction)) {
 324     return $transaction;
 325   }
 326
 327   // but actually, $payment->doDirectPayment() doesn't return a
 328   // CRM_Core_Error by itself
 329   if (is_object($transaction) && get_class($transaction) == 'CRM_Core_Error') {
 330     $errs = $transaction->getErrors();
 331     if (!empty($errs)) {
 332       $last_error = array_shift($errs);
 333       return CRM_Core_Error::createApiError($last_error['message']);
 334     }
 335   }
 336   $params['payment_instrument_id'] = CRM_Core_DAO::getFieldValue('CRM_Financial_DAO_PaymentProcessorType', $paymentProcessor['payment_processor_type_id'], 'payment_type') == 1 ? 'Credit Card' : 'Debit Card';
 337   return civicrm_api('contribution', 'create', $params);
 338 }
 339
 340 /**
 341  * Send a contribution confirmation (receipt or invoice)
 342  * The appropriate online template will be used (the existence of related objects
 343  * (e.g. memberships ) will affect this selection
 344  *
 345  * @param array $params input parameters
 346  * {@getfields Contribution_sendconfirmation}
 347  *
 348  * @throws Exception
 349  * @return array  Api result array
 350  * @static void
 351  * @access public
 352  */
 353 function civicrm_api3_contribution_sendconfirmation($params) {
 354   $contribution = new CRM_Contribute_BAO_Contribution();
 355   $contribution->id = $params['id'];
 356   if (! $contribution->find(TRUE)) {
 357     throw new Exception('Contribution does not exist');
 358 }
 359   $input = $ids = $cvalues = array('receipt_from_email' => $params['receipt_from_email']);
 360   $contribution->loadRelatedObjects($input, $ids, FALSE, TRUE);
 361   $contribution->composeMessageArray($input, $ids, $cvalues, FALSE, FALSE);
 362 }
 363
 364 /**
 365  * Adjust Metadata for sendconfirmation action
 366  *
 367  * The metadata is used for setting defaults, documentation & validation
 368  * @param array $params array or parameters determined by getfields
 369  */
 370 function _civicrm_api3_contribution_sendconfirmation_spec(&$params) {
 371   $params['id'] = array(
 372     'api.required' => 1,
 373     'title' => 'Contribution ID'
 374   );
 375   $params['receipt_from_email'] = array(
 376     'api.required' =>1,
 377     'title' => 'From Email address (string) required until someone provides a patch :-)',
 378   );
 379   $params['receipt_from_name'] = array(
 380     'title' => 'From Name (string)',
 381   );
 382   $params['cc_receipt'] = array(
 383     'title' => 'CC Email address (string)',
 384   );
 385   $params['bcc_receipt'] = array(
 386     'title' => 'BCC Email address (string)',
 387   );
 388   $params['receipt_text'] = array(
 389     'title' => 'Message (string)',
 390   );
 391 }
 392
 393 /**
 394  * Complete an existing (pending) transaction, updating related entities (participant, membership, pledge etc)
 395  * and taking any complete actions from the contribution page (e.g. send receipt)
 396  *
 397  * @todo - most of this should live in the BAO layer but as we want it to be an addition
 398  * to 4.3 which is already stable we should add it to the api layer & re-factor into the BAO layer later
 399  *
 400  * @param array $params input parameters
 401  * {@getfields Contribution_completetransaction}
 402  *
 403  * @throws API_Exception
 404  * @return array  Api result array
 405  * @static void
 406  * @access public
 407  */
 408 function civicrm_api3_contribution_completetransaction(&$params) {
 409
 410   $input = $ids = array();
 411   $contribution = new CRM_Contribute_BAO_Contribution();
 412   $contribution->id = $params['id'];
 413   $contribution->find(TRUE);
 414   if(!$contribution->id == $params['id']){
 415     throw new API_Exception('A valid contribution ID is required', 'invalid_data');
 416   }
 417   try {
 418     if(!$contribution->loadRelatedObjects($input, $ids, FALSE, TRUE)){
 419       throw new API_Exception('failed to load related objects');
 420     }
 421     elseif ($contribution->contribution_status_id == CRM_Core_OptionGroup::getValue('contribution_status', 'Completed', 'name')) {
 422       throw new API_Exception(ts('Contribution already completed'));
 423     }
 424     $objects = $contribution->_relatedObjects;
 425     $objects['contribution'] = &$contribution;
 426     $input['component'] = $contribution->_component;
 427     $input['is_test'] = $contribution->is_test;
 428     $input['trxn_id']= !empty($params['trxn_id']) ? $params['trxn_id'] : $contribution->trxn_id;
 429     $input['amount'] = $contribution->total_amount;
 430     if(isset($params['is_email_receipt'])){
 431       $input['is_email_receipt'] = $params['is_email_receipt'];
 432     }
 433     // @todo required for base ipn but problematic as api layer handles this
 434     $transaction = new CRM_Core_Transaction();
 435     $ipn = new CRM_Core_Payment_BaseIPN();
 436     $ipn->completeTransaction($input, $ids, $objects, $transaction, !empty($contribution->contribution_recur_id));
 437   }
 438   catch(Exception $e) {
 439     throw new API_Exception('failed to load related objects' . $e->getMessage() . "\n" . $e->getTraceAsString());
 440   }
 441 }
 442
 443 /**
 444  * provide function metadata
 445  * @param array $params
 446  */
 447 function _civicrm_api3_contribution_completetransaction_spec(&$params) {
 448   $params['id'] = array(
 449     'title' => 'Contribution ID',
 450     'type' => CRM_Utils_Type::T_INT,
 451     'api.required' => TRUE,
 452   );
 453   $params['trxn_id'] = array(
 454     'title' => 'Transaction ID',
 455     'type' => CRM_Utils_Type::T_STRING,
 456   );
 457   $params['is_email_receipt'] = array(
 458     'title' => 'Send email Receipt?',
 459     'type' => CRM_Utils_Type::T_BOOLEAN,
 460   );
 461 }