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 * @throws \CiviCRM_API3_Exception
29 function civicrm_api3_payment_get($params) {
30 $params['is_payment'] = TRUE;
31 $contributionID = $params['entity_id'] ??
NULL;
33 // In order to support contribution id we need to do an extra lookup.
34 if ($contributionID) {
36 'entity_id' => $contributionID,
37 'entity_table' => 'civicrm_contribution',
38 'options' => ['limit' => 0],
39 'financial_trxn_id.is_payment' => 1,
41 $eft = civicrm_api3('EntityFinancialTrxn', 'get', $eftParams)['values'];
43 return civicrm_api3_create_success([], $params, 'Payment', 'get');
45 foreach ($eft as $entityFinancialTrxn) {
46 $params['financial_trxn_id']['IN'][] = $entityFinancialTrxn['financial_trxn_id'];
50 $financialTrxn = civicrm_api3('FinancialTrxn', 'get', array_merge($params, ['sequential' => FALSE]))['values'];
51 if ($contributionID) {
52 foreach ($financialTrxn as &$values) {
53 $values['contribution_id'] = $contributionID;
56 elseif (!empty($financialTrxn)) {
57 $entityFinancialTrxns = civicrm_api3('EntityFinancialTrxn', 'get', ['financial_trxn_id' => ['IN' => array_keys($financialTrxn)], 'entity_table' => 'civicrm_contribution', 'options' => ['limit' => 0]])['values'];
58 foreach ($entityFinancialTrxns as $entityFinancialTrxn) {
59 $financialTrxn[$entityFinancialTrxn['financial_trxn_id']]['contribution_id'] = $entityFinancialTrxn['entity_id'];
63 return civicrm_api3_create_success($financialTrxn, $params, 'Payment', 'get');
69 * @param array $params
75 * @throws \CiviCRM_API3_Exception
77 function civicrm_api3_payment_delete($params) {
78 return civicrm_api3('FinancialTrxn', 'delete', $params);
82 * Cancel/Refund a payment for a Contribution.
84 * @param array $params
90 * @throws \CiviCRM_API3_Exception
91 * @throws API_Exception
93 function civicrm_api3_payment_cancel($params) {
95 'entity_table' => 'civicrm_contribution',
96 'financial_trxn_id' => $params['id'],
98 $entity = civicrm_api3('EntityFinancialTrxn', 'getsingle', $eftParams);
101 'total_amount' => -$entity['amount'],
102 'contribution_id' => $entity['entity_id'],
103 'trxn_date' => $params['trxn_date'] ??
'now',
104 'cancelled_payment_id' => $params['id'],
107 foreach (['trxn_id', 'payment_instrument_id'] as $permittedParam) {
108 if (isset($params[$permittedParam])) {
109 $paymentParams[$permittedParam] = $params[$permittedParam];
112 $result = civicrm_api3('Payment', 'create', $paymentParams);
113 return civicrm_api3_create_success($result['values'], $params, 'Payment', 'cancel');
117 * Add a payment for a Contribution.
119 * @param array $params
125 * @throws \CRM_Core_Exception
126 * @throws \CiviCRM_API3_Exception
128 function civicrm_api3_payment_create($params) {
129 if (empty($params['skipCleanMoney'])) {
130 foreach (['total_amount', 'net_amount', 'fee_amount'] as $field) {
131 if (isset($params[$field])) {
132 $params[$field] = CRM_Utils_Rule
::cleanMoney($params[$field]);
136 if (!empty($params['payment_processor'])) {
137 // I can't find evidence this is passed in - I was gonna just remove it but decided to deprecate as I see getToFinancialAccount
138 // also anticipates it.
139 CRM_Core_Error
::deprecatedFunctionWarning('passing payment_processor is deprecated - use payment_processor_id');
140 $params['payment_processor_id'] = $params['payment_processor'];
142 // Check if it is an update
143 if (!empty($params['id'])) {
144 $amount = $params['total_amount'];
145 civicrm_api3('Payment', 'cancel', $params);
146 $params['total_amount'] = $amount;
148 $trxn = CRM_Financial_BAO_Payment
::create($params);
151 _civicrm_api3_object_to_array_unique_fields($trxn, $values[$trxn->id
]);
152 return civicrm_api3_create_success($values, $params, 'Payment', 'create', $trxn);
156 * Adjust Metadata for Create action.
158 * The metadata is used for setting defaults, documentation & validation.
160 * @param array $params
161 * Array of parameters.
163 function _civicrm_api3_payment_create_spec(&$params) {
165 'contribution_id' => [
167 'title' => ts('Contribution ID'),
168 'type' => CRM_Utils_Type
::T_INT
,
169 // We accept order_id as an alias so that we can chain like
170 // civicrm_api3('Order', 'create', ['blah' => 'blah', 'contribution_status_id' => 'Pending', 'api.Payment.create => ['total_amount' => 5]]
171 'api.aliases' => ['order_id'],
175 'title' => ts('Total Payment Amount'),
176 'type' => CRM_Utils_Type
::T_FLOAT
,
179 'title' => ts('Fee Amount'),
180 'type' => CRM_Utils_Type
::T_FLOAT
,
182 'payment_processor_id' => [
183 'name' => 'payment_processor_id',
184 'type' => CRM_Utils_Type
::T_INT
,
185 'title' => ts('Payment Processor'),
186 'description' => ts('Payment Processor for this payment'),
187 'where' => 'civicrm_financial_trxn.payment_processor_id',
188 'table_name' => 'civicrm_financial_trxn',
189 'entity' => 'FinancialTrxn',
190 'bao' => 'CRM_Financial_DAO_FinancialTrxn',
192 'FKClassName' => 'CRM_Financial_DAO_PaymentProcessor',
195 'title' => ts('Payment ID'),
196 'type' => CRM_Utils_Type
::T_INT
,
197 'api.aliases' => ['payment_id'],
200 'title' => ts('Payment Date'),
201 'type' => CRM_Utils_Type
::T_DATE + CRM_Utils_Type
::T_TIME
,
202 'api.default' => 'now',
203 'api.required' => TRUE,
205 'is_send_contribution_notification' => [
206 'title' => ts('Send out notifications based on contribution status change?'),
207 'description' => ts('Most commonly this equates to emails relating to the contribution, event, etcwhen a payment completes a contribution'),
208 'type' => CRM_Utils_Type
::T_BOOLEAN
,
209 'api.default' => TRUE,
211 'payment_instrument_id' => [
212 'name' => 'payment_instrument_id',
213 'type' => CRM_Utils_Type
::T_INT
,
214 'title' => ts('Payment Method'),
215 'description' => ts('FK to payment_instrument option group values'),
216 'where' => 'civicrm_financial_trxn.payment_instrument_id',
217 'table_name' => 'civicrm_financial_trxn',
218 'entity' => 'FinancialTrxn',
219 'bao' => 'CRM_Financial_DAO_FinancialTrxn',
224 'pseudoconstant' => [
225 'optionGroupName' => 'payment_instrument',
226 'optionEditPath' => 'civicrm/admin/options/payment_instrument',
230 'name' => 'card_type_id',
231 'type' => CRM_Utils_Type
::T_INT
,
232 'title' => ts('Card Type ID'),
233 'description' => ts('FK to accept_creditcard option group values'),
234 'where' => 'civicrm_financial_trxn.card_type_id',
235 'table_name' => 'civicrm_financial_trxn',
236 'entity' => 'FinancialTrxn',
237 'bao' => 'CRM_Financial_DAO_FinancialTrxn',
242 'pseudoconstant' => [
243 'optionGroupName' => 'accept_creditcard',
244 'optionEditPath' => 'civicrm/admin/options/accept_creditcard',
247 'trxn_result_code' => [
248 'name' => 'trxn_result_code',
249 'type' => CRM_Utils_Type
::T_STRING
,
250 'title' => ts('Transaction Result Code'),
251 'description' => ts('processor result code'),
253 'size' => CRM_Utils_Type
::HUGE
,
254 'where' => 'civicrm_financial_trxn.trxn_result_code',
255 'table_name' => 'civicrm_financial_trxn',
256 'entity' => 'FinancialTrxn',
257 'bao' => 'CRM_Financial_DAO_FinancialTrxn',
262 'type' => CRM_Utils_Type
::T_STRING
,
263 'title' => ts('Transaction ID'),
264 'description' => ts('Transaction id supplied by external processor. This may not be unique.'),
267 'where' => 'civicrm_financial_trxn.trxn_id',
268 'table_name' => 'civicrm_financial_trxn',
269 'entity' => 'FinancialTrxn',
270 'bao' => 'CRM_Financial_DAO_FinancialTrxn',
276 'order_reference' => [
277 'name' => 'order_reference',
278 'type' => CRM_Utils_Type
::T_STRING
,
279 'title' => 'Order Reference',
280 'description' => 'Payment Processor external order reference',
283 'where' => 'civicrm_financial_trxn.order_reference',
284 'table_name' => 'civicrm_financial_trxn',
285 'entity' => 'FinancialTrxn',
286 'bao' => 'CRM_Financial_DAO_FinancialTrxn',
293 'name' => 'check_number',
294 'type' => CRM_Utils_Type
::T_STRING
,
295 'title' => ts('Check Number'),
296 'description' => ts('Check number'),
299 'where' => 'civicrm_financial_trxn.check_number',
300 'table_name' => 'civicrm_financial_trxn',
301 'entity' => 'FinancialTrxn',
302 'bao' => 'CRM_Financial_DAO_FinancialTrxn',
308 'pan_truncation' => [
309 'name' => 'pan_truncation',
310 'type' => CRM_Utils_Type
::T_STRING
,
311 'title' => ts('PAN Truncation'),
312 'description' => ts('Last 4 digits of credit card'),
315 'where' => 'civicrm_financial_trxn.pan_truncation',
316 'table_name' => 'civicrm_financial_trxn',
317 'entity' => 'FinancialTrxn',
318 'bao' => 'CRM_Financial_DAO_FinancialTrxn',
328 * Adjust Metadata for Get action.
330 * The metadata is used for setting defaults, documentation & validation.
332 * @param array $params
333 * Array of parameters determined by getfields.
335 function _civicrm_api3_payment_get_spec(&$params) {
337 'contribution_id' => [
338 'title' => ts('Contribution ID'),
339 'type' => CRM_Utils_Type
::T_INT
,
342 'title' => ts('Entity ID'),
343 'type' => CRM_Utils_Type
::T_INT
,
344 'api.aliases' => ['contribution_id'],
347 'title' => ts('Transaction ID'),
348 'description' => ts('Transaction id supplied by external processor. This may not be unique.'),
349 'type' => CRM_Utils_Type
::T_STRING
,
352 'title' => ts('Payment Date'),
353 'type' => CRM_Utils_Type
::T_TIMESTAMP
,
355 'financial_trxn_id' => [
356 'title' => ts('Payment ID'),
357 'description' => ts('The ID of the record in civicrm_financial_trxn'),
358 'type' => CRM_Utils_Type
::T_INT
,
359 'api.aliases' => ['payment_id', 'id'],
365 * Adjust Metadata for Delete action.
367 * The metadata is used for setting defaults, documentation & validation.
369 * @param array $params
370 * Array of parameters.
372 function _civicrm_api3_payment_delete_spec(&$params) {
376 'title' => 'Payment ID',
377 'type' => CRM_Utils_Type
::T_INT
,
378 'api.aliases' => ['payment_id'],
384 * Adjust Metadata for Cancel action.
386 * The metadata is used for setting defaults, documentation & validation.
388 * @param array $params
389 * Array of parameters.
391 function _civicrm_api3_payment_cancel_spec(&$params) {
395 'title' => 'Payment ID',
396 'type' => CRM_Utils_Type
::T_INT
,
397 'api.aliases' => ['payment_id'],
400 'title' => 'Cancel Date',
401 'type' => CRM_Utils_Type
::T_DATE + CRM_Utils_Type
::T_TIME
,
407 * Send a payment confirmation.
409 * @param array $params
415 function civicrm_api3_payment_sendconfirmation($params) {
421 $input = array_intersect_key($params, array_flip($allowedParams));
422 // use either the contribution or membership receipt, based on whether it’s a membership-related contrib or not
423 $result = CRM_Financial_BAO_Payment
::sendConfirmation($input);
424 return civicrm_api3_create_success([
426 'is_sent' => $result[0],
427 'subject' => $result[1],
428 'message_txt' => $result[2],
429 'message_html' => $result[3],
435 * Adjust Metadata for sendconfirmation action.
437 * The metadata is used for setting defaults, documentation & validation.
439 * @param array $params
440 * Array of parameters determined by getfields.
442 function _civicrm_api3_payment_sendconfirmation_spec(&$params) {
445 'title' => ts('Payment ID'),
446 'type' => CRM_Utils_Type
::T_INT
,
448 $params['from_email_address'] = [
449 'title' => ts('From email; an email string or the id of a valid email'),
450 'type' => CRM_Utils_Type
::T_STRING
,
452 $params['is_send_contribution_notification'] = [
453 'title' => ts('Send any event or contribution confirmations triggered by this payment'),
454 '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'),
455 'type' => CRM_Utils_Type
::T_BOOLEAN
,