Commit | Line | Data |
---|---|---|
6a488035 | 1 | <?php |
6a488035 TO |
2 | |
3 | /* | |
4 | +--------------------------------------------------------------------+ | |
731a0992 | 5 | | CiviCRM version 4.5 | |
6a488035 | 6 | +--------------------------------------------------------------------+ |
731a0992 | 7 | | Copyright CiviCRM LLC (c) 2004-2014 | |
6a488035 TO |
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 | * | |
731a0992 | 35 | * @copyright CiviCRM LLC (c) 2004-2014 |
6a488035 TO |
36 | * @version $Id: Contribution.php 30486 2010-11-02 16:12:09Z shot $ |
37 | * | |
38 | */ | |
39 | ||
40 | /** | |
41 | * Add or update a contribution | |
42 | * | |
69dbd1ba | 43 | * @param array $params (reference ) input parameters |
6a488035 | 44 | * |
69dbd1ba | 45 | * @throws API_Exception |
6a488035 TO |
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(); | |
6a488035 | 54 | _civicrm_api3_custom_format_params($params, $values, 'Contribution'); |
504a78f6 | 55 | $params = array_merge($params, $values); |
56 | ||
8cc574cf | 57 | if (!empty($params['id']) && !empty($params['contribution_status_id'])) { |
504a78f6 | 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 | } | |
6a488035 | 66 | } |
6a516bd6 DG |
67 | |
68 | _civicrm_api3_contribution_create_legacy_support_45($params); | |
69 | ||
21a3b46e | 70 | // make sure tax calculation is handled via api |
b5935203 | 71 | $params = CRM_Contribute_BAO_Contribution::checkTaxAmount($params); |
ebf2b57b | 72 | |
504a78f6 | 73 | return _civicrm_api3_basic_create(_civicrm_api3_get_BAO(__FUNCTION__), $params, 'Contribution'); |
6a488035 | 74 | } |
11e09c59 TO |
75 | |
76 | /** | |
6a488035 TO |
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; | |
53191813 | 85 | $params['payment_instrument_id']['api.aliases'] = array('payment_instrument'); |
8757a378 | 86 | $params['receive_date']['api.default'] = 'now'; |
6a488035 TO |
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', | |
33a429d4 | 106 | 'title' => 'Soft Credit contact ID (legacy)', |
6a488035 | 107 | 'type' => 1, |
33a429d4 | 108 | 'description' => 'ID of Contact to be Soft credited to (deprecated - use contribution_soft api)', |
6a488035 TO |
109 | 'FKClassName' => 'CRM_Contact_DAO_Contact', |
110 | ); | |
6a516bd6 DG |
111 | $params['honor_contact_id'] = array( |
112 | 'name' => 'honor_contact_id', | |
33a429d4 | 113 | 'title' => 'Honoree contact ID (legacy)', |
6a516bd6 | 114 | 'type' => 1, |
33a429d4 | 115 | 'description' => 'ID of honoree contact (deprecated - use contribution_soft api)', |
6a516bd6 DG |
116 | 'FKClassName' => 'CRM_Contact_DAO_Contact', |
117 | ); | |
33a429d4 CW |
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 | ); | |
6a488035 | 125 | // note this is a recommended option but not adding as a default to avoid |
c206647d | 126 | // creating unnecessary changes for the dev |
6a488035 TO |
127 | $params['skipRecentView'] = array( |
128 | 'name' => 'skipRecentView', | |
129 | 'title' => 'Skip adding to recent view', | |
0900b21e | 130 | 'type' => CRM_Utils_Type::T_BOOLEAN, |
6a488035 TO |
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 | ); | |
599c61ac E |
140 | $params['batch_id'] = array( |
141 | 'title' => 'Batch', | |
142 | 'type' => 1, | |
143 | 'description' => 'Batch which relevant transactions should be added to', | |
144 | ); | |
6a488035 TO |
145 | } |
146 | ||
6a516bd6 DG |
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'])){ | |
33a429d4 | 156 | $params['soft_credit'][] = array( |
6a516bd6 DG |
157 | 'contact_id' => $params['soft_credit_to'], |
158 | 'amount' => $params['total_amount'], | |
33a429d4 CW |
159 | 'soft_credit_type_id' => CRM_Core_OptionGroup::getDefaultValue("soft_credit_type") |
160 | ); | |
6a516bd6 DG |
161 | } |
162 | if(!empty($params['honor_contact_id'])){ | |
33a429d4 | 163 | $params['soft_credit'][] = array( |
6a516bd6 DG |
164 | 'contact_id' => $params['honor_contact_id'], |
165 | 'amount' => $params['total_amount'], | |
33a429d4 CW |
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 | ); | |
6a516bd6 DG |
168 | } |
169 | } | |
170 | ||
6a488035 TO |
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 | ||
0d8afee2 | 184 | $contributionID = !empty($params['contribution_id']) ? $params['contribution_id'] : $params['id']; |
6a488035 TO |
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 | } | |
11e09c59 TO |
192 | |
193 | /** | |
6a488035 TO |
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 | * | |
69dbd1ba EM |
203 | * @param array $params (reference ) input parameters |
204 | * | |
c490a46a | 205 | * @return array of contributions, if error an array with an error id and error message |
6a488035 TO |
206 | * @static void |
207 | * @access public | |
208 | * {@getfields Contribution_get} | |
209 | * @example ContributionGet.php | |
210 | */ | |
211 | function civicrm_api3_contribution_get($params) { | |
212 | ||
82f7d8b2 EM |
213 | $mode = CRM_Contact_BAO_Query::MODE_CONTRIBUTE; |
214 | $entity = 'contribution'; | |
215 | list($dao, $query) = _civicrm_api3_get_query_object($params, $mode, $entity); | |
6a488035 TO |
216 | |
217 | $contribution = array(); | |
218 | while ($dao->fetch()) { | |
219 | //CRM-8662 | |
76ca3345 KJ |
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); | |
a1c68fd2 | 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 | } | |
76ca3345 KJ |
226 | // format soft credit for backward compatibility |
227 | _civicrm_api3_format_soft_credit($contribution[$dao->contribution_id]); | |
6a488035 TO |
228 | } |
229 | return civicrm_api3_create_success($contribution, $params, 'contribution', 'get', $dao); | |
230 | } | |
11e09c59 | 231 | |
76ca3345 KJ |
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 | ||
11e09c59 | 244 | /** |
6a488035 TO |
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; | |
4c41ecb2 | 252 | $params['contribution_test']['title'] = 'Get Test Contributions?'; |
6a488035 TO |
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 | * | |
69dbd1ba | 263 | * @param array $params Associative array of property name/value |
6a488035 | 264 | * pairs to insert in new contact. |
69dbd1ba | 265 | * @param array $values The reformatted properties that we can use internally |
6a488035 TO |
266 | * ' |
267 | * | |
69dbd1ba EM |
268 | * @param bool $create |
269 | * | |
6a488035 TO |
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 | |
6a488035 | 275 | _civicrm_api3_filter_fields_for_bao('Contribution', $params, $values); |
6a488035 TO |
276 | return array(); |
277 | } | |
278 | ||
16c0ec8d CW |
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) { | |
4c41ecb2 EM |
286 | $fields = civicrm_api3('contribution', 'getfields', array('action' => 'create')); |
287 | $params = array_merge($params, $fields['values']); | |
16c0ec8d CW |
288 | $params['receive_date']['api.default'] = 'now'; |
289 | } | |
290 | ||
6a488035 TO |
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) { | |
16c0ec8d CW |
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']; | |
6a488035 TO |
305 | if (!isset($params['net_amount'])) { |
306 | $params['net_amount'] = $params['amount']; | |
307 | } | |
6a488035 TO |
308 | if (!isset($params['invoiceID']) && isset($params['invoice_id'])) { |
309 | $params['invoiceID'] = $params['invoice_id']; | |
310 | } | |
311 | ||
16c0ec8d | 312 | $paymentProcessor = CRM_Financial_BAO_PaymentProcessor::getPayment($params['payment_processor'], $params['payment_processor_mode']); |
6a488035 TO |
313 | if (civicrm_error($paymentProcessor)) { |
314 | return $paymentProcessor; | |
315 | } | |
316 | ||
16c0ec8d | 317 | $payment = CRM_Core_Payment::singleton($params['payment_processor_mode'], $paymentProcessor); |
6a488035 TO |
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 | |
16c0ec8d | 329 | if (is_object($transaction) && get_class($transaction) == 'CRM_Core_Error') { |
6a488035 TO |
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 | } | |
26ad2b72 | 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'; |
16c0ec8d | 337 | return civicrm_api('contribution', 'create', $params); |
6a488035 | 338 | } |
69dbd1ba | 339 | |
6a488035 TO |
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 | |
69dbd1ba | 344 | * |
6a488035 TO |
345 | * @param array $params input parameters |
346 | * {@getfields Contribution_sendconfirmation} | |
69dbd1ba EM |
347 | * |
348 | * @throws Exception | |
6a488035 TO |
349 | * @return array Api result array |
350 | * @static void | |
351 | * @access public | |
6a488035 TO |
352 | */ |
353 | function civicrm_api3_contribution_sendconfirmation($params) { | |
354 | $contribution = new CRM_Contribute_BAO_Contribution(); | |
355 | $contribution->id = $params['id']; | |
76ca3345 | 356 | if (! $contribution->find(TRUE)) { |
6a488035 TO |
357 | throw new Exception('Contribution does not exist'); |
358 | } | |
359 | $input = $ids = $cvalues = array('receipt_from_email' => $params['receipt_from_email']); | |
76ca3345 KJ |
360 | $contribution->loadRelatedObjects($input, $ids, FALSE, TRUE); |
361 | $contribution->composeMessageArray($input, $ids, $cvalues, FALSE, FALSE); | |
6a488035 TO |
362 | } |
363 | ||
11e09c59 | 364 | /** |
6a0cf2c6 | 365 | * Adjust Metadata for sendconfirmation action |
6a488035 TO |
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, | |
6a0cf2c6 CW |
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)', | |
6a488035 TO |
390 | ); |
391 | } | |
0efa8efe | 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} | |
69dbd1ba EM |
402 | * |
403 | * @throws API_Exception | |
0efa8efe | 404 | * @return array Api result array |
405 | * @static void | |
406 | * @access public | |
0efa8efe | 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 | } | |
1ba809f7 | 421 | elseif ($contribution->contribution_status_id == CRM_Core_OptionGroup::getValue('contribution_status', 'Completed', 'name')) { |
9e2ee07b EM |
422 | throw new API_Exception(ts('Contribution already completed')); |
423 | } | |
0efa8efe | 424 | $objects = $contribution->_relatedObjects; |
425 | $objects['contribution'] = &$contribution; | |
426 | $input['component'] = $contribution->_component; | |
427 | $input['is_test'] = $contribution->is_test; | |
eac25df2 | 428 | $input['trxn_id']= !empty($params['trxn_id']) ? $params['trxn_id'] : $contribution->trxn_id; |
0efa8efe | 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(); | |
f6780fb8 | 436 | $ipn->completeTransaction($input, $ids, $objects, $transaction, !empty($contribution->contribution_recur_id)); |
0efa8efe | 437 | } |
0e37ad72 | 438 | catch(Exception $e) { |
0efa8efe | 439 | throw new API_Exception('failed to load related objects' . $e->getMessage() . "\n" . $e->getTraceAsString()); |
440 | } | |
441 | } | |
442 | ||
aa1b1481 | 443 | /** |
3dfbdece | 444 | * provide function metadata |
c490a46a | 445 | * @param array $params |
aa1b1481 | 446 | */ |
3dfbdece | 447 | function _civicrm_api3_contribution_completetransaction_spec(&$params) { |
eac25df2 EM |
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 | ); | |
0efa8efe | 461 | } |