Commit | Line | Data |
---|---|---|
6a488035 | 1 | <?php |
6a488035 TO |
2 | /* |
3 | +--------------------------------------------------------------------+ | |
fee14197 | 4 | | CiviCRM version 5 | |
6a488035 | 5 | +--------------------------------------------------------------------+ |
6b83d5bd | 6 | | Copyright CiviCRM LLC (c) 2004-2019 | |
6a488035 TO |
7 | +--------------------------------------------------------------------+ |
8 | | This file is a part of CiviCRM. | | |
9 | | | | |
10 | | CiviCRM is free software; you can copy, modify, and distribute it | | |
11 | | under the terms of the GNU Affero General Public License | | |
12 | | Version 3, 19 November 2007 and the CiviCRM Licensing Exception. | | |
13 | | | | |
14 | | CiviCRM is distributed in the hope that it will be useful, but | | |
15 | | WITHOUT ANY WARRANTY; without even the implied warranty of | | |
16 | | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. | | |
17 | | See the GNU Affero General Public License for more details. | | |
18 | | | | |
19 | | You should have received a copy of the GNU Affero General Public | | |
20 | | License and the CiviCRM Licensing Exception along | | |
21 | | with this program; if not, contact CiviCRM LLC | | |
22 | | at info[AT]civicrm[DOT]org. If you have questions about the | | |
23 | | GNU Affero General Public License or the licensing of CiviCRM, | | |
24 | | see the CiviCRM license FAQ at http://civicrm.org/licensing | | |
25 | +--------------------------------------------------------------------+ | |
d25dd0ee | 26 | */ |
6a488035 TO |
27 | |
28 | /** | |
b081365f | 29 | * This api exposes CiviCRM Contribution records. |
6a488035 TO |
30 | * |
31 | * @package CiviCRM_APIv3 | |
6a488035 TO |
32 | */ |
33 | ||
34 | /** | |
244bbdd8 | 35 | * Add or update a Contribution. |
6a488035 | 36 | * |
cf470720 | 37 | * @param array $params |
9d32e6f7 | 38 | * Input parameters. |
6a488035 | 39 | * |
69dbd1ba | 40 | * @throws API_Exception |
a6c01b45 | 41 | * @return array |
72b3a70c | 42 | * Api result array |
6a488035 | 43 | */ |
1c31aa41 | 44 | function civicrm_api3_contribution_create($params) { |
cf8f0fff | 45 | $values = []; |
6a488035 | 46 | _civicrm_api3_custom_format_params($params, $values, 'Contribution'); |
504a78f6 | 47 | $params = array_merge($params, $values); |
83644f47 | 48 | // The BAO should not clean money - it should be done in the form layer & api wrapper |
49 | // (although arguably the api should expect pre-cleaned it seems to do some cleaning.) | |
4750ab01 | 50 | if (empty($params['skipCleanMoney'])) { |
51 | foreach (['total_amount', 'net_amount', 'fee_amount'] as $field) { | |
52 | if (isset($params[$field])) { | |
53 | $params[$field] = CRM_Utils_Rule::cleanMoney($params[$field]); | |
54 | } | |
55 | } | |
56 | } | |
83644f47 | 57 | $params['skipCleanMoney'] = TRUE; |
504a78f6 | 58 | |
ae2ade98 | 59 | if (!empty($params['check_permissions']) && CRM_Financial_BAO_FinancialType::isACLFinancialTypeStatus()) { |
3300bf67 | 60 | if (empty($params['id'])) { |
8715ff99 | 61 | $op = CRM_Core_Action::ADD; |
3300bf67 PN |
62 | } |
63 | else { | |
64 | if (empty($params['financial_type_id'])) { | |
f4a331f4 | 65 | $params['financial_type_id'] = CRM_Core_DAO::getFieldValue('CRM_Contribute_DAO_Contribution', $params['id'], 'financial_type_id'); |
3300bf67 | 66 | } |
8715ff99 | 67 | $op = CRM_Core_Action::UPDATE; |
3300bf67 PN |
68 | } |
69 | CRM_Financial_BAO_FinancialType::getAvailableFinancialTypes($types, $op); | |
70 | if (!in_array($params['financial_type_id'], array_keys($types))) { | |
ae2ade98 | 71 | throw new API_Exception('You do not have permission to create this contribution'); |
3300bf67 | 72 | } |
816cac04 | 73 | } |
8cc574cf | 74 | if (!empty($params['id']) && !empty($params['contribution_status_id'])) { |
cf8f0fff | 75 | $error = []; |
504a78f6 | 76 | //throw error for invalid status change such as setting completed back to pending |
77 | //@todo this sort of validation belongs in the BAO not the API - if it is not an OK | |
78 | // action it needs to be blocked there. If it is Ok through a form it needs to be OK through the api | |
79 | CRM_Contribute_BAO_Contribution::checkStatusValidation(NULL, $params, $error); | |
80 | if (array_key_exists('contribution_status_id', $error)) { | |
81 | throw new API_Exception($error['contribution_status_id']); | |
82 | } | |
6a488035 | 83 | } |
4d47ad17 | 84 | if (!empty($params['id']) && !empty($params['financial_type_id'])) { |
cf8f0fff | 85 | $error = []; |
4d47ad17 PN |
86 | CRM_Contribute_BAO_Contribution::checkFinancialTypeChange($params['financial_type_id'], $params['id'], $error); |
87 | if (array_key_exists('financial_type_id', $error)) { | |
88 | throw new API_Exception($error['financial_type_id']); | |
89 | } | |
90 | } | |
6a516bd6 DG |
91 | _civicrm_api3_contribution_create_legacy_support_45($params); |
92 | ||
504a78f6 | 93 | return _civicrm_api3_basic_create(_civicrm_api3_get_BAO(__FUNCTION__), $params, 'Contribution'); |
6a488035 | 94 | } |
11e09c59 TO |
95 | |
96 | /** | |
0aa0303c EM |
97 | * Adjust Metadata for Create action. |
98 | * | |
99 | * The metadata is used for setting defaults, documentation & validation. | |
6a488035 | 100 | * |
cf470720 | 101 | * @param array $params |
b081365f | 102 | * Array of parameters determined by getfields. |
6a488035 TO |
103 | */ |
104 | function _civicrm_api3_contribution_create_spec(&$params) { | |
105 | $params['contact_id']['api.required'] = 1; | |
106 | $params['total_amount']['api.required'] = 1; | |
cf8f0fff | 107 | $params['payment_instrument_id']['api.aliases'] = ['payment_instrument']; |
8757a378 | 108 | $params['receive_date']['api.default'] = 'now'; |
2b0fe7ac | 109 | $params['receive_date']['api.required'] = TRUE; |
cf8f0fff | 110 | $params['payment_processor'] = [ |
6a488035 TO |
111 | 'name' => 'payment_processor', |
112 | 'title' => 'Payment Processor ID', | |
113 | 'description' => 'ID of payment processor used for this contribution', | |
114 | // field is called payment processor - not payment processor id but can only be one id so | |
115 | // it seems likely someone will fix it up one day to be more consistent - lets alias it from the start | |
cf8f0fff | 116 | 'api.aliases' => ['payment_processor_id'], |
d142432b | 117 | 'type' => CRM_Utils_Type::T_INT, |
cf8f0fff CW |
118 | ]; |
119 | $params['financial_type_id']['api.aliases'] = ['contribution_type_id', 'contribution_type']; | |
6a488035 | 120 | $params['financial_type_id']['api.required'] = 1; |
cf8f0fff | 121 | $params['note'] = [ |
6a488035 TO |
122 | 'name' => 'note', |
123 | 'uniqueName' => 'contribution_note', | |
124 | 'title' => 'note', | |
125 | 'type' => 2, | |
126 | 'description' => 'Associated Note in the notes table', | |
cf8f0fff CW |
127 | ]; |
128 | $params['soft_credit_to'] = [ | |
6a488035 | 129 | 'name' => 'soft_credit_to', |
33a429d4 | 130 | 'title' => 'Soft Credit contact ID (legacy)', |
797d4c52 | 131 | 'type' => CRM_Utils_Type::T_INT, |
33a429d4 | 132 | 'description' => 'ID of Contact to be Soft credited to (deprecated - use contribution_soft api)', |
6a488035 | 133 | 'FKClassName' => 'CRM_Contact_DAO_Contact', |
cf8f0fff CW |
134 | ]; |
135 | $params['honor_contact_id'] = [ | |
6a516bd6 | 136 | 'name' => 'honor_contact_id', |
33a429d4 | 137 | 'title' => 'Honoree contact ID (legacy)', |
797d4c52 | 138 | 'type' => CRM_Utils_Type::T_INT, |
33a429d4 | 139 | 'description' => 'ID of honoree contact (deprecated - use contribution_soft api)', |
6a516bd6 | 140 | 'FKClassName' => 'CRM_Contact_DAO_Contact', |
cf8f0fff CW |
141 | ]; |
142 | $params['honor_type_id'] = [ | |
33a429d4 CW |
143 | 'name' => 'honor_type_id', |
144 | 'title' => 'Honoree Type (legacy)', | |
797d4c52 | 145 | 'type' => CRM_Utils_Type::T_INT, |
33a429d4 CW |
146 | 'description' => 'Type of honoree contact (deprecated - use contribution_soft api)', |
147 | 'pseudoconstant' => TRUE, | |
cf8f0fff | 148 | ]; |
6a488035 | 149 | // note this is a recommended option but not adding as a default to avoid |
c206647d | 150 | // creating unnecessary changes for the dev |
cf8f0fff | 151 | $params['skipRecentView'] = [ |
6a488035 TO |
152 | 'name' => 'skipRecentView', |
153 | 'title' => 'Skip adding to recent view', | |
0900b21e | 154 | 'type' => CRM_Utils_Type::T_BOOLEAN, |
6a488035 | 155 | 'description' => 'Do not add to recent view (setting this improves performance)', |
cf8f0fff CW |
156 | ]; |
157 | $params['skipLineItem'] = [ | |
6a488035 TO |
158 | 'name' => 'skipLineItem', |
159 | 'title' => 'Skip adding line items', | |
b3b7f4c5 | 160 | 'type' => CRM_Utils_Type::T_BOOLEAN, |
6a488035 TO |
161 | 'api.default' => 0, |
162 | 'description' => 'Do not add line items by default (if you wish to add your own)', | |
cf8f0fff CW |
163 | ]; |
164 | $params['batch_id'] = [ | |
599c61ac | 165 | 'title' => 'Batch', |
797d4c52 | 166 | 'type' => CRM_Utils_Type::T_INT, |
599c61ac | 167 | 'description' => 'Batch which relevant transactions should be added to', |
cf8f0fff CW |
168 | ]; |
169 | $params['refund_trxn_id'] = [ | |
797d4c52 | 170 | 'title' => 'Refund Transaction ID', |
171 | 'type' => CRM_Utils_Type::T_STRING, | |
172 | 'description' => 'Transaction ID specific to the refund taking place', | |
cf8f0fff CW |
173 | ]; |
174 | $params['card_type_id'] = [ | |
a55e39e9 | 175 | 'title' => 'Card Type ID', |
176 | 'description' => 'Providing Credit Card Type ID', | |
177 | 'type' => CRM_Utils_Type::T_INT, | |
cf8f0fff | 178 | 'pseudoconstant' => [ |
a55e39e9 | 179 | 'optionGroupName' => 'accept_creditcard', |
cf8f0fff CW |
180 | ], |
181 | ]; | |
6a488035 TO |
182 | } |
183 | ||
6a516bd6 | 184 | /** |
9d32e6f7 EM |
185 | * Support for schema changes made in 4.5. |
186 | * | |
35671d00 TO |
187 | * The main purpose of the API is to provide integrators a level of stability not provided by |
188 | * the core code or schema - this means we have to provide support for api calls (where possible) | |
189 | * across schema changes. | |
dc64d047 | 190 | * |
d0997921 | 191 | * @param array $params |
35671d00 | 192 | */ |
9b873358 | 193 | function _civicrm_api3_contribution_create_legacy_support_45(&$params) { |
6a516bd6 | 194 | //legacy soft credit handling - recommended approach is chaining |
9b873358 | 195 | if (!empty($params['soft_credit_to'])) { |
cf8f0fff | 196 | $params['soft_credit'][] = [ |
6a516bd6 DG |
197 | 'contact_id' => $params['soft_credit_to'], |
198 | 'amount' => $params['total_amount'], | |
21dfd5f5 | 199 | 'soft_credit_type_id' => CRM_Core_OptionGroup::getDefaultValue("soft_credit_type"), |
cf8f0fff | 200 | ]; |
6a516bd6 | 201 | } |
9b873358 | 202 | if (!empty($params['honor_contact_id'])) { |
cf8f0fff | 203 | $params['soft_credit'][] = [ |
6a516bd6 DG |
204 | 'contact_id' => $params['honor_contact_id'], |
205 | 'amount' => $params['total_amount'], | |
a28ce73f | 206 | 'soft_credit_type_id' => CRM_Utils_Array::value('honor_type_id', $params, CRM_Core_PseudoConstant::getKey('CRM_Contribute_BAO_ContributionSoft', 'soft_credit_type_id', 'in_honor_of')), |
cf8f0fff | 207 | ]; |
6a516bd6 DG |
208 | } |
209 | } | |
210 | ||
6a488035 | 211 | /** |
244bbdd8 | 212 | * Delete a Contribution. |
6a488035 | 213 | * |
cf470720 | 214 | * @param array $params |
9d32e6f7 | 215 | * Input parameters. |
6a488035 | 216 | * |
9d32e6f7 | 217 | * @return array |
ae2ade98 | 218 | * @throws \API_Exception |
6a488035 TO |
219 | */ |
220 | function civicrm_api3_contribution_delete($params) { | |
221 | ||
0d8afee2 | 222 | $contributionID = !empty($params['contribution_id']) ? $params['contribution_id'] : $params['id']; |
c93fecd1 E |
223 | // First check contribution financial type |
224 | $financialType = CRM_Core_DAO::getFieldValue('CRM_Contribute_DAO_Contribution', $contributionID, 'financial_type_id'); | |
c93fecd1 | 225 | // Now check permissioned lineitems & permissioned contribution |
ae2ade98 | 226 | if (!empty($params['check_permissions']) && CRM_Financial_BAO_FinancialType::isACLFinancialTypeStatus() && |
227 | ( | |
228 | !CRM_Core_Permission::check('delete contributions of type ' . CRM_Contribute_PseudoConstant::financialType($financialType)) | |
229 | || !CRM_Financial_BAO_FinancialType::checkPermissionedLineItems($contributionID, 'delete', FALSE) | |
230 | ) | |
66af7c48 | 231 | ) { |
ae2ade98 | 232 | throw new API_Exception('You do not have permission to delete this contribution'); |
c93fecd1 | 233 | } |
6a488035 | 234 | if (CRM_Contribute_BAO_Contribution::deleteContribution($contributionID)) { |
cf8f0fff | 235 | return civicrm_api3_create_success([$contributionID => 1]); |
6a488035 TO |
236 | } |
237 | else { | |
8744e9ce | 238 | throw new API_Exception('Could not delete contribution'); |
6a488035 TO |
239 | } |
240 | } | |
11e09c59 TO |
241 | |
242 | /** | |
9d32e6f7 EM |
243 | * Modify metadata for delete action. |
244 | * | |
245 | * Legacy support for contribution_id. | |
246 | * | |
d0997921 | 247 | * @param array $params |
6a488035 TO |
248 | */ |
249 | function _civicrm_api3_contribution_delete_spec(&$params) { | |
cf8f0fff | 250 | $params['id']['api.aliases'] = ['contribution_id']; |
6a488035 TO |
251 | } |
252 | ||
253 | /** | |
35823763 | 254 | * Retrieve a set of contributions. |
6a488035 | 255 | * |
cf470720 | 256 | * @param array $params |
35823763 | 257 | * Input parameters. |
69dbd1ba | 258 | * |
a6c01b45 | 259 | * @return array |
16b10e64 | 260 | * Array of contributions, if error an array with an error id and error message |
6a488035 TO |
261 | */ |
262 | function civicrm_api3_contribution_get($params) { | |
263 | ||
82f7d8b2 | 264 | $mode = CRM_Contact_BAO_Query::MODE_CONTRIBUTE; |
3123273f | 265 | $additionalOptions = _civicrm_api3_contribution_get_support_nonunique_returns($params); |
be81f101 | 266 | $returnProperties = CRM_Contribute_BAO_Query::defaultReturnProperties($mode); |
6a488035 | 267 | |
5062a7b3 | 268 | // Get the contributions based on parameters passed in |
3123273f | 269 | $contributions = _civicrm_api3_get_using_query_object('Contribution', $params, $additionalOptions, NULL, $mode, $returnProperties); |
5062a7b3 MWMC |
270 | if (!empty($contributions)) { |
271 | $softContributions = CRM_Contribute_BAO_ContributionSoft::getSoftCreditContributionFields(array_keys($contributions), TRUE); | |
272 | foreach ($contributions as $id => $contribution) { | |
273 | $contributions[$id] = isset($softContributions[$id]) ? array_merge($contribution, $softContributions[$id]) : $contribution; | |
274 | // format soft credit for backward compatibility | |
275 | _civicrm_api3_format_soft_credit($contributions[$id]); | |
276 | _civicrm_api3_contribution_add_supported_fields($contributions[$id]); | |
277 | } | |
6a488035 | 278 | } |
be81f101 | 279 | return civicrm_api3_create_success($contributions, $params, 'Contribution', 'get'); |
9ae25b56 | 280 | } |
281 | ||
3123273f | 282 | /** |
283 | * Fix the return values to reflect cases where the schema has been changed. | |
284 | * | |
285 | * At the query object level using uniquenames dismbiguates between tables. | |
286 | * | |
287 | * However, adding uniquename can change inputs accepted by the api, so we need | |
288 | * to ensure we are asking for the unique name return fields. | |
289 | * | |
290 | * @param array $params | |
291 | * | |
292 | * @return array | |
293 | * @throws \API_Exception | |
294 | */ | |
295 | function _civicrm_api3_contribution_get_support_nonunique_returns($params) { | |
cf8f0fff | 296 | $additionalOptions = []; |
3123273f | 297 | $options = _civicrm_api3_get_options_from_params($params, TRUE); |
6e7cc0f5 | 298 | foreach (['check_number', 'address_id', 'cancel_date'] as $changedVariable) { |
3123273f | 299 | if (isset($options['return']) && !empty($options['return'][$changedVariable])) { |
300 | $additionalOptions['return']['contribution_' . $changedVariable] = 1; | |
301 | } | |
302 | } | |
303 | return $additionalOptions; | |
304 | } | |
305 | ||
306 | /** | |
307 | * Support for supported output variables. | |
308 | * | |
309 | * @param $contribution | |
310 | */ | |
311 | function _civicrm_api3_contribution_add_supported_fields(&$contribution) { | |
312 | // These are output fields that are supported in our test contract. | |
313 | // Arguably we should also do the same with 'campaign_id' & | |
314 | // 'source' - which are also fields being rendered with unique names. | |
315 | // That seems more consistent with other api where we output the actual field names. | |
cf8f0fff | 316 | $outputAliases = [ |
3123273f | 317 | 'contribution_check_number' => 'check_number', |
318 | 'contribution_address_id' => 'address_id', | |
319 | 'payment_instrument_id' => 'instrument_id', | |
6e7cc0f5 | 320 | 'contribution_cancel_date' => 'cancel_date', |
cf8f0fff | 321 | ]; |
3123273f | 322 | foreach ($outputAliases as $returnName => $copyTo) { |
323 | if (array_key_exists($returnName, $contribution)) { | |
324 | $contribution[$copyTo] = $contribution[$returnName]; | |
325 | } | |
326 | } | |
327 | ||
328 | } | |
329 | ||
9ae25b56 | 330 | /** |
331 | * Get number of contacts matching the supplied criteria. | |
332 | * | |
333 | * @param array $params | |
334 | * | |
335 | * @return int | |
336 | */ | |
337 | function civicrm_api3_contribution_getcount($params) { | |
cf8f0fff | 338 | $count = _civicrm_api3_get_using_query_object('Contribution', $params, [], TRUE, CRM_Contact_BAO_Query::MODE_CONTRIBUTE); |
9ae25b56 | 339 | return (int) $count; |
6a488035 | 340 | } |
11e09c59 | 341 | |
76ca3345 | 342 | /** |
1747ab99 EM |
343 | * This function is used to format the soft credit for backward compatibility. |
344 | * | |
345 | * As of v4.4 we support multiple soft credit, so now contribution returns array with 'soft_credit' as key | |
76ca3345 | 346 | * but we still return first soft credit as a part of contribution array |
dc64d047 | 347 | * |
645ee340 | 348 | * @param $contribution |
76ca3345 KJ |
349 | */ |
350 | function _civicrm_api3_format_soft_credit(&$contribution) { | |
351 | if (!empty($contribution['soft_credit'])) { | |
352 | $contribution['soft_credit_to'] = $contribution['soft_credit'][1]['contact_id']; | |
353 | $contribution['soft_credit_id'] = $contribution['soft_credit'][1]['soft_credit_id']; | |
354 | } | |
355 | } | |
356 | ||
11e09c59 | 357 | /** |
1747ab99 | 358 | * Adjust Metadata for Get action. |
6a488035 | 359 | * |
0aa0303c EM |
360 | * The metadata is used for setting defaults, documentation & validation. |
361 | * | |
cf470720 | 362 | * @param array $params |
b081365f | 363 | * Array of parameters determined by getfields. |
6a488035 TO |
364 | */ |
365 | function _civicrm_api3_contribution_get_spec(&$params) { | |
cf8f0fff | 366 | $params['contribution_test'] = [ |
d142432b EM |
367 | 'api.default' => 0, |
368 | 'type' => CRM_Utils_Type::T_BOOLEAN, | |
369 | 'title' => 'Get Test Contributions?', | |
cf8f0fff CW |
370 | 'api.aliases' => ['is_test'], |
371 | ]; | |
739a8336 | 372 | |
cf8f0fff CW |
373 | $params['financial_type_id']['api.aliases'] = ['contribution_type_id']; |
374 | $params['payment_instrument_id']['api.aliases'] = ['contribution_payment_instrument', 'payment_instrument']; | |
03df80cf | 375 | $params['contact_id'] = CRM_Utils_Array::value('contribution_contact_id', $params); |
cf8f0fff | 376 | $params['contact_id']['api.aliases'] = ['contribution_contact_id']; |
6a488035 TO |
377 | unset($params['contribution_contact_id']); |
378 | } | |
379 | ||
380 | /** | |
1747ab99 EM |
381 | * Legacy handling for contribution parameters. |
382 | * | |
383 | * Take the input parameter list as specified in the data model and | |
384 | * convert it into the same format that we use in QF and BAO object. | |
6a488035 | 385 | * |
cf470720 | 386 | * @param array $params |
c23f45d3 | 387 | * property name/value pairs to insert in new contact. |
cf470720 TO |
388 | * @param array $values |
389 | * The reformatted properties that we can use internally. | |
6a488035 | 390 | * |
c23f45d3 | 391 | * @return array |
6a488035 | 392 | */ |
c23f45d3 | 393 | function _civicrm_api3_contribute_format_params($params, &$values) { |
35671d00 | 394 | //legacy way of formatting from v2 api - v3 way is to define metadata & do it in the api layer |
6a488035 | 395 | _civicrm_api3_filter_fields_for_bao('Contribution', $params, $values); |
cf8f0fff | 396 | return []; |
6a488035 TO |
397 | } |
398 | ||
16c0ec8d | 399 | /** |
1747ab99 | 400 | * Adjust Metadata for Transact action. |
16c0ec8d | 401 | * |
0aa0303c EM |
402 | * The metadata is used for setting defaults, documentation & validation. |
403 | * | |
cf470720 | 404 | * @param array $params |
b081365f | 405 | * Array of parameters determined by getfields. |
16c0ec8d CW |
406 | */ |
407 | function _civicrm_api3_contribution_transact_spec(&$params) { | |
cf8f0fff | 408 | $fields = civicrm_api3('Contribution', 'getfields', ['action' => 'create']); |
4c41ecb2 | 409 | $params = array_merge($params, $fields['values']); |
16c0ec8d CW |
410 | $params['receive_date']['api.default'] = 'now'; |
411 | } | |
412 | ||
6a488035 TO |
413 | /** |
414 | * Process a transaction and record it against the contact. | |
415 | * | |
cf470720 | 416 | * @param array $params |
1747ab99 | 417 | * Input parameters. |
6a488035 | 418 | * |
a6c01b45 | 419 | * @return array |
c23f45d3 | 420 | * contribution of created or updated record (or a civicrm error) |
6a488035 TO |
421 | */ |
422 | function civicrm_api3_contribution_transact($params) { | |
16c0ec8d | 423 | // Set some params specific to payment processing |
8319cf11 EM |
424 | // @todo - fix this function - none of the results checked by civicrm_error would ever be an array with |
425 | // 'is_error' set | |
426 | // also trxn_id is not saved. | |
427 | // but since there is no test it's not desirable to jump in & make the obvious changes. | |
16c0ec8d CW |
428 | $params['payment_processor_mode'] = empty($params['is_test']) ? 'live' : 'test'; |
429 | $params['amount'] = $params['total_amount']; | |
6a488035 TO |
430 | if (!isset($params['net_amount'])) { |
431 | $params['net_amount'] = $params['amount']; | |
432 | } | |
6a488035 TO |
433 | if (!isset($params['invoiceID']) && isset($params['invoice_id'])) { |
434 | $params['invoiceID'] = $params['invoice_id']; | |
435 | } | |
436 | ||
be06e507 CW |
437 | // Some payment processors expect a unique invoice_id - generate one if not supplied |
438 | $params['invoice_id'] = CRM_Utils_Array::value('invoice_id', $params, md5(uniqid(rand(), TRUE))); | |
439 | ||
16c0ec8d | 440 | $paymentProcessor = CRM_Financial_BAO_PaymentProcessor::getPayment($params['payment_processor'], $params['payment_processor_mode']); |
9d8f43b1 | 441 | $paymentProcessor['object']->doPayment($params); |
6a488035 | 442 | |
5a9f9519 O |
443 | $params['payment_instrument_id'] = $paymentProcessor['object']->getPaymentInstrumentID(); |
444 | ||
244bbdd8 | 445 | return civicrm_api('Contribution', 'create', $params); |
6a488035 | 446 | } |
69dbd1ba | 447 | |
6a488035 | 448 | /** |
1747ab99 EM |
449 | * Send a contribution confirmation (receipt or invoice). |
450 | * | |
6a488035 TO |
451 | * The appropriate online template will be used (the existence of related objects |
452 | * (e.g. memberships ) will affect this selection | |
69dbd1ba | 453 | * |
cf470720 TO |
454 | * @param array $params |
455 | * Input parameters. | |
69dbd1ba EM |
456 | * |
457 | * @throws Exception | |
6a488035 TO |
458 | */ |
459 | function civicrm_api3_contribution_sendconfirmation($params) { | |
cf8f0fff CW |
460 | $ids = $values = []; |
461 | $allowedParams = [ | |
ec7e3954 E |
462 | 'receipt_from_email', |
463 | 'receipt_from_name', | |
464 | 'receipt_update', | |
465 | 'cc_receipt', | |
466 | 'bcc_receipt', | |
467 | 'receipt_text', | |
468 | 'payment_processor_id', | |
cf8f0fff | 469 | ]; |
71687b3d | 470 | $input = array_intersect_key($params, array_flip($allowedParams)); |
55df1211 | 471 | $input['is_email_receipt'] = TRUE; |
ec7e3954 | 472 | CRM_Contribute_BAO_Contribution::sendMail($input, $ids, $params['id'], $values); |
6a488035 TO |
473 | } |
474 | ||
11e09c59 | 475 | /** |
1747ab99 | 476 | * Adjust Metadata for sendconfirmation action. |
6a488035 | 477 | * |
0aa0303c EM |
478 | * The metadata is used for setting defaults, documentation & validation. |
479 | * | |
cf470720 | 480 | * @param array $params |
b081365f | 481 | * Array of parameters determined by getfields. |
6a488035 TO |
482 | */ |
483 | function _civicrm_api3_contribution_sendconfirmation_spec(&$params) { | |
cf8f0fff | 484 | $params['id'] = [ |
6a488035 | 485 | 'api.required' => 1, |
ec7e3954 | 486 | 'title' => ts('Contribution ID'), |
d142432b | 487 | 'type' => CRM_Utils_Type::T_INT, |
cf8f0fff CW |
488 | ]; |
489 | $params['receipt_from_email'] = [ | |
ec7e3954 | 490 | 'title' => ts('From Email address (string)'), |
d142432b | 491 | 'type' => CRM_Utils_Type::T_STRING, |
cf8f0fff CW |
492 | ]; |
493 | $params['receipt_from_name'] = [ | |
ec7e3954 | 494 | 'title' => ts('From Name (string)'), |
d142432b | 495 | 'type' => CRM_Utils_Type::T_STRING, |
cf8f0fff CW |
496 | ]; |
497 | $params['cc_receipt'] = [ | |
ec7e3954 | 498 | 'title' => ts('CC Email address (string)'), |
d142432b | 499 | 'type' => CRM_Utils_Type::T_STRING, |
cf8f0fff CW |
500 | ]; |
501 | $params['bcc_receipt'] = [ | |
ec7e3954 | 502 | 'title' => ts('BCC Email address (string)'), |
d142432b | 503 | 'type' => CRM_Utils_Type::T_STRING, |
cf8f0fff CW |
504 | ]; |
505 | $params['receipt_text'] = [ | |
ec7e3954 | 506 | 'title' => ts('Message (string)'), |
d142432b | 507 | 'type' => CRM_Utils_Type::T_STRING, |
cf8f0fff CW |
508 | ]; |
509 | $params['receipt_update'] = [ | |
ec7e3954 E |
510 | 'title' => ts('Update the Receipt Date'), |
511 | 'type' => CRM_Utils_Type::T_BOOLEAN, | |
512 | 'api.default' => TRUE, | |
cf8f0fff CW |
513 | ]; |
514 | $params['payment_processor_id'] = [ | |
ec7e3954 E |
515 | 'title' => ts('Payment processor Id (avoids mis-guesses)'), |
516 | 'type' => CRM_Utils_Type::T_INT, | |
cf8f0fff | 517 | ]; |
6a488035 | 518 | } |
0efa8efe | 519 | |
520 | /** | |
1747ab99 EM |
521 | * Complete an existing (pending) transaction. |
522 | * | |
523 | * This will update related entities (participant, membership, pledge etc) | |
524 | * and take any complete actions from the contribution page (e.g. send receipt). | |
0efa8efe | 525 | * |
526 | * @todo - most of this should live in the BAO layer but as we want it to be an addition | |
527 | * to 4.3 which is already stable we should add it to the api layer & re-factor into the BAO layer later | |
528 | * | |
cf470720 TO |
529 | * @param array $params |
530 | * Input parameters. | |
69dbd1ba | 531 | * |
734d2daa | 532 | * @return array |
533 | * API result array | |
534 | * @throws \API_Exception | |
535 | * @throws \CRM_Core_Exception | |
536 | * @throws \Exception | |
0efa8efe | 537 | */ |
1c31aa41 | 538 | function civicrm_api3_contribution_completetransaction($params) { |
cf8f0fff | 539 | $input = $ids = []; |
07b46478 | 540 | if (isset($params['payment_processor_id'])) { |
541 | $input['payment_processor_id'] = $params['payment_processor_id']; | |
542 | } | |
0efa8efe | 543 | $contribution = new CRM_Contribute_BAO_Contribution(); |
544 | $contribution->id = $params['id']; | |
4e379895 | 545 | if (!$contribution->find(TRUE)) { |
0efa8efe | 546 | throw new API_Exception('A valid contribution ID is required', 'invalid_data'); |
547 | } | |
5ddd6889 | 548 | |
276e3ec6 | 549 | if (!$contribution->loadRelatedObjects($input, $ids, TRUE)) { |
5ddd6889 | 550 | throw new API_Exception('failed to load related objects'); |
0efa8efe | 551 | } |
f527e012 | 552 | elseif ($contribution->contribution_status_id == CRM_Core_PseudoConstant::getKey('CRM_Contribute_BAO_Contribution', 'contribution_status_id', 'Completed')) { |
5ddd6889 | 553 | throw new API_Exception(ts('Contribution already completed'), 'contribution_completed'); |
0efa8efe | 554 | } |
5ddd6889 | 555 | $input['trxn_id'] = !empty($params['trxn_id']) ? $params['trxn_id'] : $contribution->trxn_id; |
080a561b | 556 | if (!empty($params['fee_amount'])) { |
557 | $input['fee_amount'] = $params['fee_amount']; | |
558 | } | |
734d2daa | 559 | return _ipn_process_transaction($params, $contribution, $input, $ids); |
5ddd6889 | 560 | |
0efa8efe | 561 | } |
562 | ||
aa1b1481 | 563 | /** |
9d32e6f7 EM |
564 | * Provide function metadata. |
565 | * | |
c490a46a | 566 | * @param array $params |
aa1b1481 | 567 | */ |
3dfbdece | 568 | function _civicrm_api3_contribution_completetransaction_spec(&$params) { |
cf8f0fff | 569 | $params['id'] = [ |
eac25df2 EM |
570 | 'title' => 'Contribution ID', |
571 | 'type' => CRM_Utils_Type::T_INT, | |
572 | 'api.required' => TRUE, | |
cf8f0fff CW |
573 | ]; |
574 | $params['trxn_id'] = [ | |
eac25df2 EM |
575 | 'title' => 'Transaction ID', |
576 | 'type' => CRM_Utils_Type::T_STRING, | |
cf8f0fff CW |
577 | ]; |
578 | $params['is_email_receipt'] = [ | |
eac25df2 EM |
579 | 'title' => 'Send email Receipt?', |
580 | 'type' => CRM_Utils_Type::T_BOOLEAN, | |
cf8f0fff CW |
581 | ]; |
582 | $params['receipt_from_email'] = [ | |
0930231a EM |
583 | 'title' => 'Email to send receipt from.', |
584 | 'description' => 'If not provided this will default to being based on domain mail or contribution page', | |
585 | 'type' => CRM_Utils_Type::T_EMAIL, | |
cf8f0fff CW |
586 | ]; |
587 | $params['receipt_from_name'] = [ | |
0930231a EM |
588 | 'title' => 'Name to send receipt from', |
589 | 'description' => '. If not provided this will default to domain mail or contribution page', | |
590 | 'type' => CRM_Utils_Type::T_STRING, | |
cf8f0fff CW |
591 | ]; |
592 | $params['payment_processor_id'] = [ | |
07b46478 | 593 | 'title' => 'Payment processor ID', |
080a561b | 594 | 'description' => 'Providing this is strongly recommended, as not possible to calculate it accurately always', |
07b46478 | 595 | 'type' => CRM_Utils_Type::T_INT, |
cf8f0fff CW |
596 | ]; |
597 | $params['fee_amount'] = [ | |
080a561b | 598 | 'title' => 'Fee charged on transaction', |
599 | 'description' => 'If a fee has been charged then the amount', | |
600 | 'type' => CRM_Utils_Type::T_FLOAT, | |
cf8f0fff CW |
601 | ]; |
602 | $params['trxn_date'] = [ | |
7104593e | 603 | 'title' => 'Transaction Date', |
604 | 'description' => 'Date this transaction occurred', | |
970aa2fe | 605 | 'type' => CRM_Utils_Type::T_DATE + CRM_Utils_Type::T_TIME, |
cf8f0fff CW |
606 | ]; |
607 | $params['card_type_id'] = [ | |
a55e39e9 | 608 | 'title' => 'Card Type ID', |
609 | 'description' => 'Providing Credit Card Type ID', | |
610 | 'type' => CRM_Utils_Type::T_INT, | |
cf8f0fff | 611 | 'pseudoconstant' => [ |
a55e39e9 | 612 | 'optionGroupName' => 'accept_creditcard', |
cf8f0fff CW |
613 | ], |
614 | ]; | |
362f37fc | 615 | // At some point we will deprecate this api in favour of calling payment create which will in turn call this |
616 | // api if appropriate to transition related entities and send receipts - ie. financial responsibility should | |
617 | // not exist in completetransaction. For now we just need to allow payment.create to force a bypass on the | |
618 | // things it does itself. | |
619 | $params['is_post_payment_create'] = [ | |
620 | 'title' => 'Is this being called from payment create?', | |
621 | 'type' => CRM_Utils_Type::T_BOOLEAN, | |
622 | 'description' => 'The \'correct\' flow is to call payment.create for the financial side & for that to call completecontribution for the entity & receipt management. However, we need to still support completetransaction directly for legacy reasons', | |
623 | ]; | |
0efa8efe | 624 | } |
5fa7c328 EM |
625 | |
626 | /** | |
627 | * Complete an existing (pending) transaction. | |
628 | * | |
629 | * This will update related entities (participant, membership, pledge etc) | |
630 | * and take any complete actions from the contribution page (e.g. send receipt). | |
631 | * | |
632 | * @todo - most of this should live in the BAO layer but as we want it to be an addition | |
633 | * to 4.3 which is already stable we should add it to the api layer & re-factor into the BAO layer later | |
634 | * | |
635 | * @param array $params | |
636 | * Input parameters. | |
637 | * | |
e4384ce8 | 638 | * @return array |
5fa7c328 | 639 | * Api result array. |
e4384ce8 | 640 | * @throws API_Exception |
5fa7c328 | 641 | */ |
1c31aa41 | 642 | function civicrm_api3_contribution_repeattransaction($params) { |
cf8f0fff CW |
643 | $input = $ids = []; |
644 | civicrm_api3_verify_one_mandatory($params, NULL, ['contribution_recur_id', 'original_contribution_id']); | |
1eade77d | 645 | if (empty($params['original_contribution_id'])) { |
018203cd | 646 | // CRM-19873 call with test mode. |
cf8f0fff | 647 | $params['original_contribution_id'] = civicrm_api3('contribution', 'getvalue', [ |
1eade77d | 648 | 'return' => 'id', |
cf8f0fff | 649 | 'contribution_status_id' => ['IN' => ['Completed']], |
1eade77d | 650 | 'contribution_recur_id' => $params['contribution_recur_id'], |
018203cd | 651 | 'contribution_test' => CRM_Core_DAO::getFieldValue('CRM_Contribute_DAO_ContributionRecur', $params['contribution_recur_id'], 'is_test'), |
cf8f0fff CW |
652 | 'options' => ['limit' => 1, 'sort' => 'id DESC'], |
653 | ]); | |
1eade77d | 654 | } |
5fa7c328 EM |
655 | $contribution = new CRM_Contribute_BAO_Contribution(); |
656 | $contribution->id = $params['original_contribution_id']; | |
657 | if (!$contribution->find(TRUE)) { | |
658 | throw new API_Exception( | |
659 | 'A valid original contribution ID is required', 'invalid_data'); | |
660 | } | |
d97c96dc | 661 | $original_contribution = clone $contribution; |
cf8f0fff | 662 | $input['payment_processor_id'] = civicrm_api3('contributionRecur', 'getvalue', [ |
69a2b0bc AD |
663 | 'return' => 'payment_processor_id', |
664 | 'id' => $contribution->contribution_recur_id, | |
cf8f0fff | 665 | ]); |
5fa7c328 | 666 | try { |
276e3ec6 | 667 | if (!$contribution->loadRelatedObjects($input, $ids, TRUE)) { |
5fa7c328 EM |
668 | throw new API_Exception('failed to load related objects'); |
669 | } | |
d97c96dc EM |
670 | |
671 | unset($contribution->id, $contribution->receive_date, $contribution->invoice_id); | |
5fa7c328 | 672 | $contribution->receive_date = $params['receive_date']; |
96f0fe0d | 673 | |
cf8f0fff | 674 | $passThroughParams = [ |
d5580ed4 | 675 | 'trxn_id', |
676 | 'total_amount', | |
677 | 'campaign_id', | |
678 | 'fee_amount', | |
679 | 'financial_type_id', | |
680 | 'contribution_status_id', | |
cf8f0fff | 681 | ]; |
96f0fe0d | 682 | $input = array_intersect_key($params, array_fill_keys($passThroughParams, NULL)); |
d97c96dc | 683 | |
734d2daa | 684 | return _ipn_process_transaction($params, $contribution, $input, $ids, $original_contribution); |
5fa7c328 | 685 | } |
7c31ae57 | 686 | catch (Exception $e) { |
5fa7c328 EM |
687 | throw new API_Exception('failed to load related objects' . $e->getMessage() . "\n" . $e->getTraceAsString()); |
688 | } | |
689 | } | |
690 | ||
691 | /** | |
692 | * Calls IPN complete transaction for completing or repeating a transaction. | |
693 | * | |
694 | * The IPN function is overloaded with two purposes - this is simply a wrapper for that | |
695 | * when separating them in the api layer. | |
696 | * | |
697 | * @param array $params | |
698 | * @param CRM_Contribute_BAO_Contribution $contribution | |
699 | * @param array $input | |
700 | * | |
701 | * @param array $ids | |
702 | * | |
d97c96dc EM |
703 | * @param CRM_Contribute_BAO_Contribution $firstContribution |
704 | * | |
5fa7c328 EM |
705 | * @return mixed |
706 | */ | |
d97c96dc | 707 | function _ipn_process_transaction(&$params, $contribution, $input, $ids, $firstContribution = NULL) { |
5fa7c328 EM |
708 | $objects = $contribution->_relatedObjects; |
709 | $objects['contribution'] = &$contribution; | |
d97c96dc EM |
710 | |
711 | if ($firstContribution) { | |
712 | $objects['first_contribution'] = $firstContribution; | |
713 | } | |
5fa7c328 EM |
714 | $input['component'] = $contribution->_component; |
715 | $input['is_test'] = $contribution->is_test; | |
96f0fe0d EM |
716 | $input['amount'] = empty($input['total_amount']) ? $contribution->total_amount : $input['total_amount']; |
717 | ||
5fa7c328 EM |
718 | if (isset($params['is_email_receipt'])) { |
719 | $input['is_email_receipt'] = $params['is_email_receipt']; | |
720 | } | |
7104593e | 721 | if (!empty($params['trxn_date'])) { |
722 | $input['trxn_date'] = $params['trxn_date']; | |
723 | } | |
dccd9f4f ERL |
724 | if (!empty($params['receive_date'])) { |
725 | $input['receive_date'] = $params['receive_date']; | |
726 | } | |
0930231a EM |
727 | if (empty($contribution->contribution_page_id)) { |
728 | static $domainFromName; | |
729 | static $domainFromEmail; | |
730 | if (empty($domainFromEmail) && (empty($params['receipt_from_name']) || empty($params['receipt_from_email']))) { | |
37b8953e | 731 | list($domainFromName, $domainFromEmail) = CRM_Core_BAO_Domain::getNameAndEmail(TRUE); |
0930231a EM |
732 | } |
733 | $input['receipt_from_name'] = CRM_Utils_Array::value('receipt_from_name', $params, $domainFromName); | |
734 | $input['receipt_from_email'] = CRM_Utils_Array::value('receipt_from_email', $params, $domainFromEmail); | |
735 | } | |
a55e39e9 | 736 | $input['card_type_id'] = CRM_Utils_Array::value('card_type_id', $params); |
737 | $input['pan_truncation'] = CRM_Utils_Array::value('pan_truncation', $params); | |
4b6c8c1e | 738 | $transaction = new CRM_Core_Transaction(); |
7237222f | 739 | return CRM_Contribute_BAO_Contribution::completeOrder($input, $ids, $objects, $transaction, |
362f37fc | 740 | !empty($contribution->contribution_recur_id), $contribution, CRM_Utils_Array::value('is_post_payment_create', $params)); |
5fa7c328 EM |
741 | } |
742 | ||
743 | /** | |
744 | * Provide function metadata. | |
745 | * | |
746 | * @param array $params | |
747 | */ | |
748 | function _civicrm_api3_contribution_repeattransaction_spec(&$params) { | |
cf8f0fff | 749 | $params['original_contribution_id'] = [ |
5fa7c328 | 750 | 'title' => 'Original Contribution ID', |
1eade77d | 751 | 'description' => 'Contribution ID to copy (will be calculated from recurring contribution if not provided)', |
752 | 'type' => CRM_Utils_Type::T_INT, | |
cf8f0fff CW |
753 | ]; |
754 | $params['contribution_recur_id'] = [ | |
1eade77d | 755 | 'title' => 'Recurring contribution ID', |
5fa7c328 | 756 | 'type' => CRM_Utils_Type::T_INT, |
cf8f0fff CW |
757 | ]; |
758 | $params['trxn_id'] = [ | |
5fa7c328 EM |
759 | 'title' => 'Transaction ID', |
760 | 'type' => CRM_Utils_Type::T_STRING, | |
cf8f0fff CW |
761 | ]; |
762 | $params['is_email_receipt'] = [ | |
5fa7c328 EM |
763 | 'title' => 'Send email Receipt?', |
764 | 'type' => CRM_Utils_Type::T_BOOLEAN, | |
cf8f0fff CW |
765 | ]; |
766 | $params['contribution_status_id'] = [ | |
5fa7c328 | 767 | 'title' => 'Contribution Status ID', |
d97c96dc | 768 | 'name' => 'contribution_status_id', |
5fa7c328 | 769 | 'type' => CRM_Utils_Type::T_INT, |
cf8f0fff | 770 | 'pseudoconstant' => [ |
5fa7c328 | 771 | 'optionGroupName' => 'contribution_status', |
cf8f0fff | 772 | ], |
5fa7c328 | 773 | 'api.required' => TRUE, |
cf8f0fff CW |
774 | ]; |
775 | $params['receive_date'] = [ | |
5fa7c328 | 776 | 'title' => 'Contribution Receive Date', |
d97c96dc | 777 | 'name' => 'receive_date', |
970aa2fe | 778 | 'type' => CRM_Utils_Type::T_DATE + CRM_Utils_Type::T_TIME, |
5fa7c328 | 779 | 'api.default' => 'now', |
cf8f0fff CW |
780 | ]; |
781 | $params['trxn_id'] = [ | |
d97c96dc EM |
782 | 'title' => 'Transaction ID', |
783 | 'name' => 'trxn_id', | |
784 | 'type' => CRM_Utils_Type::T_STRING, | |
cf8f0fff CW |
785 | ]; |
786 | $params['campaign_id'] = [ | |
c02c17df | 787 | 'title' => 'Campaign ID', |
788 | 'name' => 'campaign_id', | |
789 | 'type' => CRM_Utils_Type::T_INT, | |
cf8f0fff | 790 | 'pseudoconstant' => [ |
c02c17df | 791 | 'table' => 'civicrm_campaign', |
792 | 'keyColumn' => 'id', | |
793 | 'labelColumn' => 'title', | |
cf8f0fff CW |
794 | ], |
795 | ]; | |
796 | $params['financial_type_id'] = [ | |
3c49d90c | 797 | 'title' => 'Financial ID (ignored if more than one line item)', |
798 | 'name' => 'financial_type_id', | |
799 | 'type' => CRM_Utils_Type::T_INT, | |
cf8f0fff | 800 | 'pseudoconstant' => [ |
3c49d90c | 801 | 'table' => 'civicrm_financial_type', |
802 | 'keyColumn' => 'id', | |
803 | 'labelColumn' => 'name', | |
cf8f0fff CW |
804 | ], |
805 | ]; | |
806 | $params['payment_processor_id'] = [ | |
d97c96dc EM |
807 | 'description' => ts('Payment processor ID, will be loaded from contribution_recur if not provided'), |
808 | 'title' => 'Payment processor ID', | |
809 | 'name' => 'payment_processor_id', | |
810 | 'type' => CRM_Utils_Type::T_INT, | |
cf8f0fff | 811 | ]; |
5fa7c328 | 812 | } |