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) {
32 if (isset($params['options']) && !empty($params['options']['limit'])) {
33 $limit = CRM_Utils_Array
::value('limit', $params['options']);
35 $params['options']['limit'] = 0;
36 if (isset($params['trxn_id'])) {
37 $params['financial_trxn_id.trxn_id'] = $params['trxn_id'];
40 unset($eftParams['return']);
41 // @todo - why do we fetch EFT params at all?
42 $eft = civicrm_api3('EntityFinancialTrxn', 'get', $eftParams);
43 if (!empty($eft['values'])) {
45 foreach ($eft['values'] as $efts) {
46 if (empty($efts['financial_trxn_id'])) {
49 $eftIds[] = $efts['financial_trxn_id'];
50 $map[$efts['financial_trxn_id']] = $efts['entity_id'];
52 if (!empty($eftIds)) {
54 'id' => ['IN' => $eftIds],
58 $ftParams['options']['limit'] = $limit;
60 $financialTrxn = civicrm_api3('FinancialTrxn', 'get', $ftParams);
61 foreach ($financialTrxn['values'] as &$values) {
62 $values['contribution_id'] = $map[$values['id']];
66 return civicrm_api3_create_success(CRM_Utils_Array
::value('values', $financialTrxn, []), $params, 'Payment', 'get');
72 * @param array $params
78 * @throws \CiviCRM_API3_Exception
80 function civicrm_api3_payment_delete($params) {
81 return civicrm_api3('FinancialTrxn', 'delete', $params);
85 * Cancel/Refund a payment for a Contribution.
87 * @param array $params
93 * @throws \CiviCRM_API3_Exception
94 * @throws API_Exception
96 function civicrm_api3_payment_cancel($params) {
98 'entity_table' => 'civicrm_contribution',
99 'financial_trxn_id' => $params['id'],
101 $entity = civicrm_api3('EntityFinancialTrxn', 'getsingle', $eftParams);
104 'total_amount' => -$entity['amount'],
105 'contribution_id' => $entity['entity_id'],
106 'trxn_date' => CRM_Utils_Array
::value('trxn_date', $params, 'now'),
107 'cancelled_payment_id' => $params['id'],
110 foreach (['trxn_id', 'payment_instrument_id'] as $permittedParam) {
111 if (isset($params[$permittedParam])) {
112 $paymentParams[$permittedParam] = $params[$permittedParam];
115 $result = civicrm_api3('Payment', 'create', $paymentParams);
116 return civicrm_api3_create_success($result['values'], $params, 'Payment', 'cancel');
120 * Add a payment for a Contribution.
122 * @param array $params
128 * @throws \CRM_Core_Exception
129 * @throws \CiviCRM_API3_Exception
131 function civicrm_api3_payment_create($params) {
132 if (empty($params['skipCleanMoney'])) {
133 foreach (['total_amount', 'net_amount', 'fee_amount'] as $field) {
134 if (isset($params[$field])) {
135 $params[$field] = CRM_Utils_Rule
::cleanMoney($params[$field]);
139 if (!empty($params['payment_processor'])) {
140 // I can't find evidence this is passed in - I was gonna just remove it but decided to deprecate as I see getToFinancialAccount
141 // also anticipates it.
142 CRM_Core_Error
::deprecatedFunctionWarning('passing payment_processor is deprecated - use payment_processor_id');
143 $params['payment_processor_id'] = $params['payment_processor'];
145 // Check if it is an update
146 if (!empty($params['id'])) {
147 $amount = $params['total_amount'];
148 civicrm_api3('Payment', 'cancel', $params);
149 $params['total_amount'] = $amount;
151 $trxn = CRM_Financial_BAO_Payment
::create($params);
154 _civicrm_api3_object_to_array_unique_fields($trxn, $values[$trxn->id
]);
155 return civicrm_api3_create_success($values, $params, 'Payment', 'create', $trxn);
159 * Adjust Metadata for Create action.
161 * The metadata is used for setting defaults, documentation & validation.
163 * @param array $params
164 * Array of parameters.
166 function _civicrm_api3_payment_create_spec(&$params) {
168 'contribution_id' => [
170 'title' => ts('Contribution ID'),
171 'type' => CRM_Utils_Type
::T_INT
,
172 // We accept order_id as an alias so that we can chain like
173 // civicrm_api3('Order', 'create', ['blah' => 'blah', 'contribution_status_id' => 'Pending', 'api.Payment.create => ['total_amount' => 5]]
174 'api.aliases' => ['order_id'],
178 'title' => ts('Total Payment Amount'),
179 'type' => CRM_Utils_Type
::T_FLOAT
,
182 'title' => ts('Fee Amount'),
183 'type' => CRM_Utils_Type
::T_FLOAT
,
185 'payment_processor_id' => [
186 'name' => 'payment_processor_id',
187 'type' => CRM_Utils_Type
::T_INT
,
188 'title' => ts('Payment Processor'),
189 'description' => ts('Payment Processor for this payment'),
190 'where' => 'civicrm_financial_trxn.payment_processor_id',
191 'table_name' => 'civicrm_financial_trxn',
192 'entity' => 'FinancialTrxn',
193 'bao' => 'CRM_Financial_DAO_FinancialTrxn',
195 'FKClassName' => 'CRM_Financial_DAO_PaymentProcessor',
198 'title' => ts('Payment ID'),
199 'type' => CRM_Utils_Type
::T_INT
,
200 'api.aliases' => ['payment_id'],
203 'title' => ts('Payment Date'),
204 'type' => CRM_Utils_Type
::T_DATE + CRM_Utils_Type
::T_TIME
,
205 'api.default' => 'now',
206 'api.required' => TRUE,
208 'is_send_contribution_notification' => [
209 'title' => ts('Send out notifications based on contribution status change?'),
210 'description' => ts('Most commonly this equates to emails relating to the contribution, event, etcwhen a payment completes a contribution'),
211 'type' => CRM_Utils_Type
::T_BOOLEAN
,
212 'api.default' => TRUE,
214 'payment_instrument_id' => [
215 'name' => 'payment_instrument_id',
216 'type' => CRM_Utils_Type
::T_INT
,
217 'title' => ts('Payment Method'),
218 'description' => ts('FK to payment_instrument option group values'),
219 'where' => 'civicrm_financial_trxn.payment_instrument_id',
220 'table_name' => 'civicrm_financial_trxn',
221 'entity' => 'FinancialTrxn',
222 'bao' => 'CRM_Financial_DAO_FinancialTrxn',
227 'pseudoconstant' => [
228 'optionGroupName' => 'payment_instrument',
229 'optionEditPath' => 'civicrm/admin/options/payment_instrument',
233 'name' => 'card_type_id',
234 'type' => CRM_Utils_Type
::T_INT
,
235 'title' => ts('Card Type ID'),
236 'description' => ts('FK to accept_creditcard option group values'),
237 'where' => 'civicrm_financial_trxn.card_type_id',
238 'table_name' => 'civicrm_financial_trxn',
239 'entity' => 'FinancialTrxn',
240 'bao' => 'CRM_Financial_DAO_FinancialTrxn',
245 'pseudoconstant' => [
246 'optionGroupName' => 'accept_creditcard',
247 'optionEditPath' => 'civicrm/admin/options/accept_creditcard',
250 'trxn_result_code' => [
251 'name' => 'trxn_result_code',
252 'type' => CRM_Utils_Type
::T_STRING
,
253 'title' => ts('Transaction Result Code'),
254 'description' => ts('processor result code'),
256 'size' => CRM_Utils_Type
::HUGE
,
257 'where' => 'civicrm_financial_trxn.trxn_result_code',
258 'table_name' => 'civicrm_financial_trxn',
259 'entity' => 'FinancialTrxn',
260 'bao' => 'CRM_Financial_DAO_FinancialTrxn',
265 'type' => CRM_Utils_Type
::T_STRING
,
266 'title' => ts('Transaction ID'),
267 'description' => ts('Transaction id supplied by external processor. This may not be unique.'),
270 'where' => 'civicrm_financial_trxn.trxn_id',
271 'table_name' => 'civicrm_financial_trxn',
272 'entity' => 'FinancialTrxn',
273 'bao' => 'CRM_Financial_DAO_FinancialTrxn',
280 'name' => 'check_number',
281 'type' => CRM_Utils_Type
::T_STRING
,
282 'title' => ts('Check Number'),
283 'description' => ts('Check number'),
286 'where' => 'civicrm_financial_trxn.check_number',
287 'table_name' => 'civicrm_financial_trxn',
288 'entity' => 'FinancialTrxn',
289 'bao' => 'CRM_Financial_DAO_FinancialTrxn',
295 'pan_truncation' => [
296 'name' => 'pan_truncation',
297 'type' => CRM_Utils_Type
::T_STRING
,
298 'title' => ts('Pan Truncation'),
299 'description' => ts('Last 4 digits of credit card'),
302 'where' => 'civicrm_financial_trxn.pan_truncation',
303 'table_name' => 'civicrm_financial_trxn',
304 'entity' => 'FinancialTrxn',
305 'bao' => 'CRM_Financial_DAO_FinancialTrxn',
315 * Adjust Metadata for Get action.
317 * The metadata is used for setting defaults, documentation & validation.
319 * @param array $params
320 * Array of parameters determined by getfields.
322 function _civicrm_api3_payment_get_spec(&$params) {
324 'contribution_id' => [
325 'title' => ts('Contribution ID'),
326 'type' => CRM_Utils_Type
::T_INT
,
329 'title' => ts('Entity Table'),
330 'api.default' => 'civicrm_contribution',
333 'title' => ts('Entity ID'),
334 'type' => CRM_Utils_Type
::T_INT
,
335 'api.aliases' => ['contribution_id'],
338 'title' => ts('Transaction ID'),
339 'description' => ts('Transaction id supplied by external processor. This may not be unique.'),
340 'type' => CRM_Utils_Type
::T_STRING
,
343 'title' => ts('Payment Date'),
344 'type' => CRM_Utils_Type
::T_TIMESTAMP
,
346 'financial_trxn_id' => [
347 'title' => ts('Payment ID'),
348 'description' => ts('The ID of the record in civicrm_financial_trxn'),
349 'type' => CRM_Utils_Type
::T_INT
,
350 'api.aliases' => ['payment_id', 'id'],
356 * Adjust Metadata for Delete action.
358 * The metadata is used for setting defaults, documentation & validation.
360 * @param array $params
361 * Array of parameters.
363 function _civicrm_api3_payment_delete_spec(&$params) {
367 'title' => 'Payment ID',
368 'type' => CRM_Utils_Type
::T_INT
,
369 'api.aliases' => ['payment_id'],
375 * Adjust Metadata for Cancel action.
377 * The metadata is used for setting defaults, documentation & validation.
379 * @param array $params
380 * Array of parameters.
382 function _civicrm_api3_payment_cancel_spec(&$params) {
386 'title' => 'Payment ID',
387 'type' => CRM_Utils_Type
::T_INT
,
388 'api.aliases' => ['payment_id'],
391 'title' => 'Cancel Date',
392 'type' => CRM_Utils_Type
::T_DATE + CRM_Utils_Type
::T_TIME
,
398 * Send a payment confirmation.
400 * @param array $params
406 function civicrm_api3_payment_sendconfirmation($params) {
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([
417 'is_sent' => $result[0],
418 'subject' => $result[1],
419 'message_txt' => $result[2],
420 'message_html' => $result[3],
426 * Adjust Metadata for sendconfirmation action.
428 * The metadata is used for setting defaults, documentation & validation.
430 * @param array $params
431 * Array of parameters determined by getfields.
433 function _civicrm_api3_payment_sendconfirmation_spec(&$params) {
436 'title' => ts('Payment ID'),
437 'type' => CRM_Utils_Type
::T_INT
,
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
,
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
,