3 +--------------------------------------------------------------------+
4 | Copyright CiviCRM LLC. All rights reserved. |
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 |
9 +--------------------------------------------------------------------+
13 * This api exposes CiviCRM Contribution Payment records.
15 * @package CiviCRM_APIv3
19 * Retrieve a set of financial transactions which are payments.
21 * @param array $params
25 * Array of financial transactions which are payments, if error an array with an error id and error message
27 function civicrm_api3_payment_get($params) {
30 if (isset($params['options']) && !empty($params['options']['limit'])) {
31 $limit = CRM_Utils_Array
::value('limit', $params['options']);
33 $params['options']['limit'] = 0;
34 if (isset($params['trxn_id'])) {
35 $params['financial_trxn_id.trxn_id'] = $params['trxn_id'];
37 $eft = civicrm_api3('EntityFinancialTrxn', 'get', $params);
38 if (!empty($eft['values'])) {
40 foreach ($eft['values'] as $efts) {
41 if (empty($efts['financial_trxn_id'])) {
44 $eftIds[] = $efts['financial_trxn_id'];
45 $map[$efts['financial_trxn_id']] = $efts['entity_id'];
47 if (!empty($eftIds)) {
49 'id' => ['IN' => $eftIds],
53 $ftParams['options']['limit'] = $limit;
55 $financialTrxn = civicrm_api3('FinancialTrxn', 'get', $ftParams);
56 foreach ($financialTrxn['values'] as &$values) {
57 $values['contribution_id'] = $map[$values['id']];
61 return civicrm_api3_create_success(CRM_Utils_Array
::value('values', $financialTrxn, []), $params, 'Payment', 'get');
67 * @param array $params
70 * @throws API_Exception
74 function civicrm_api3_payment_delete($params) {
75 return civicrm_api3('FinancialTrxn', 'delete', $params);
79 * Cancel/Refund a payment for a Contribution.
81 * @param array $params
87 * @throws \CiviCRM_API3_Exception
88 * @throws API_Exception
90 function civicrm_api3_payment_cancel($params) {
92 'entity_table' => 'civicrm_contribution',
93 'financial_trxn_id' => $params['id'],
95 $entity = civicrm_api3('EntityFinancialTrxn', 'getsingle', $eftParams);
98 'total_amount' => -$entity['amount'],
99 'contribution_id' => $entity['entity_id'],
100 'trxn_date' => CRM_Utils_Array
::value('trxn_date', $params, 'now'),
101 'cancelled_payment_id' => $params['id'],
104 foreach (['trxn_id', 'payment_instrument_id'] as $permittedParam) {
105 if (isset($params[$permittedParam])) {
106 $paymentParams[$permittedParam] = $params[$permittedParam];
109 $result = civicrm_api3('Payment', 'create', $paymentParams);
110 return civicrm_api3_create_success($result['values'], $params, 'Payment', 'cancel');
114 * Add a payment for a Contribution.
116 * @param array $params
122 * @throws \API_Exception
123 * @throws \CRM_Core_Exception
124 * @throws \CiviCRM_API3_Exception
126 function civicrm_api3_payment_create($params) {
127 if (empty($params['skipCleanMoney'])) {
128 foreach (['total_amount', 'net_amount', 'fee_amount'] as $field) {
129 if (isset($params[$field])) {
130 $params[$field] = CRM_Utils_Rule
::cleanMoney($params[$field]);
134 if (!empty($params['payment_processor'])) {
135 // I can't find evidence this is passed in - I was gonna just remove it but decided to deprecate as I see getToFinancialAccount
136 // also anticipates it.
137 CRM_Core_Error
::deprecatedFunctionWarning('passing payment_processor is deprecated - use payment_processor_id');
138 $params['payment_processor_id'] = $params['payment_processor'];
140 // Check if it is an update
141 if (!empty($params['id'])) {
142 $amount = $params['total_amount'];
143 civicrm_api3('Payment', 'cancel', $params);
144 $params['total_amount'] = $amount;
146 $trxn = CRM_Financial_BAO_Payment
::create($params);
149 _civicrm_api3_object_to_array_unique_fields($trxn, $values[$trxn->id
]);
150 return civicrm_api3_create_success($values, $params, 'Payment', 'create', $trxn);
154 * Adjust Metadata for Create action.
156 * The metadata is used for setting defaults, documentation & validation.
158 * @param array $params
159 * Array of parameters.
161 function _civicrm_api3_payment_create_spec(&$params) {
163 'contribution_id' => [
165 'title' => ts('Contribution ID'),
166 'type' => CRM_Utils_Type
::T_INT
,
167 // We accept order_id as an alias so that we can chain like
168 // civicrm_api3('Order', 'create', ['blah' => 'blah', 'contribution_status_id' => 'Pending', 'api.Payment.create => ['total_amount' => 5]]
169 'api.aliases' => ['order_id'],
173 'title' => ts('Total Payment Amount'),
174 'type' => CRM_Utils_Type
::T_FLOAT
,
176 'payment_processor_id' => [
177 'name' => 'payment_processor_id',
178 'type' => CRM_Utils_Type
::T_INT
,
179 'title' => ts('Payment Processor'),
180 'description' => ts('Payment Processor for this payment'),
181 'where' => 'civicrm_financial_trxn.payment_processor_id',
182 'table_name' => 'civicrm_financial_trxn',
183 'entity' => 'FinancialTrxn',
184 'bao' => 'CRM_Financial_DAO_FinancialTrxn',
186 'FKClassName' => 'CRM_Financial_DAO_PaymentProcessor',
189 'title' => ts('Payment ID'),
190 'type' => CRM_Utils_Type
::T_INT
,
191 'api.aliases' => ['payment_id'],
194 'title' => ts('Payment Date'),
195 'type' => CRM_Utils_Type
::T_DATE + CRM_Utils_Type
::T_TIME
,
196 'api.default' => 'now',
197 'api.required' => TRUE,
199 'is_send_contribution_notification' => [
200 'title' => ts('Send out notifications based on contribution status change?'),
201 'description' => ts('Most commonly this equates to emails relating to the contribution, event, etcwhen a payment completes a contribution'),
202 'type' => CRM_Utils_Type
::T_BOOLEAN
,
203 'api.default' => TRUE,
205 'payment_instrument_id' => [
206 'name' => 'payment_instrument_id',
207 'type' => CRM_Utils_Type
::T_INT
,
208 'title' => ts('Payment Method'),
209 'description' => ts('FK to payment_instrument option group values'),
210 'where' => 'civicrm_financial_trxn.payment_instrument_id',
211 'table_name' => 'civicrm_financial_trxn',
212 'entity' => 'FinancialTrxn',
213 'bao' => 'CRM_Financial_DAO_FinancialTrxn',
218 'pseudoconstant' => [
219 'optionGroupName' => 'payment_instrument',
220 'optionEditPath' => 'civicrm/admin/options/payment_instrument',
224 'name' => 'card_type_id',
225 'type' => CRM_Utils_Type
::T_INT
,
226 'title' => ts('Card Type ID'),
227 'description' => ts('FK to accept_creditcard option group values'),
228 'where' => 'civicrm_financial_trxn.card_type_id',
229 'table_name' => 'civicrm_financial_trxn',
230 'entity' => 'FinancialTrxn',
231 'bao' => 'CRM_Financial_DAO_FinancialTrxn',
236 'pseudoconstant' => [
237 'optionGroupName' => 'accept_creditcard',
238 'optionEditPath' => 'civicrm/admin/options/accept_creditcard',
241 'trxn_result_code' => [
242 'name' => 'trxn_result_code',
243 'type' => CRM_Utils_Type
::T_STRING
,
244 'title' => ts('Transaction Result Code'),
245 'description' => ts('processor result code'),
247 'size' => CRM_Utils_Type
::HUGE
,
248 'where' => 'civicrm_financial_trxn.trxn_result_code',
249 'table_name' => 'civicrm_financial_trxn',
250 'entity' => 'FinancialTrxn',
251 'bao' => 'CRM_Financial_DAO_FinancialTrxn',
256 'type' => CRM_Utils_Type
::T_STRING
,
257 'title' => ts('Transaction ID'),
258 'description' => ts('Transaction id supplied by external processor. This may not be unique.'),
261 'where' => 'civicrm_financial_trxn.trxn_id',
262 'table_name' => 'civicrm_financial_trxn',
263 'entity' => 'FinancialTrxn',
264 'bao' => 'CRM_Financial_DAO_FinancialTrxn',
271 'name' => 'check_number',
272 'type' => CRM_Utils_Type
::T_STRING
,
273 'title' => ts('Check Number'),
274 'description' => ts('Check number'),
277 'where' => 'civicrm_financial_trxn.check_number',
278 'table_name' => 'civicrm_financial_trxn',
279 'entity' => 'FinancialTrxn',
280 'bao' => 'CRM_Financial_DAO_FinancialTrxn',
286 'pan_truncation' => [
287 'name' => 'pan_truncation',
288 'type' => CRM_Utils_Type
::T_STRING
,
289 'title' => ts('Pan Truncation'),
290 'description' => ts('Last 4 digits of credit card'),
293 'where' => 'civicrm_financial_trxn.pan_truncation',
294 'table_name' => 'civicrm_financial_trxn',
295 'entity' => 'FinancialTrxn',
296 'bao' => 'CRM_Financial_DAO_FinancialTrxn',
306 * Adjust Metadata for Get action.
308 * The metadata is used for setting defaults, documentation & validation.
310 * @param array $params
311 * Array of parameters determined by getfields.
313 function _civicrm_api3_payment_get_spec(&$params) {
315 'contribution_id' => [
316 'title' => ts('Contribution ID'),
317 'type' => CRM_Utils_Type
::T_INT
,
320 'title' => ts('Entity Table'),
321 'api.default' => 'civicrm_contribution',
324 'title' => ts('Entity ID'),
325 'type' => CRM_Utils_Type
::T_INT
,
326 'api.aliases' => ['contribution_id'],
329 'title' => ts('Transaction ID'),
330 'type' => CRM_Utils_Type
::T_STRING
,
333 'title' => ts('Payment Date'),
334 'type' => CRM_Utils_Type
::T_TIMESTAMP
,
340 * Adjust Metadata for Delete action.
342 * The metadata is used for setting defaults, documentation & validation.
344 * @param array $params
345 * Array of parameters.
347 function _civicrm_api3_payment_delete_spec(&$params) {
351 'title' => 'Payment ID',
352 'type' => CRM_Utils_Type
::T_INT
,
353 'api.aliases' => ['payment_id'],
359 * Adjust Metadata for Cancel action.
361 * The metadata is used for setting defaults, documentation & validation.
363 * @param array $params
364 * Array of parameters.
366 function _civicrm_api3_payment_cancel_spec(&$params) {
370 'title' => 'Payment ID',
371 'type' => CRM_Utils_Type
::T_INT
,
372 'api.aliases' => ['payment_id'],
375 'title' => 'Cancel Date',
376 'type' => CRM_Utils_Type
::T_DATE + CRM_Utils_Type
::T_TIME
,
382 * Send a payment confirmation.
384 * @param array $params
390 function civicrm_api3_payment_sendconfirmation($params) {
396 $input = array_intersect_key($params, array_flip($allowedParams));
397 // use either the contribution or membership receipt, based on whether it’s a membership-related contrib or not
398 $result = CRM_Financial_BAO_Payment
::sendConfirmation($input);
399 return civicrm_api3_create_success([
401 'is_sent' => $result[0],
402 'subject' => $result[1],
403 'message_txt' => $result[2],
404 'message_html' => $result[3],
410 * Adjust Metadata for sendconfirmation action.
412 * The metadata is used for setting defaults, documentation & validation.
414 * @param array $params
415 * Array of parameters determined by getfields.
417 function _civicrm_api3_payment_sendconfirmation_spec(&$params) {
420 'title' => ts('Payment ID'),
421 'type' => CRM_Utils_Type
::T_INT
,
423 $params['from_email_address'] = [
424 'title' => ts('From email; an email string or the id of a valid email'),
425 'type' => CRM_Utils_Type
::T_STRING
,
427 $params['is_send_contribution_notification'] = [
428 'title' => ts('Send any event or contribution confirmations triggered by this payment'),
429 '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'),
430 'type' => CRM_Utils_Type
::T_BOOLEAN
,