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; | |
d2545e26 PN |
50 | $eft = civicrm_api3('EntityFinancialTrxn', 'get', $params); |
51 | if (!empty($eft['values'])) { | |
cf8f0fff | 52 | $eftIds = []; |
d2545e26 | 53 | foreach ($eft['values'] as $efts) { |
2ff2ff26 PN |
54 | if (empty($efts['financial_trxn_id'])) { |
55 | continue; | |
56 | } | |
d2545e26 PN |
57 | $eftIds[] = $efts['financial_trxn_id']; |
58 | $map[$efts['financial_trxn_id']] = $efts['entity_id']; | |
59 | } | |
2ff2ff26 | 60 | if (!empty($eftIds)) { |
cf8f0fff CW |
61 | $ftParams = [ |
62 | 'id' => ['IN' => $eftIds], | |
2ff2ff26 | 63 | 'is_payment' => 1, |
cf8f0fff | 64 | ]; |
2ff2ff26 PN |
65 | if ($limit) { |
66 | $ftParams['options']['limit'] = $limit; | |
67 | } | |
68 | $financialTrxn = civicrm_api3('FinancialTrxn', 'get', $ftParams); | |
69 | foreach ($financialTrxn['values'] as &$values) { | |
70 | $values['contribution_id'] = $map[$values['id']]; | |
71 | } | |
d2545e26 PN |
72 | } |
73 | } | |
cf8f0fff | 74 | return civicrm_api3_create_success(CRM_Utils_Array::value('values', $financialTrxn, []), $params, 'Payment', 'get'); |
d2545e26 PN |
75 | } |
76 | ||
77 | /** | |
78 | * Delete a payment. | |
79 | * | |
80 | * @param array $params | |
81 | * Input parameters. | |
82 | * | |
83 | * @throws API_Exception | |
84 | * @return array | |
85 | * Api result array | |
86 | */ | |
1c31aa41 | 87 | function civicrm_api3_payment_delete($params) { |
d2545e26 PN |
88 | return civicrm_api3('FinancialTrxn', 'delete', $params); |
89 | } | |
90 | ||
91 | /** | |
92 | * Cancel/Refund a payment for a Contribution. | |
93 | * | |
94 | * @param array $params | |
95 | * Input parameters. | |
96 | * | |
97 | * @throws API_Exception | |
98 | * @return array | |
99 | * Api result array | |
100 | */ | |
1c31aa41 | 101 | function civicrm_api3_payment_cancel($params) { |
cf8f0fff | 102 | $eftParams = [ |
d2545e26 PN |
103 | 'entity_table' => 'civicrm_contribution', |
104 | 'financial_trxn_id' => $params['id'], | |
cf8f0fff | 105 | ]; |
d2545e26 | 106 | $entity = civicrm_api3('EntityFinancialTrxn', 'getsingle', $eftParams); |
d2545e26 | 107 | |
2561fc11 | 108 | $paymentParams = [ |
109 | 'total_amount' => -$entity['amount'], | |
110 | 'contribution_id' => $entity['entity_id'], | |
111 | 'trxn_date' => CRM_Utils_Array::value('trxn_date', $params, 'now'), | |
112 | ]; | |
d2545e26 | 113 | |
2561fc11 | 114 | foreach (['trxn_id', 'payment_instrument_id'] as $permittedParam) { |
115 | if (isset($params[$permittedParam])) { | |
116 | $paymentParams[$permittedParam] = $params[$permittedParam]; | |
117 | } | |
118 | } | |
119 | $result = civicrm_api3('Payment', 'create', $paymentParams); | |
120 | return civicrm_api3_create_success($result['values'], $params, 'Payment', 'cancel'); | |
d2545e26 PN |
121 | } |
122 | ||
123 | /** | |
124 | * Add a payment for a Contribution. | |
125 | * | |
126 | * @param array $params | |
127 | * Input parameters. | |
128 | * | |
129 | * @throws API_Exception | |
130 | * @return array | |
131 | * Api result array | |
132 | */ | |
1c31aa41 | 133 | function civicrm_api3_payment_create($params) { |
d2545e26 | 134 | // Check if it is an update |
de6c59ca | 135 | if (!empty($params['id'])) { |
d2545e26 PN |
136 | $amount = $params['total_amount']; |
137 | civicrm_api3('Payment', 'cancel', $params); | |
138 | $params['total_amount'] = $amount; | |
139 | } | |
0c9b306a | 140 | $trxn = CRM_Financial_BAO_Payment::create($params); |
5625fdf0 | 141 | |
cf8f0fff | 142 | $values = []; |
d2545e26 PN |
143 | _civicrm_api3_object_to_array_unique_fields($trxn, $values[$trxn->id]); |
144 | return civicrm_api3_create_success($values, $params, 'Payment', 'create', $trxn); | |
145 | } | |
146 | ||
147 | /** | |
148 | * Adjust Metadata for Create action. | |
149 | * | |
150 | * The metadata is used for setting defaults, documentation & validation. | |
151 | * | |
152 | * @param array $params | |
153 | * Array of parameters. | |
154 | */ | |
155 | function _civicrm_api3_payment_create_spec(&$params) { | |
cf8f0fff CW |
156 | $params = [ |
157 | 'contribution_id' => [ | |
7c31ae57 | 158 | 'api.required' => 1, |
d1987324 | 159 | 'title' => ts('Contribution ID'), |
d2545e26 | 160 | 'type' => CRM_Utils_Type::T_INT, |
cf8f0fff CW |
161 | ], |
162 | 'total_amount' => [ | |
7c31ae57 | 163 | 'api.required' => 1, |
d1987324 | 164 | 'title' => ts('Total Payment Amount'), |
d2545e26 | 165 | 'type' => CRM_Utils_Type::T_FLOAT, |
cf8f0fff CW |
166 | ], |
167 | 'payment_processor_id' => [ | |
d1987324 | 168 | 'title' => ts('Payment Processor ID'), |
d2545e26 PN |
169 | 'type' => CRM_Utils_Type::T_INT, |
170 | 'description' => ts('Payment processor ID - required for payment processor payments'), | |
cf8f0fff CW |
171 | ], |
172 | 'id' => [ | |
d1987324 | 173 | 'title' => ts('Payment ID'), |
d2545e26 | 174 | 'type' => CRM_Utils_Type::T_INT, |
cf8f0fff CW |
175 | 'api.aliases' => ['payment_id'], |
176 | ], | |
2561fc11 | 177 | 'trxn_date' => [ |
d1987324 | 178 | 'title' => ts('Cancel Date'), |
2561fc11 | 179 | 'type' => CRM_Utils_Type::T_DATE + CRM_Utils_Type::T_TIME, |
180 | ], | |
bd981689 | 181 | 'is_send_contribution_notification' => [ |
182 | 'title' => ts('Send out notifications based on contribution status change?'), | |
183 | 'description' => ts('Most commonly this equates to emails relating to the contribution, event, etcwhen a payment completes a contribution'), | |
184 | 'type' => CRM_Utils_Type::T_BOOLEAN, | |
185 | 'api.default' => TRUE, | |
186 | ], | |
cf8f0fff | 187 | ]; |
d2545e26 PN |
188 | } |
189 | ||
190 | /** | |
191 | * Adjust Metadata for Get action. | |
192 | * | |
193 | * The metadata is used for setting defaults, documentation & validation. | |
194 | * | |
195 | * @param array $params | |
196 | * Array of parameters determined by getfields. | |
197 | */ | |
198 | function _civicrm_api3_payment_get_spec(&$params) { | |
cf8f0fff CW |
199 | $params = [ |
200 | 'contribution_id' => [ | |
d2545e26 PN |
201 | 'title' => 'Contribution ID', |
202 | 'type' => CRM_Utils_Type::T_INT, | |
cf8f0fff CW |
203 | ], |
204 | 'entity_table' => [ | |
d2545e26 PN |
205 | 'title' => 'Entity Table', |
206 | 'api.default' => 'civicrm_contribution', | |
cf8f0fff CW |
207 | ], |
208 | 'entity_id' => [ | |
d2545e26 PN |
209 | 'title' => 'Entity ID', |
210 | 'type' => CRM_Utils_Type::T_INT, | |
cf8f0fff CW |
211 | 'api.aliases' => ['contribution_id'], |
212 | ], | |
213 | ]; | |
d2545e26 PN |
214 | } |
215 | ||
216 | /** | |
217 | * Adjust Metadata for Delete action. | |
218 | * | |
219 | * The metadata is used for setting defaults, documentation & validation. | |
220 | * | |
221 | * @param array $params | |
222 | * Array of parameters. | |
223 | */ | |
224 | function _civicrm_api3_payment_delete_spec(&$params) { | |
cf8f0fff CW |
225 | $params = [ |
226 | 'id' => [ | |
7c31ae57 | 227 | 'api.required' => 1, |
d2545e26 PN |
228 | 'title' => 'Payment ID', |
229 | 'type' => CRM_Utils_Type::T_INT, | |
cf8f0fff CW |
230 | 'api.aliases' => ['payment_id'], |
231 | ], | |
232 | ]; | |
d2545e26 PN |
233 | } |
234 | ||
235 | /** | |
236 | * Adjust Metadata for Cancel action. | |
237 | * | |
238 | * The metadata is used for setting defaults, documentation & validation. | |
239 | * | |
240 | * @param array $params | |
241 | * Array of parameters. | |
242 | */ | |
243 | function _civicrm_api3_payment_cancel_spec(&$params) { | |
cf8f0fff CW |
244 | $params = [ |
245 | 'id' => [ | |
7c31ae57 | 246 | 'api.required' => 1, |
d2545e26 PN |
247 | 'title' => 'Payment ID', |
248 | 'type' => CRM_Utils_Type::T_INT, | |
cf8f0fff CW |
249 | 'api.aliases' => ['payment_id'], |
250 | ], | |
2561fc11 | 251 | 'trxn_date' => [ |
252 | 'title' => 'Cancel Date', | |
253 | 'type' => CRM_Utils_Type::T_DATE + CRM_Utils_Type::T_TIME, | |
254 | ], | |
cf8f0fff | 255 | ]; |
d2545e26 | 256 | } |
a79d2ec2 | 257 | |
258 | /** | |
259 | * Send a payment confirmation. | |
260 | * | |
261 | * @param array $params | |
262 | * Input parameters. | |
263 | * | |
264 | * @return array | |
265 | * @throws Exception | |
266 | */ | |
267 | function civicrm_api3_payment_sendconfirmation($params) { | |
268 | $allowedParams = [ | |
269 | 'receipt_from_email', | |
270 | 'receipt_from_name', | |
271 | 'cc_receipt', | |
272 | 'bcc_receipt', | |
273 | 'receipt_text', | |
274 | 'id', | |
275 | ]; | |
276 | $input = array_intersect_key($params, array_flip($allowedParams)); | |
277 | // use either the contribution or membership receipt, based on whether it’s a membership-related contrib or not | |
278 | $result = CRM_Financial_BAO_Payment::sendConfirmation($input); | |
279 | return civicrm_api3_create_success([ | |
280 | $params['id'] => [ | |
281 | 'is_sent' => $result[0], | |
282 | 'subject' => $result[1], | |
283 | 'message_txt' => $result[2], | |
284 | 'message_html' => $result[3], | |
7c31ae57 SL |
285 | ], |
286 | ]); | |
a79d2ec2 | 287 | } |
288 | ||
289 | /** | |
290 | * Adjust Metadata for sendconfirmation action. | |
291 | * | |
292 | * The metadata is used for setting defaults, documentation & validation. | |
293 | * | |
294 | * @param array $params | |
295 | * Array of parameters determined by getfields. | |
296 | */ | |
297 | function _civicrm_api3_payment_sendconfirmation_spec(&$params) { | |
cf8f0fff | 298 | $params['id'] = [ |
a79d2ec2 | 299 | 'api.required' => 1, |
300 | 'title' => ts('Payment ID'), | |
301 | 'type' => CRM_Utils_Type::T_INT, | |
cf8f0fff | 302 | ]; |
a79d2ec2 | 303 | } |