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',
277 'name' => 'check_number',
278 'type' => CRM_Utils_Type
::T_STRING
,
279 'title' => ts('Check Number'),
280 'description' => ts('Check number'),
283 'where' => 'civicrm_financial_trxn.check_number',
284 'table_name' => 'civicrm_financial_trxn',
285 'entity' => 'FinancialTrxn',
286 'bao' => 'CRM_Financial_DAO_FinancialTrxn',
292 'pan_truncation' => [
293 'name' => 'pan_truncation',
294 'type' => CRM_Utils_Type
::T_STRING
,
295 'title' => ts('PAN Truncation'),
296 'description' => ts('Last 4 digits of credit card'),
299 'where' => 'civicrm_financial_trxn.pan_truncation',
300 'table_name' => 'civicrm_financial_trxn',
301 'entity' => 'FinancialTrxn',
302 'bao' => 'CRM_Financial_DAO_FinancialTrxn',
312 * Adjust Metadata for Get action.
314 * The metadata is used for setting defaults, documentation & validation.
316 * @param array $params
317 * Array of parameters determined by getfields.
319 function _civicrm_api3_payment_get_spec(&$params) {
321 'contribution_id' => [
322 'title' => ts('Contribution ID'),
323 'type' => CRM_Utils_Type
::T_INT
,
326 'title' => ts('Entity ID'),
327 'type' => CRM_Utils_Type
::T_INT
,
328 'api.aliases' => ['contribution_id'],
331 'title' => ts('Transaction ID'),
332 'description' => ts('Transaction id supplied by external processor. This may not be unique.'),
333 'type' => CRM_Utils_Type
::T_STRING
,
336 'title' => ts('Payment Date'),
337 'type' => CRM_Utils_Type
::T_TIMESTAMP
,
339 'financial_trxn_id' => [
340 'title' => ts('Payment ID'),
341 'description' => ts('The ID of the record in civicrm_financial_trxn'),
342 'type' => CRM_Utils_Type
::T_INT
,
343 'api.aliases' => ['payment_id', 'id'],
349 * Adjust Metadata for Delete action.
351 * The metadata is used for setting defaults, documentation & validation.
353 * @param array $params
354 * Array of parameters.
356 function _civicrm_api3_payment_delete_spec(&$params) {
360 'title' => 'Payment ID',
361 'type' => CRM_Utils_Type
::T_INT
,
362 'api.aliases' => ['payment_id'],
368 * Adjust Metadata for Cancel action.
370 * The metadata is used for setting defaults, documentation & validation.
372 * @param array $params
373 * Array of parameters.
375 function _civicrm_api3_payment_cancel_spec(&$params) {
379 'title' => 'Payment ID',
380 'type' => CRM_Utils_Type
::T_INT
,
381 'api.aliases' => ['payment_id'],
384 'title' => 'Cancel Date',
385 'type' => CRM_Utils_Type
::T_DATE + CRM_Utils_Type
::T_TIME
,
391 * Send a payment confirmation.
393 * @param array $params
399 function civicrm_api3_payment_sendconfirmation($params) {
405 $input = array_intersect_key($params, array_flip($allowedParams));
406 // use either the contribution or membership receipt, based on whether it’s a membership-related contrib or not
407 $result = CRM_Financial_BAO_Payment
::sendConfirmation($input);
408 return civicrm_api3_create_success([
410 'is_sent' => $result[0],
411 'subject' => $result[1],
412 'message_txt' => $result[2],
413 'message_html' => $result[3],
419 * Adjust Metadata for sendconfirmation action.
421 * The metadata is used for setting defaults, documentation & validation.
423 * @param array $params
424 * Array of parameters determined by getfields.
426 function _civicrm_api3_payment_sendconfirmation_spec(&$params) {
429 'title' => ts('Payment ID'),
430 'type' => CRM_Utils_Type
::T_INT
,
432 $params['from_email_address'] = [
433 'title' => ts('From email; an email string or the id of a valid email'),
434 'type' => CRM_Utils_Type
::T_STRING
,
436 $params['is_send_contribution_notification'] = [
437 'title' => ts('Send any event or contribution confirmations triggered by this payment'),
438 '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'),
439 'type' => CRM_Utils_Type
::T_BOOLEAN
,