Commit | Line | Data |
---|---|---|
d2545e26 PN |
1 | <?php |
2 | /* | |
3 | +--------------------------------------------------------------------+ | |
fee14197 | 4 | | CiviCRM version 5 | |
d2545e26 | 5 | +--------------------------------------------------------------------+ |
6b83d5bd | 6 | | Copyright CiviCRM LLC (c) 2004-2019 | |
d2545e26 PN |
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 | +--------------------------------------------------------------------+ | |
26 | */ | |
27 | ||
28 | /** | |
29 | * This api exposes CiviCRM Contribution Payment records. | |
30 | * | |
31 | * @package CiviCRM_APIv3 | |
32 | */ | |
33 | ||
34 | /** | |
35 | * Retrieve a set of financial transactions which are payments. | |
36 | * | |
37 | * @param array $params | |
38 | * Input parameters. | |
39 | * | |
40 | * @return array | |
41 | * Array of financial transactions which are payments, if error an array with an error id and error message | |
42 | */ | |
43 | function civicrm_api3_payment_get($params) { | |
cf8f0fff | 44 | $financialTrxn = []; |
cf33c6cb | 45 | $limit = ''; |
de6c59ca | 46 | if (isset($params['options']) && !empty($params['options']['limit'])) { |
cf33c6cb E |
47 | $limit = CRM_Utils_Array::value('limit', $params['options']); |
48 | } | |
49 | $params['options']['limit'] = 0; | |
c4204541 | 50 | if (isset($params['trxn_id'])) { |
51 | $params['financial_trxn_id.trxn_id'] = $params['trxn_id']; | |
52 | } | |
d2545e26 PN |
53 | $eft = civicrm_api3('EntityFinancialTrxn', 'get', $params); |
54 | if (!empty($eft['values'])) { | |
cf8f0fff | 55 | $eftIds = []; |
d2545e26 | 56 | foreach ($eft['values'] as $efts) { |
2ff2ff26 PN |
57 | if (empty($efts['financial_trxn_id'])) { |
58 | continue; | |
59 | } | |
d2545e26 PN |
60 | $eftIds[] = $efts['financial_trxn_id']; |
61 | $map[$efts['financial_trxn_id']] = $efts['entity_id']; | |
62 | } | |
2ff2ff26 | 63 | if (!empty($eftIds)) { |
cf8f0fff CW |
64 | $ftParams = [ |
65 | 'id' => ['IN' => $eftIds], | |
2ff2ff26 | 66 | 'is_payment' => 1, |
cf8f0fff | 67 | ]; |
2ff2ff26 PN |
68 | if ($limit) { |
69 | $ftParams['options']['limit'] = $limit; | |
70 | } | |
71 | $financialTrxn = civicrm_api3('FinancialTrxn', 'get', $ftParams); | |
72 | foreach ($financialTrxn['values'] as &$values) { | |
73 | $values['contribution_id'] = $map[$values['id']]; | |
74 | } | |
d2545e26 PN |
75 | } |
76 | } | |
cf8f0fff | 77 | return civicrm_api3_create_success(CRM_Utils_Array::value('values', $financialTrxn, []), $params, 'Payment', 'get'); |
d2545e26 PN |
78 | } |
79 | ||
80 | /** | |
81 | * Delete a payment. | |
82 | * | |
83 | * @param array $params | |
84 | * Input parameters. | |
85 | * | |
86 | * @throws API_Exception | |
87 | * @return array | |
88 | * Api result array | |
89 | */ | |
1c31aa41 | 90 | function civicrm_api3_payment_delete($params) { |
d2545e26 PN |
91 | return civicrm_api3('FinancialTrxn', 'delete', $params); |
92 | } | |
93 | ||
94 | /** | |
95 | * Cancel/Refund a payment for a Contribution. | |
96 | * | |
97 | * @param array $params | |
98 | * Input parameters. | |
99 | * | |
d2545e26 PN |
100 | * @return array |
101 | * Api result array | |
df29ccff | 102 | * |
103 | * @throws \CiviCRM_API3_Exception | |
104 | * @throws API_Exception | |
d2545e26 | 105 | */ |
1c31aa41 | 106 | function civicrm_api3_payment_cancel($params) { |
cf8f0fff | 107 | $eftParams = [ |
d2545e26 PN |
108 | 'entity_table' => 'civicrm_contribution', |
109 | 'financial_trxn_id' => $params['id'], | |
cf8f0fff | 110 | ]; |
d2545e26 | 111 | $entity = civicrm_api3('EntityFinancialTrxn', 'getsingle', $eftParams); |
d2545e26 | 112 | |
2561fc11 | 113 | $paymentParams = [ |
114 | 'total_amount' => -$entity['amount'], | |
115 | 'contribution_id' => $entity['entity_id'], | |
116 | 'trxn_date' => CRM_Utils_Array::value('trxn_date', $params, 'now'), | |
df29ccff | 117 | 'cancelled_payment_id' => $params['id'], |
2561fc11 | 118 | ]; |
d2545e26 | 119 | |
2561fc11 | 120 | foreach (['trxn_id', 'payment_instrument_id'] as $permittedParam) { |
121 | if (isset($params[$permittedParam])) { | |
122 | $paymentParams[$permittedParam] = $params[$permittedParam]; | |
123 | } | |
124 | } | |
125 | $result = civicrm_api3('Payment', 'create', $paymentParams); | |
126 | return civicrm_api3_create_success($result['values'], $params, 'Payment', 'cancel'); | |
d2545e26 PN |
127 | } |
128 | ||
129 | /** | |
130 | * Add a payment for a Contribution. | |
131 | * | |
132 | * @param array $params | |
133 | * Input parameters. | |
134 | * | |
d2545e26 PN |
135 | * @return array |
136 | * Api result array | |
a494d7a3 | 137 | * |
138 | * @throws \API_Exception | |
139 | * @throws \CRM_Core_Exception | |
140 | * @throws \CiviCRM_API3_Exception | |
d2545e26 | 141 | */ |
1c31aa41 | 142 | function civicrm_api3_payment_create($params) { |
b4c48831 | 143 | if (empty($params['skipCleanMoney'])) { |
144 | foreach (['total_amount', 'net_amount', 'fee_amount'] as $field) { | |
145 | if (isset($params[$field])) { | |
146 | $params[$field] = CRM_Utils_Rule::cleanMoney($params[$field]); | |
147 | } | |
148 | } | |
149 | } | |
6cc6cb8c | 150 | if (!empty($params['payment_processor'])) { |
151 | // I can't find evidence this is passed in - I was gonna just remove it but decided to deprecate as I see getToFinancialAccount | |
152 | // also anticipates it. | |
153 | CRM_Core_Error::deprecatedFunctionWarning('passing payment_processor is deprecated - use payment_processor_id'); | |
154 | $params['payment_processor_id'] = $params['payment_processor']; | |
155 | } | |
d2545e26 | 156 | // Check if it is an update |
de6c59ca | 157 | if (!empty($params['id'])) { |
d2545e26 PN |
158 | $amount = $params['total_amount']; |
159 | civicrm_api3('Payment', 'cancel', $params); | |
160 | $params['total_amount'] = $amount; | |
161 | } | |
0c9b306a | 162 | $trxn = CRM_Financial_BAO_Payment::create($params); |
5625fdf0 | 163 | |
cf8f0fff | 164 | $values = []; |
d2545e26 PN |
165 | _civicrm_api3_object_to_array_unique_fields($trxn, $values[$trxn->id]); |
166 | return civicrm_api3_create_success($values, $params, 'Payment', 'create', $trxn); | |
167 | } | |
168 | ||
169 | /** | |
170 | * Adjust Metadata for Create action. | |
171 | * | |
172 | * The metadata is used for setting defaults, documentation & validation. | |
173 | * | |
174 | * @param array $params | |
175 | * Array of parameters. | |
176 | */ | |
177 | function _civicrm_api3_payment_create_spec(&$params) { | |
cf8f0fff CW |
178 | $params = [ |
179 | 'contribution_id' => [ | |
7c31ae57 | 180 | 'api.required' => 1, |
d1987324 | 181 | 'title' => ts('Contribution ID'), |
d2545e26 | 182 | 'type' => CRM_Utils_Type::T_INT, |
e2887a3c | 183 | // We accept order_id as an alias so that we can chain like |
184 | // civicrm_api3('Order', 'create', ['blah' => 'blah', 'contribution_status_id' => 'Pending', 'api.Payment.create => ['total_amount' => 5]] | |
185 | 'api.aliases' => ['order_id'], | |
cf8f0fff CW |
186 | ], |
187 | 'total_amount' => [ | |
7c31ae57 | 188 | 'api.required' => 1, |
d1987324 | 189 | 'title' => ts('Total Payment Amount'), |
d2545e26 | 190 | 'type' => CRM_Utils_Type::T_FLOAT, |
cf8f0fff CW |
191 | ], |
192 | 'payment_processor_id' => [ | |
a494d7a3 | 193 | 'name' => 'payment_processor_id', |
d2545e26 | 194 | 'type' => CRM_Utils_Type::T_INT, |
a494d7a3 | 195 | 'title' => ts('Payment Processor'), |
196 | 'description' => ts('Payment Processor for this payment'), | |
197 | 'where' => 'civicrm_financial_trxn.payment_processor_id', | |
198 | 'table_name' => 'civicrm_financial_trxn', | |
199 | 'entity' => 'FinancialTrxn', | |
200 | 'bao' => 'CRM_Financial_DAO_FinancialTrxn', | |
201 | 'localizable' => 0, | |
202 | 'FKClassName' => 'CRM_Financial_DAO_PaymentProcessor', | |
cf8f0fff CW |
203 | ], |
204 | 'id' => [ | |
d1987324 | 205 | 'title' => ts('Payment ID'), |
d2545e26 | 206 | 'type' => CRM_Utils_Type::T_INT, |
cf8f0fff CW |
207 | 'api.aliases' => ['payment_id'], |
208 | ], | |
2561fc11 | 209 | 'trxn_date' => [ |
4c68d684 | 210 | 'title' => ts('Payment Date'), |
2561fc11 | 211 | 'type' => CRM_Utils_Type::T_DATE + CRM_Utils_Type::T_TIME, |
4c68d684 | 212 | 'api.default' => 'now', |
213 | 'api.required' => TRUE, | |
2561fc11 | 214 | ], |
bd981689 | 215 | 'is_send_contribution_notification' => [ |
216 | 'title' => ts('Send out notifications based on contribution status change?'), | |
217 | 'description' => ts('Most commonly this equates to emails relating to the contribution, event, etcwhen a payment completes a contribution'), | |
218 | 'type' => CRM_Utils_Type::T_BOOLEAN, | |
219 | 'api.default' => TRUE, | |
220 | ], | |
a494d7a3 | 221 | 'payment_instrument_id' => [ |
222 | 'name' => 'payment_instrument_id', | |
223 | 'type' => CRM_Utils_Type::T_INT, | |
224 | 'title' => ts('Payment Method'), | |
225 | 'description' => ts('FK to payment_instrument option group values'), | |
226 | 'where' => 'civicrm_financial_trxn.payment_instrument_id', | |
227 | 'table_name' => 'civicrm_financial_trxn', | |
228 | 'entity' => 'FinancialTrxn', | |
229 | 'bao' => 'CRM_Financial_DAO_FinancialTrxn', | |
230 | 'localizable' => 0, | |
231 | 'html' => [ | |
232 | 'type' => 'Select', | |
233 | ], | |
234 | 'pseudoconstant' => [ | |
235 | 'optionGroupName' => 'payment_instrument', | |
236 | 'optionEditPath' => 'civicrm/admin/options/payment_instrument', | |
237 | ], | |
238 | ], | |
239 | 'card_type_id' => [ | |
240 | 'name' => 'card_type_id', | |
241 | 'type' => CRM_Utils_Type::T_INT, | |
242 | 'title' => ts('Card Type ID'), | |
243 | 'description' => ts('FK to accept_creditcard option group values'), | |
244 | 'where' => 'civicrm_financial_trxn.card_type_id', | |
245 | 'table_name' => 'civicrm_financial_trxn', | |
246 | 'entity' => 'FinancialTrxn', | |
247 | 'bao' => 'CRM_Financial_DAO_FinancialTrxn', | |
248 | 'localizable' => 0, | |
249 | 'html' => [ | |
250 | 'type' => 'Select', | |
251 | ], | |
252 | 'pseudoconstant' => [ | |
253 | 'optionGroupName' => 'accept_creditcard', | |
254 | 'optionEditPath' => 'civicrm/admin/options/accept_creditcard', | |
255 | ], | |
256 | ], | |
257 | 'trxn_result_code' => [ | |
258 | 'name' => 'trxn_result_code', | |
259 | 'type' => CRM_Utils_Type::T_STRING, | |
260 | 'title' => ts('Transaction Result Code'), | |
261 | 'description' => ts('processor result code'), | |
262 | 'maxlength' => 255, | |
263 | 'size' => CRM_Utils_Type::HUGE, | |
264 | 'where' => 'civicrm_financial_trxn.trxn_result_code', | |
265 | 'table_name' => 'civicrm_financial_trxn', | |
266 | 'entity' => 'FinancialTrxn', | |
267 | 'bao' => 'CRM_Financial_DAO_FinancialTrxn', | |
268 | 'localizable' => 0, | |
269 | ], | |
270 | 'trxn_id' => [ | |
271 | 'name' => 'trxn_id', | |
272 | 'type' => CRM_Utils_Type::T_STRING, | |
273 | 'title' => ts('Transaction ID'), | |
274 | 'description' => ts('Transaction id supplied by external processor. This may not be unique.'), | |
275 | 'maxlength' => 255, | |
276 | 'size' => 10, | |
277 | 'where' => 'civicrm_financial_trxn.trxn_id', | |
278 | 'table_name' => 'civicrm_financial_trxn', | |
279 | 'entity' => 'FinancialTrxn', | |
280 | 'bao' => 'CRM_Financial_DAO_FinancialTrxn', | |
281 | 'localizable' => 0, | |
282 | 'html' => [ | |
283 | 'type' => 'Text', | |
284 | ], | |
285 | ], | |
286 | 'check_number' => [ | |
287 | 'name' => 'check_number', | |
288 | 'type' => CRM_Utils_Type::T_STRING, | |
289 | 'title' => ts('Check Number'), | |
290 | 'description' => ts('Check number'), | |
291 | 'maxlength' => 255, | |
292 | 'size' => 6, | |
293 | 'where' => 'civicrm_financial_trxn.check_number', | |
294 | 'table_name' => 'civicrm_financial_trxn', | |
295 | 'entity' => 'FinancialTrxn', | |
296 | 'bao' => 'CRM_Financial_DAO_FinancialTrxn', | |
297 | 'localizable' => 0, | |
298 | 'html' => [ | |
299 | 'type' => 'Text', | |
300 | ], | |
301 | ], | |
302 | 'pan_truncation' => [ | |
303 | 'name' => 'pan_truncation', | |
304 | 'type' => CRM_Utils_Type::T_STRING, | |
305 | 'title' => ts('Pan Truncation'), | |
306 | 'description' => ts('Last 4 digits of credit card'), | |
307 | 'maxlength' => 4, | |
308 | 'size' => 4, | |
309 | 'where' => 'civicrm_financial_trxn.pan_truncation', | |
310 | 'table_name' => 'civicrm_financial_trxn', | |
311 | 'entity' => 'FinancialTrxn', | |
312 | 'bao' => 'CRM_Financial_DAO_FinancialTrxn', | |
313 | 'localizable' => 0, | |
314 | 'html' => [ | |
315 | 'type' => 'Text', | |
316 | ], | |
317 | ], | |
cf8f0fff | 318 | ]; |
d2545e26 PN |
319 | } |
320 | ||
321 | /** | |
322 | * Adjust Metadata for Get action. | |
323 | * | |
324 | * The metadata is used for setting defaults, documentation & validation. | |
325 | * | |
326 | * @param array $params | |
327 | * Array of parameters determined by getfields. | |
328 | */ | |
329 | function _civicrm_api3_payment_get_spec(&$params) { | |
cf8f0fff CW |
330 | $params = [ |
331 | 'contribution_id' => [ | |
4c68d684 | 332 | 'title' => ts('Contribution ID'), |
d2545e26 | 333 | 'type' => CRM_Utils_Type::T_INT, |
cf8f0fff CW |
334 | ], |
335 | 'entity_table' => [ | |
4c68d684 | 336 | 'title' => ts('Entity Table'), |
d2545e26 | 337 | 'api.default' => 'civicrm_contribution', |
cf8f0fff CW |
338 | ], |
339 | 'entity_id' => [ | |
4c68d684 | 340 | 'title' => ts('Entity ID'), |
d2545e26 | 341 | 'type' => CRM_Utils_Type::T_INT, |
cf8f0fff CW |
342 | 'api.aliases' => ['contribution_id'], |
343 | ], | |
c4204541 | 344 | 'trxn_id' => [ |
4c68d684 | 345 | 'title' => ts('Transaction ID'), |
c4204541 | 346 | 'type' => CRM_Utils_Type::T_STRING, |
347 | ], | |
4c68d684 | 348 | 'trxn_date' => [ |
349 | 'title' => ts('Payment Date'), | |
350 | 'type' => CRM_Utils_Type::T_TIMESTAMP, | |
351 | ], | |
cf8f0fff | 352 | ]; |
d2545e26 PN |
353 | } |
354 | ||
355 | /** | |
356 | * Adjust Metadata for Delete action. | |
357 | * | |
358 | * The metadata is used for setting defaults, documentation & validation. | |
359 | * | |
360 | * @param array $params | |
361 | * Array of parameters. | |
362 | */ | |
363 | function _civicrm_api3_payment_delete_spec(&$params) { | |
cf8f0fff CW |
364 | $params = [ |
365 | 'id' => [ | |
7c31ae57 | 366 | 'api.required' => 1, |
d2545e26 PN |
367 | 'title' => 'Payment ID', |
368 | 'type' => CRM_Utils_Type::T_INT, | |
cf8f0fff CW |
369 | 'api.aliases' => ['payment_id'], |
370 | ], | |
371 | ]; | |
d2545e26 PN |
372 | } |
373 | ||
374 | /** | |
375 | * Adjust Metadata for Cancel action. | |
376 | * | |
377 | * The metadata is used for setting defaults, documentation & validation. | |
378 | * | |
379 | * @param array $params | |
380 | * Array of parameters. | |
381 | */ | |
382 | function _civicrm_api3_payment_cancel_spec(&$params) { | |
cf8f0fff CW |
383 | $params = [ |
384 | 'id' => [ | |
7c31ae57 | 385 | 'api.required' => 1, |
d2545e26 PN |
386 | 'title' => 'Payment ID', |
387 | 'type' => CRM_Utils_Type::T_INT, | |
cf8f0fff CW |
388 | 'api.aliases' => ['payment_id'], |
389 | ], | |
2561fc11 | 390 | 'trxn_date' => [ |
391 | 'title' => 'Cancel Date', | |
392 | 'type' => CRM_Utils_Type::T_DATE + CRM_Utils_Type::T_TIME, | |
393 | ], | |
cf8f0fff | 394 | ]; |
d2545e26 | 395 | } |
a79d2ec2 | 396 | |
397 | /** | |
398 | * Send a payment confirmation. | |
399 | * | |
400 | * @param array $params | |
401 | * Input parameters. | |
402 | * | |
403 | * @return array | |
404 | * @throws Exception | |
405 | */ | |
406 | function civicrm_api3_payment_sendconfirmation($params) { | |
407 | $allowedParams = [ | |
44a2f017 | 408 | 'from', |
a79d2ec2 | 409 | 'id', |
44a2f017 | 410 | 'check_permissions', |
a79d2ec2 | 411 | ]; |
412 | $input = array_intersect_key($params, array_flip($allowedParams)); | |
413 | // use either the contribution or membership receipt, based on whether it’s a membership-related contrib or not | |
414 | $result = CRM_Financial_BAO_Payment::sendConfirmation($input); | |
415 | return civicrm_api3_create_success([ | |
416 | $params['id'] => [ | |
417 | 'is_sent' => $result[0], | |
418 | 'subject' => $result[1], | |
419 | 'message_txt' => $result[2], | |
420 | 'message_html' => $result[3], | |
7c31ae57 SL |
421 | ], |
422 | ]); | |
a79d2ec2 | 423 | } |
424 | ||
425 | /** | |
426 | * Adjust Metadata for sendconfirmation action. | |
427 | * | |
428 | * The metadata is used for setting defaults, documentation & validation. | |
429 | * | |
430 | * @param array $params | |
431 | * Array of parameters determined by getfields. | |
432 | */ | |
433 | function _civicrm_api3_payment_sendconfirmation_spec(&$params) { | |
cf8f0fff | 434 | $params['id'] = [ |
a79d2ec2 | 435 | 'api.required' => 1, |
436 | 'title' => ts('Payment ID'), | |
437 | 'type' => CRM_Utils_Type::T_INT, | |
cf8f0fff | 438 | ]; |
44a2f017 | 439 | $params['from_email_address'] = [ |
440 | 'title' => ts('From email; an email string or the id of a valid email'), | |
441 | 'type' => CRM_Utils_Type::T_STRING, | |
442 | ]; | |
6ac768e7 | 443 | $params['is_send_contribution_notification'] = [ |
444 | 'title' => ts('Send any event or contribution confirmations triggered by this payment'), | |
445 | 'description' => ts('If this payment completes a contribution it may mean receipts will go out according to busines logic if thie is set to TRUE'), | |
446 | 'type' => CRM_Utils_Type::T_BOOLEAN, | |
447 | 'api.default' => 0, | |
448 | ]; | |
a79d2ec2 | 449 | } |