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