Commit | Line | Data |
---|---|---|
6a488035 | 1 | <?php |
6a488035 TO |
2 | /* |
3 | +--------------------------------------------------------------------+ | |
81621fee | 4 | | CiviCRM version 4.7 | |
6a488035 | 5 | +--------------------------------------------------------------------+ |
e7112fa7 | 6 | | Copyright CiviCRM LLC (c) 2004-2015 | |
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 TO |
43 | */ |
44 | function civicrm_api3_contribution_create(&$params) { | |
45 | $values = array(); | |
6a488035 | 46 | _civicrm_api3_custom_format_params($params, $values, 'Contribution'); |
504a78f6 | 47 | $params = array_merge($params, $values); |
48 | ||
3300bf67 PN |
49 | if (CRM_Financial_BAO_FinancialType::isACLFinancialTypeStatus()) { |
50 | if (empty($params['id'])) { | |
51 | $op = 'add'; | |
52 | } | |
53 | else { | |
54 | if (empty($params['financial_type_id'])) { | |
55 | $params['financial_type_id'] = civicrm_api3('Contribution', 'getvalue', array( | |
56 | 'id' => $params['id'], | |
57 | 'return' => 'financial_type_id', | |
58 | )); | |
59 | } | |
60 | $op = 'edit'; | |
61 | } | |
62 | CRM_Financial_BAO_FinancialType::getAvailableFinancialTypes($types, $op); | |
63 | if (!in_array($params['financial_type_id'], array_keys($types))) { | |
64 | return civicrm_api3_create_error('You do not have permission to create this contribution'); | |
65 | } | |
816cac04 | 66 | } |
8cc574cf | 67 | if (!empty($params['id']) && !empty($params['contribution_status_id'])) { |
504a78f6 | 68 | $error = array(); |
69 | //throw error for invalid status change such as setting completed back to pending | |
70 | //@todo this sort of validation belongs in the BAO not the API - if it is not an OK | |
71 | // action it needs to be blocked there. If it is Ok through a form it needs to be OK through the api | |
72 | CRM_Contribute_BAO_Contribution::checkStatusValidation(NULL, $params, $error); | |
73 | if (array_key_exists('contribution_status_id', $error)) { | |
74 | throw new API_Exception($error['contribution_status_id']); | |
75 | } | |
6a488035 | 76 | } |
4d47ad17 PN |
77 | if (!empty($params['id']) && !empty($params['financial_type_id'])) { |
78 | $error = array(); | |
79 | CRM_Contribute_BAO_Contribution::checkFinancialTypeChange($params['financial_type_id'], $params['id'], $error); | |
80 | if (array_key_exists('financial_type_id', $error)) { | |
81 | throw new API_Exception($error['financial_type_id']); | |
82 | } | |
83 | } | |
6a516bd6 DG |
84 | _civicrm_api3_contribution_create_legacy_support_45($params); |
85 | ||
9d32e6f7 | 86 | // Make sure tax calculation is handled via api. |
b5935203 | 87 | $params = CRM_Contribute_BAO_Contribution::checkTaxAmount($params); |
ebf2b57b | 88 | |
504a78f6 | 89 | return _civicrm_api3_basic_create(_civicrm_api3_get_BAO(__FUNCTION__), $params, 'Contribution'); |
6a488035 | 90 | } |
11e09c59 TO |
91 | |
92 | /** | |
0aa0303c EM |
93 | * Adjust Metadata for Create action. |
94 | * | |
95 | * The metadata is used for setting defaults, documentation & validation. | |
6a488035 | 96 | * |
cf470720 | 97 | * @param array $params |
b081365f | 98 | * Array of parameters determined by getfields. |
6a488035 TO |
99 | */ |
100 | function _civicrm_api3_contribution_create_spec(&$params) { | |
101 | $params['contact_id']['api.required'] = 1; | |
102 | $params['total_amount']['api.required'] = 1; | |
53191813 | 103 | $params['payment_instrument_id']['api.aliases'] = array('payment_instrument'); |
8757a378 | 104 | $params['receive_date']['api.default'] = 'now'; |
6a488035 TO |
105 | $params['payment_processor'] = array( |
106 | 'name' => 'payment_processor', | |
107 | 'title' => 'Payment Processor ID', | |
108 | 'description' => 'ID of payment processor used for this contribution', | |
109 | // field is called payment processor - not payment processor id but can only be one id so | |
110 | // it seems likely someone will fix it up one day to be more consistent - lets alias it from the start | |
111 | 'api.aliases' => array('payment_processor_id'), | |
d142432b | 112 | 'type' => CRM_Utils_Type::T_INT, |
6a488035 TO |
113 | ); |
114 | $params['financial_type_id']['api.aliases'] = array('contribution_type_id', 'contribution_type'); | |
115 | $params['financial_type_id']['api.required'] = 1; | |
116 | $params['note'] = array( | |
117 | 'name' => 'note', | |
118 | 'uniqueName' => 'contribution_note', | |
119 | 'title' => 'note', | |
120 | 'type' => 2, | |
121 | 'description' => 'Associated Note in the notes table', | |
122 | ); | |
123 | $params['soft_credit_to'] = array( | |
124 | 'name' => 'soft_credit_to', | |
33a429d4 | 125 | 'title' => 'Soft Credit contact ID (legacy)', |
797d4c52 | 126 | 'type' => CRM_Utils_Type::T_INT, |
33a429d4 | 127 | 'description' => 'ID of Contact to be Soft credited to (deprecated - use contribution_soft api)', |
6a488035 TO |
128 | 'FKClassName' => 'CRM_Contact_DAO_Contact', |
129 | ); | |
6a516bd6 DG |
130 | $params['honor_contact_id'] = array( |
131 | 'name' => 'honor_contact_id', | |
33a429d4 | 132 | 'title' => 'Honoree contact ID (legacy)', |
797d4c52 | 133 | 'type' => CRM_Utils_Type::T_INT, |
33a429d4 | 134 | 'description' => 'ID of honoree contact (deprecated - use contribution_soft api)', |
6a516bd6 DG |
135 | 'FKClassName' => 'CRM_Contact_DAO_Contact', |
136 | ); | |
33a429d4 CW |
137 | $params['honor_type_id'] = array( |
138 | 'name' => 'honor_type_id', | |
139 | 'title' => 'Honoree Type (legacy)', | |
797d4c52 | 140 | 'type' => CRM_Utils_Type::T_INT, |
33a429d4 CW |
141 | 'description' => 'Type of honoree contact (deprecated - use contribution_soft api)', |
142 | 'pseudoconstant' => TRUE, | |
143 | ); | |
6a488035 | 144 | // note this is a recommended option but not adding as a default to avoid |
c206647d | 145 | // creating unnecessary changes for the dev |
6a488035 TO |
146 | $params['skipRecentView'] = array( |
147 | 'name' => 'skipRecentView', | |
148 | 'title' => 'Skip adding to recent view', | |
0900b21e | 149 | 'type' => CRM_Utils_Type::T_BOOLEAN, |
6a488035 TO |
150 | 'description' => 'Do not add to recent view (setting this improves performance)', |
151 | ); | |
152 | $params['skipLineItem'] = array( | |
153 | 'name' => 'skipLineItem', | |
154 | 'title' => 'Skip adding line items', | |
b3b7f4c5 | 155 | 'type' => CRM_Utils_Type::T_BOOLEAN, |
6a488035 TO |
156 | 'api.default' => 0, |
157 | 'description' => 'Do not add line items by default (if you wish to add your own)', | |
158 | ); | |
599c61ac E |
159 | $params['batch_id'] = array( |
160 | 'title' => 'Batch', | |
797d4c52 | 161 | 'type' => CRM_Utils_Type::T_INT, |
599c61ac E |
162 | 'description' => 'Batch which relevant transactions should be added to', |
163 | ); | |
797d4c52 | 164 | $params['refund_trxn_id'] = array( |
165 | 'title' => 'Refund Transaction ID', | |
166 | 'type' => CRM_Utils_Type::T_STRING, | |
167 | 'description' => 'Transaction ID specific to the refund taking place', | |
168 | ); | |
6a488035 TO |
169 | } |
170 | ||
6a516bd6 | 171 | /** |
9d32e6f7 EM |
172 | * Support for schema changes made in 4.5. |
173 | * | |
35671d00 TO |
174 | * The main purpose of the API is to provide integrators a level of stability not provided by |
175 | * the core code or schema - this means we have to provide support for api calls (where possible) | |
176 | * across schema changes. | |
dc64d047 | 177 | * |
d0997921 | 178 | * @param array $params |
35671d00 | 179 | */ |
9b873358 | 180 | function _civicrm_api3_contribution_create_legacy_support_45(&$params) { |
6a516bd6 | 181 | //legacy soft credit handling - recommended approach is chaining |
9b873358 | 182 | if (!empty($params['soft_credit_to'])) { |
33a429d4 | 183 | $params['soft_credit'][] = array( |
6a516bd6 DG |
184 | 'contact_id' => $params['soft_credit_to'], |
185 | 'amount' => $params['total_amount'], | |
21dfd5f5 | 186 | 'soft_credit_type_id' => CRM_Core_OptionGroup::getDefaultValue("soft_credit_type"), |
33a429d4 | 187 | ); |
6a516bd6 | 188 | } |
9b873358 | 189 | if (!empty($params['honor_contact_id'])) { |
33a429d4 | 190 | $params['soft_credit'][] = array( |
6a516bd6 DG |
191 | 'contact_id' => $params['honor_contact_id'], |
192 | 'amount' => $params['total_amount'], | |
21dfd5f5 | 193 | 'soft_credit_type_id' => CRM_Utils_Array::value('honor_type_id', $params, CRM_Core_OptionGroup::getValue('soft_credit_type', 'in_honor_of', 'name')), |
33a429d4 | 194 | ); |
6a516bd6 DG |
195 | } |
196 | } | |
197 | ||
6a488035 | 198 | /** |
244bbdd8 | 199 | * Delete a Contribution. |
6a488035 | 200 | * |
cf470720 | 201 | * @param array $params |
9d32e6f7 | 202 | * Input parameters. |
6a488035 | 203 | * |
9d32e6f7 | 204 | * @return array |
6a488035 TO |
205 | */ |
206 | function civicrm_api3_contribution_delete($params) { | |
207 | ||
0d8afee2 | 208 | $contributionID = !empty($params['contribution_id']) ? $params['contribution_id'] : $params['id']; |
c93fecd1 E |
209 | // First check contribution financial type |
210 | $financialType = CRM_Core_DAO::getFieldValue('CRM_Contribute_DAO_Contribution', $contributionID, 'financial_type_id'); | |
c93fecd1 | 211 | // Now check permissioned lineitems & permissioned contribution |
40c655aa E |
212 | if (CRM_Financial_BAO_FinancialType::isACLFinancialTypeStatus() |
213 | && !CRM_Core_Permission::check('delete contributions of type ' . CRM_Contribute_PseudoConstant::financialType($financialType)) || | |
214 | !CRM_Financial_BAO_FinancialType::checkPermissionedLineItems($contributionID, 'delete', FALSE) | |
66af7c48 | 215 | ) { |
c93fecd1 E |
216 | return civicrm_api3_create_error('You do not have permission to delete this contribution'); |
217 | } | |
6a488035 TO |
218 | if (CRM_Contribute_BAO_Contribution::deleteContribution($contributionID)) { |
219 | return civicrm_api3_create_success(array($contributionID => 1)); | |
220 | } | |
221 | else { | |
222 | return civicrm_api3_create_error('Could not delete contribution'); | |
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) { | |
234 | $params['id']['api.aliases'] = array('contribution_id'); | |
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; |
be81f101 | 249 | $returnProperties = CRM_Contribute_BAO_Query::defaultReturnProperties($mode); |
6a488035 | 250 | |
be81f101 | 251 | $contributions = _civicrm_api3_get_using_query_object('Contribution', $params, array(), NULL, $mode, $returnProperties); |
252 | ||
253 | foreach ($contributions as $id => $contribution) { | |
254 | $softContribution = CRM_Contribute_BAO_ContributionSoft::getSoftContribution($id, TRUE); | |
255 | $contributions[$id] = array_merge($contribution, $softContribution); | |
76ca3345 | 256 | // format soft credit for backward compatibility |
be81f101 | 257 | _civicrm_api3_format_soft_credit($contributions[$id]); |
6a488035 | 258 | } |
be81f101 | 259 | return civicrm_api3_create_success($contributions, $params, 'Contribution', 'get'); |
9ae25b56 | 260 | } |
261 | ||
262 | /** | |
263 | * Get number of contacts matching the supplied criteria. | |
264 | * | |
265 | * @param array $params | |
266 | * | |
267 | * @return int | |
268 | */ | |
269 | function civicrm_api3_contribution_getcount($params) { | |
270 | $count = _civicrm_api3_get_using_query_object('Contribution', $params, array(), TRUE, CRM_Contact_BAO_Query::MODE_CONTRIBUTE); | |
271 | return (int) $count; | |
6a488035 | 272 | } |
11e09c59 | 273 | |
76ca3345 | 274 | /** |
1747ab99 EM |
275 | * This function is used to format the soft credit for backward compatibility. |
276 | * | |
277 | * As of v4.4 we support multiple soft credit, so now contribution returns array with 'soft_credit' as key | |
76ca3345 | 278 | * but we still return first soft credit as a part of contribution array |
dc64d047 | 279 | * |
645ee340 | 280 | * @param $contribution |
76ca3345 KJ |
281 | */ |
282 | function _civicrm_api3_format_soft_credit(&$contribution) { | |
283 | if (!empty($contribution['soft_credit'])) { | |
284 | $contribution['soft_credit_to'] = $contribution['soft_credit'][1]['contact_id']; | |
285 | $contribution['soft_credit_id'] = $contribution['soft_credit'][1]['soft_credit_id']; | |
286 | } | |
287 | } | |
288 | ||
11e09c59 | 289 | /** |
1747ab99 | 290 | * Adjust Metadata for Get action. |
6a488035 | 291 | * |
0aa0303c EM |
292 | * The metadata is used for setting defaults, documentation & validation. |
293 | * | |
cf470720 | 294 | * @param array $params |
b081365f | 295 | * Array of parameters determined by getfields. |
6a488035 TO |
296 | */ |
297 | function _civicrm_api3_contribution_get_spec(&$params) { | |
d142432b EM |
298 | $params['contribution_test'] = array( |
299 | 'api.default' => 0, | |
300 | 'type' => CRM_Utils_Type::T_BOOLEAN, | |
301 | 'title' => 'Get Test Contributions?', | |
71d5a412 | 302 | 'api.aliases' => array('is_test'), |
d142432b | 303 | ); |
739a8336 | 304 | |
6a488035 | 305 | $params['financial_type_id']['api.aliases'] = array('contribution_type_id'); |
e6b9e2ae | 306 | $params['payment_instrument_id']['api.aliases'] = array('contribution_payment_instrument', 'payment_instrument'); |
6a488035 TO |
307 | $params['contact_id'] = $params['contribution_contact_id']; |
308 | $params['contact_id']['api.aliases'] = array('contribution_contact_id'); | |
309 | unset($params['contribution_contact_id']); | |
310 | } | |
311 | ||
312 | /** | |
1747ab99 EM |
313 | * Legacy handling for contribution parameters. |
314 | * | |
315 | * Take the input parameter list as specified in the data model and | |
316 | * convert it into the same format that we use in QF and BAO object. | |
6a488035 | 317 | * |
cf470720 | 318 | * @param array $params |
c23f45d3 | 319 | * property name/value pairs to insert in new contact. |
cf470720 TO |
320 | * @param array $values |
321 | * The reformatted properties that we can use internally. | |
6a488035 | 322 | * |
c23f45d3 | 323 | * @return array |
6a488035 | 324 | */ |
c23f45d3 | 325 | function _civicrm_api3_contribute_format_params($params, &$values) { |
35671d00 | 326 | //legacy way of formatting from v2 api - v3 way is to define metadata & do it in the api layer |
6a488035 | 327 | _civicrm_api3_filter_fields_for_bao('Contribution', $params, $values); |
6a488035 TO |
328 | return array(); |
329 | } | |
330 | ||
16c0ec8d | 331 | /** |
1747ab99 | 332 | * Adjust Metadata for Transact action. |
16c0ec8d | 333 | * |
0aa0303c EM |
334 | * The metadata is used for setting defaults, documentation & validation. |
335 | * | |
cf470720 | 336 | * @param array $params |
b081365f | 337 | * Array of parameters determined by getfields. |
16c0ec8d CW |
338 | */ |
339 | function _civicrm_api3_contribution_transact_spec(&$params) { | |
244bbdd8 | 340 | $fields = civicrm_api3('Contribution', 'getfields', array('action' => 'create')); |
4c41ecb2 | 341 | $params = array_merge($params, $fields['values']); |
16c0ec8d CW |
342 | $params['receive_date']['api.default'] = 'now'; |
343 | } | |
344 | ||
6a488035 TO |
345 | /** |
346 | * Process a transaction and record it against the contact. | |
347 | * | |
cf470720 | 348 | * @param array $params |
1747ab99 | 349 | * Input parameters. |
6a488035 | 350 | * |
a6c01b45 | 351 | * @return array |
c23f45d3 | 352 | * contribution of created or updated record (or a civicrm error) |
6a488035 TO |
353 | */ |
354 | function civicrm_api3_contribution_transact($params) { | |
16c0ec8d | 355 | // Set some params specific to payment processing |
8319cf11 EM |
356 | // @todo - fix this function - none of the results checked by civicrm_error would ever be an array with |
357 | // 'is_error' set | |
358 | // also trxn_id is not saved. | |
359 | // but since there is no test it's not desirable to jump in & make the obvious changes. | |
16c0ec8d CW |
360 | $params['payment_processor_mode'] = empty($params['is_test']) ? 'live' : 'test'; |
361 | $params['amount'] = $params['total_amount']; | |
6a488035 TO |
362 | if (!isset($params['net_amount'])) { |
363 | $params['net_amount'] = $params['amount']; | |
364 | } | |
6a488035 TO |
365 | if (!isset($params['invoiceID']) && isset($params['invoice_id'])) { |
366 | $params['invoiceID'] = $params['invoice_id']; | |
367 | } | |
368 | ||
be06e507 CW |
369 | // Some payment processors expect a unique invoice_id - generate one if not supplied |
370 | $params['invoice_id'] = CRM_Utils_Array::value('invoice_id', $params, md5(uniqid(rand(), TRUE))); | |
371 | ||
16c0ec8d | 372 | $paymentProcessor = CRM_Financial_BAO_PaymentProcessor::getPayment($params['payment_processor'], $params['payment_processor_mode']); |
9d8f43b1 | 373 | $paymentProcessor['object']->doPayment($params); |
6a488035 | 374 | |
26ad2b72 | 375 | $params['payment_instrument_id'] = CRM_Core_DAO::getFieldValue('CRM_Financial_DAO_PaymentProcessorType', $paymentProcessor['payment_processor_type_id'], 'payment_type') == 1 ? 'Credit Card' : 'Debit Card'; |
244bbdd8 | 376 | return civicrm_api('Contribution', 'create', $params); |
6a488035 | 377 | } |
69dbd1ba | 378 | |
6a488035 | 379 | /** |
1747ab99 EM |
380 | * Send a contribution confirmation (receipt or invoice). |
381 | * | |
6a488035 TO |
382 | * The appropriate online template will be used (the existence of related objects |
383 | * (e.g. memberships ) will affect this selection | |
69dbd1ba | 384 | * |
cf470720 TO |
385 | * @param array $params |
386 | * Input parameters. | |
69dbd1ba EM |
387 | * |
388 | * @throws Exception | |
6a488035 TO |
389 | */ |
390 | function civicrm_api3_contribution_sendconfirmation($params) { | |
391 | $contribution = new CRM_Contribute_BAO_Contribution(); | |
392 | $contribution->id = $params['id']; | |
acb1052e | 393 | if (!$contribution->find(TRUE)) { |
6a488035 | 394 | throw new Exception('Contribution does not exist'); |
35671d00 | 395 | } |
6a488035 | 396 | $input = $ids = $cvalues = array('receipt_from_email' => $params['receipt_from_email']); |
276e3ec6 | 397 | $contribution->loadRelatedObjects($input, $ids, TRUE); |
76ca3345 | 398 | $contribution->composeMessageArray($input, $ids, $cvalues, FALSE, FALSE); |
6a488035 TO |
399 | } |
400 | ||
11e09c59 | 401 | /** |
1747ab99 | 402 | * Adjust Metadata for sendconfirmation action. |
6a488035 | 403 | * |
0aa0303c EM |
404 | * The metadata is used for setting defaults, documentation & validation. |
405 | * | |
cf470720 | 406 | * @param array $params |
b081365f | 407 | * Array of parameters determined by getfields. |
6a488035 TO |
408 | */ |
409 | function _civicrm_api3_contribution_sendconfirmation_spec(&$params) { | |
410 | $params['id'] = array( | |
411 | 'api.required' => 1, | |
21dfd5f5 | 412 | 'title' => 'Contribution ID', |
d142432b | 413 | 'type' => CRM_Utils_Type::T_INT, |
6a488035 TO |
414 | ); |
415 | $params['receipt_from_email'] = array( | |
35671d00 | 416 | 'api.required' => 1, |
6a0cf2c6 | 417 | 'title' => 'From Email address (string) required until someone provides a patch :-)', |
d142432b | 418 | 'type' => CRM_Utils_Type::T_STRING, |
6a0cf2c6 CW |
419 | ); |
420 | $params['receipt_from_name'] = array( | |
421 | 'title' => 'From Name (string)', | |
d142432b | 422 | 'type' => CRM_Utils_Type::T_STRING, |
6a0cf2c6 CW |
423 | ); |
424 | $params['cc_receipt'] = array( | |
425 | 'title' => 'CC Email address (string)', | |
d142432b | 426 | 'type' => CRM_Utils_Type::T_STRING, |
6a0cf2c6 CW |
427 | ); |
428 | $params['bcc_receipt'] = array( | |
429 | 'title' => 'BCC Email address (string)', | |
d142432b | 430 | 'type' => CRM_Utils_Type::T_STRING, |
6a0cf2c6 CW |
431 | ); |
432 | $params['receipt_text'] = array( | |
433 | 'title' => 'Message (string)', | |
d142432b | 434 | 'type' => CRM_Utils_Type::T_STRING, |
6a488035 TO |
435 | ); |
436 | } | |
0efa8efe | 437 | |
438 | /** | |
1747ab99 EM |
439 | * Complete an existing (pending) transaction. |
440 | * | |
441 | * This will update related entities (participant, membership, pledge etc) | |
442 | * and take any complete actions from the contribution page (e.g. send receipt). | |
0efa8efe | 443 | * |
444 | * @todo - most of this should live in the BAO layer but as we want it to be an addition | |
445 | * to 4.3 which is already stable we should add it to the api layer & re-factor into the BAO layer later | |
446 | * | |
cf470720 TO |
447 | * @param array $params |
448 | * Input parameters. | |
69dbd1ba EM |
449 | * |
450 | * @throws API_Exception | |
acb1052e | 451 | * Api result array. |
0efa8efe | 452 | */ |
453 | function civicrm_api3_contribution_completetransaction(&$params) { | |
454 | ||
455 | $input = $ids = array(); | |
07b46478 | 456 | if (isset($params['payment_processor_id'])) { |
457 | $input['payment_processor_id'] = $params['payment_processor_id']; | |
458 | } | |
0efa8efe | 459 | $contribution = new CRM_Contribute_BAO_Contribution(); |
460 | $contribution->id = $params['id']; | |
461 | $contribution->find(TRUE); | |
9b873358 | 462 | if (!$contribution->id == $params['id']) { |
0efa8efe | 463 | throw new API_Exception('A valid contribution ID is required', 'invalid_data'); |
464 | } | |
5ddd6889 | 465 | |
276e3ec6 | 466 | if (!$contribution->loadRelatedObjects($input, $ids, TRUE)) { |
5ddd6889 | 467 | throw new API_Exception('failed to load related objects'); |
0efa8efe | 468 | } |
5ddd6889 EM |
469 | elseif ($contribution->contribution_status_id == CRM_Core_OptionGroup::getValue('contribution_status', 'Completed', 'name')) { |
470 | throw new API_Exception(ts('Contribution already completed'), 'contribution_completed'); | |
0efa8efe | 471 | } |
5ddd6889 | 472 | $input['trxn_id'] = !empty($params['trxn_id']) ? $params['trxn_id'] : $contribution->trxn_id; |
080a561b | 473 | if (!empty($params['fee_amount'])) { |
474 | $input['fee_amount'] = $params['fee_amount']; | |
475 | } | |
5ddd6889 EM |
476 | $params = _ipn_process_transaction($params, $contribution, $input, $ids); |
477 | ||
0efa8efe | 478 | } |
479 | ||
aa1b1481 | 480 | /** |
9d32e6f7 EM |
481 | * Provide function metadata. |
482 | * | |
c490a46a | 483 | * @param array $params |
aa1b1481 | 484 | */ |
3dfbdece | 485 | function _civicrm_api3_contribution_completetransaction_spec(&$params) { |
eac25df2 EM |
486 | $params['id'] = array( |
487 | 'title' => 'Contribution ID', | |
488 | 'type' => CRM_Utils_Type::T_INT, | |
489 | 'api.required' => TRUE, | |
490 | ); | |
491 | $params['trxn_id'] = array( | |
492 | 'title' => 'Transaction ID', | |
493 | 'type' => CRM_Utils_Type::T_STRING, | |
494 | ); | |
495 | $params['is_email_receipt'] = array( | |
496 | 'title' => 'Send email Receipt?', | |
497 | 'type' => CRM_Utils_Type::T_BOOLEAN, | |
498 | ); | |
0930231a EM |
499 | $params['receipt_from_email'] = array( |
500 | 'title' => 'Email to send receipt from.', | |
501 | 'description' => 'If not provided this will default to being based on domain mail or contribution page', | |
502 | 'type' => CRM_Utils_Type::T_EMAIL, | |
503 | ); | |
504 | $params['receipt_from_name'] = array( | |
505 | 'title' => 'Name to send receipt from', | |
506 | 'description' => '. If not provided this will default to domain mail or contribution page', | |
507 | 'type' => CRM_Utils_Type::T_STRING, | |
508 | ); | |
07b46478 | 509 | $params['payment_processor_id'] = array( |
510 | 'title' => 'Payment processor ID', | |
080a561b | 511 | 'description' => 'Providing this is strongly recommended, as not possible to calculate it accurately always', |
07b46478 | 512 | 'type' => CRM_Utils_Type::T_INT, |
513 | ); | |
080a561b | 514 | $params['fee_amount'] = array( |
515 | 'title' => 'Fee charged on transaction', | |
516 | 'description' => 'If a fee has been charged then the amount', | |
517 | 'type' => CRM_Utils_Type::T_FLOAT, | |
518 | ); | |
7104593e | 519 | $params['trxn_date'] = array( |
520 | 'title' => 'Transaction Date', | |
521 | 'description' => 'Date this transaction occurred', | |
522 | 'type' => CRM_Utils_Type::T_DATE, | |
523 | ); | |
0efa8efe | 524 | } |
5fa7c328 EM |
525 | |
526 | /** | |
527 | * Complete an existing (pending) transaction. | |
528 | * | |
529 | * This will update related entities (participant, membership, pledge etc) | |
530 | * and take any complete actions from the contribution page (e.g. send receipt). | |
531 | * | |
532 | * @todo - most of this should live in the BAO layer but as we want it to be an addition | |
533 | * to 4.3 which is already stable we should add it to the api layer & re-factor into the BAO layer later | |
534 | * | |
535 | * @param array $params | |
536 | * Input parameters. | |
537 | * | |
538 | * @throws API_Exception | |
539 | * Api result array. | |
540 | */ | |
541 | function civicrm_api3_contribution_repeattransaction(&$params) { | |
542 | $input = $ids = array(); | |
543 | $contribution = new CRM_Contribute_BAO_Contribution(); | |
544 | $contribution->id = $params['original_contribution_id']; | |
545 | if (!$contribution->find(TRUE)) { | |
546 | throw new API_Exception( | |
547 | 'A valid original contribution ID is required', 'invalid_data'); | |
548 | } | |
d97c96dc | 549 | $original_contribution = clone $contribution; |
5fa7c328 | 550 | try { |
276e3ec6 | 551 | if (!$contribution->loadRelatedObjects($input, $ids, TRUE)) { |
5fa7c328 EM |
552 | throw new API_Exception('failed to load related objects'); |
553 | } | |
d97c96dc EM |
554 | |
555 | unset($contribution->id, $contribution->receive_date, $contribution->invoice_id); | |
556 | $contribution->contribution_status_id = $params['contribution_status_id']; | |
5fa7c328 | 557 | $contribution->receive_date = $params['receive_date']; |
96f0fe0d EM |
558 | |
559 | $passThroughParams = array('trxn_id', 'total_amount', 'campaign_id', 'fee_amount'); | |
560 | $input = array_intersect_key($params, array_fill_keys($passThroughParams, NULL)); | |
d97c96dc EM |
561 | |
562 | $params = _ipn_process_transaction($params, $contribution, $input, $ids, $original_contribution); | |
5fa7c328 EM |
563 | } |
564 | catch(Exception $e) { | |
565 | throw new API_Exception('failed to load related objects' . $e->getMessage() . "\n" . $e->getTraceAsString()); | |
566 | } | |
567 | } | |
568 | ||
569 | /** | |
570 | * Calls IPN complete transaction for completing or repeating a transaction. | |
571 | * | |
572 | * The IPN function is overloaded with two purposes - this is simply a wrapper for that | |
573 | * when separating them in the api layer. | |
574 | * | |
575 | * @param array $params | |
576 | * @param CRM_Contribute_BAO_Contribution $contribution | |
577 | * @param array $input | |
578 | * | |
579 | * @param array $ids | |
580 | * | |
d97c96dc EM |
581 | * @param CRM_Contribute_BAO_Contribution $firstContribution |
582 | * | |
5fa7c328 EM |
583 | * @return mixed |
584 | */ | |
d97c96dc | 585 | function _ipn_process_transaction(&$params, $contribution, $input, $ids, $firstContribution = NULL) { |
5fa7c328 EM |
586 | $objects = $contribution->_relatedObjects; |
587 | $objects['contribution'] = &$contribution; | |
d97c96dc EM |
588 | |
589 | if ($firstContribution) { | |
590 | $objects['first_contribution'] = $firstContribution; | |
591 | } | |
5fa7c328 EM |
592 | $input['component'] = $contribution->_component; |
593 | $input['is_test'] = $contribution->is_test; | |
96f0fe0d EM |
594 | $input['amount'] = empty($input['total_amount']) ? $contribution->total_amount : $input['total_amount']; |
595 | ||
5fa7c328 EM |
596 | if (isset($params['is_email_receipt'])) { |
597 | $input['is_email_receipt'] = $params['is_email_receipt']; | |
598 | } | |
7104593e | 599 | if (!empty($params['trxn_date'])) { |
600 | $input['trxn_date'] = $params['trxn_date']; | |
601 | } | |
0930231a EM |
602 | if (empty($contribution->contribution_page_id)) { |
603 | static $domainFromName; | |
604 | static $domainFromEmail; | |
605 | if (empty($domainFromEmail) && (empty($params['receipt_from_name']) || empty($params['receipt_from_email']))) { | |
37b8953e | 606 | list($domainFromName, $domainFromEmail) = CRM_Core_BAO_Domain::getNameAndEmail(TRUE); |
0930231a EM |
607 | } |
608 | $input['receipt_from_name'] = CRM_Utils_Array::value('receipt_from_name', $params, $domainFromName); | |
609 | $input['receipt_from_email'] = CRM_Utils_Array::value('receipt_from_email', $params, $domainFromEmail); | |
610 | } | |
4b6c8c1e | 611 | $transaction = new CRM_Core_Transaction(); |
59cdadfc | 612 | CRM_Contribute_BAO_Contribution::completeOrder($input, $ids, $objects, $transaction, !empty($contribution->contribution_recur_id), $contribution, |
613 | FALSE, FALSE); | |
5fa7c328 EM |
614 | return $params; |
615 | } | |
616 | ||
617 | /** | |
618 | * Provide function metadata. | |
619 | * | |
620 | * @param array $params | |
621 | */ | |
622 | function _civicrm_api3_contribution_repeattransaction_spec(&$params) { | |
623 | $params['original_contribution_id'] = array( | |
624 | 'title' => 'Original Contribution ID', | |
625 | 'type' => CRM_Utils_Type::T_INT, | |
626 | 'api.required' => TRUE, | |
627 | ); | |
628 | $params['trxn_id'] = array( | |
629 | 'title' => 'Transaction ID', | |
630 | 'type' => CRM_Utils_Type::T_STRING, | |
631 | ); | |
632 | $params['is_email_receipt'] = array( | |
633 | 'title' => 'Send email Receipt?', | |
634 | 'type' => CRM_Utils_Type::T_BOOLEAN, | |
635 | ); | |
636 | $params['contribution_status_id'] = array( | |
637 | 'title' => 'Contribution Status ID', | |
d97c96dc | 638 | 'name' => 'contribution_status_id', |
5fa7c328 EM |
639 | 'type' => CRM_Utils_Type::T_INT, |
640 | 'pseudoconstant' => array( | |
641 | 'optionGroupName' => 'contribution_status', | |
642 | ), | |
643 | 'api.required' => TRUE, | |
644 | ); | |
645 | $params['receive_date'] = array( | |
646 | 'title' => 'Contribution Receive Date', | |
d97c96dc | 647 | 'name' => 'receive_date', |
5fa7c328 EM |
648 | 'type' => CRM_Utils_Type::T_DATE, |
649 | 'api.default' => 'now', | |
650 | ); | |
d97c96dc EM |
651 | $params['trxn_id'] = array( |
652 | 'title' => 'Transaction ID', | |
653 | 'name' => 'trxn_id', | |
654 | 'type' => CRM_Utils_Type::T_STRING, | |
655 | ); | |
656 | $params['payment_processor_id'] = array( | |
657 | 'description' => ts('Payment processor ID, will be loaded from contribution_recur if not provided'), | |
658 | 'title' => 'Payment processor ID', | |
659 | 'name' => 'payment_processor_id', | |
660 | 'type' => CRM_Utils_Type::T_INT, | |
661 | ); | |
5fa7c328 | 662 | } |