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'],
97 'return' => ['entity', 'amount', 'entity_id', 'financial_trxn_id.check_number'],
99 $entity = civicrm_api3('EntityFinancialTrxn', 'getsingle', $eftParams);
102 'total_amount' => -$entity['amount'],
103 'contribution_id' => $entity['entity_id'],
104 'trxn_date' => $params['trxn_date'] ??
'now',
105 'cancelled_payment_id' => $params['id'],
106 'check_number' => $entity['financial_trxn_id.check_number'] ??
NULL,
109 foreach (['trxn_id', 'payment_instrument_id'] as $permittedParam) {
110 if (isset($params[$permittedParam])) {
111 $paymentParams[$permittedParam] = $params[$permittedParam];
114 $result = civicrm_api3('Payment', 'create', $paymentParams);
115 return civicrm_api3_create_success($result['values'], $params, 'Payment', 'cancel');
119 * Add a payment for a Contribution.
121 * @param array $params
127 * @throws \CRM_Core_Exception
128 * @throws \CiviCRM_API3_Exception
130 function civicrm_api3_payment_create($params) {
131 if (empty($params['skipCleanMoney'])) {
132 foreach (['total_amount', 'net_amount', 'fee_amount'] as $field) {
133 if (isset($params[$field])) {
134 $params[$field] = CRM_Utils_Rule
::cleanMoney($params[$field]);
138 // Check if it is an update
139 if (!empty($params['id'])) {
140 $amount = $params['total_amount'];
141 civicrm_api3('Payment', 'cancel', $params);
142 $params['total_amount'] = $amount;
144 $trxn = CRM_Financial_BAO_Payment
::create($params);
147 _civicrm_api3_object_to_array_unique_fields($trxn, $values[$trxn->id
]);
148 return civicrm_api3_create_success($values, $params, 'Payment', 'create', $trxn);
152 * Adjust Metadata for Create action.
154 * The metadata is used for setting defaults, documentation & validation.
156 * @param array $params
157 * Array of parameters.
159 function _civicrm_api3_payment_create_spec(&$params) {
161 'contribution_id' => [
163 'title' => ts('Contribution ID'),
164 'type' => CRM_Utils_Type
::T_INT
,
165 // We accept order_id as an alias so that we can chain like
166 // civicrm_api3('Order', 'create', ['blah' => 'blah', 'contribution_status_id' => 'Pending', 'api.Payment.create => ['total_amount' => 5]]
167 'api.aliases' => ['order_id'],
171 'title' => ts('Total Payment Amount'),
172 'type' => CRM_Utils_Type
::T_FLOAT
,
175 'title' => ts('Fee Amount'),
176 'type' => CRM_Utils_Type
::T_FLOAT
,
178 'payment_processor_id' => [
179 'name' => 'payment_processor_id',
180 'type' => CRM_Utils_Type
::T_INT
,
181 'title' => ts('Payment Processor'),
182 'description' => ts('Payment Processor for this payment'),
183 'where' => 'civicrm_financial_trxn.payment_processor_id',
184 'table_name' => 'civicrm_financial_trxn',
185 'entity' => 'FinancialTrxn',
186 'bao' => 'CRM_Financial_DAO_FinancialTrxn',
188 'FKClassName' => 'CRM_Financial_DAO_PaymentProcessor',
191 'title' => ts('Payment ID'),
192 'type' => CRM_Utils_Type
::T_INT
,
193 'api.aliases' => ['payment_id'],
196 'title' => ts('Payment Date'),
197 'type' => CRM_Utils_Type
::T_DATE + CRM_Utils_Type
::T_TIME
,
198 'api.default' => 'now',
199 'api.required' => TRUE,
201 'is_send_contribution_notification' => [
202 'title' => ts('Send out notifications based on contribution status change?'),
203 'description' => ts('Most commonly this equates to emails relating to the contribution, event, etcwhen a payment completes a contribution'),
204 'type' => CRM_Utils_Type
::T_BOOLEAN
,
205 'api.default' => TRUE,
207 'payment_instrument_id' => [
208 'name' => 'payment_instrument_id',
209 'type' => CRM_Utils_Type
::T_INT
,
210 'title' => ts('Payment Method'),
211 'description' => ts('FK to payment_instrument option group values'),
212 'where' => 'civicrm_financial_trxn.payment_instrument_id',
213 'table_name' => 'civicrm_financial_trxn',
214 'entity' => 'FinancialTrxn',
215 'bao' => 'CRM_Financial_DAO_FinancialTrxn',
220 'pseudoconstant' => [
221 'optionGroupName' => 'payment_instrument',
222 'optionEditPath' => 'civicrm/admin/options/payment_instrument',
226 'name' => 'card_type_id',
227 'type' => CRM_Utils_Type
::T_INT
,
228 'title' => ts('Card Type ID'),
229 'description' => ts('FK to accept_creditcard option group values'),
230 'where' => 'civicrm_financial_trxn.card_type_id',
231 'table_name' => 'civicrm_financial_trxn',
232 'entity' => 'FinancialTrxn',
233 'bao' => 'CRM_Financial_DAO_FinancialTrxn',
238 'pseudoconstant' => [
239 'optionGroupName' => 'accept_creditcard',
240 'optionEditPath' => 'civicrm/admin/options/accept_creditcard',
243 'trxn_result_code' => [
244 'name' => 'trxn_result_code',
245 'type' => CRM_Utils_Type
::T_STRING
,
246 'title' => ts('Transaction Result Code'),
247 'description' => ts('processor result code'),
249 'size' => CRM_Utils_Type
::HUGE
,
250 'where' => 'civicrm_financial_trxn.trxn_result_code',
251 'table_name' => 'civicrm_financial_trxn',
252 'entity' => 'FinancialTrxn',
253 'bao' => 'CRM_Financial_DAO_FinancialTrxn',
258 'type' => CRM_Utils_Type
::T_STRING
,
259 'title' => ts('Transaction ID'),
260 'description' => ts('Transaction id supplied by external processor. This may not be unique.'),
263 'where' => 'civicrm_financial_trxn.trxn_id',
264 'table_name' => 'civicrm_financial_trxn',
265 'entity' => 'FinancialTrxn',
266 'bao' => 'CRM_Financial_DAO_FinancialTrxn',
272 'order_reference' => [
273 'name' => 'order_reference',
274 'type' => CRM_Utils_Type
::T_STRING
,
275 'title' => 'Order Reference',
276 'description' => 'Payment Processor external order reference',
279 'where' => 'civicrm_financial_trxn.order_reference',
280 'table_name' => 'civicrm_financial_trxn',
281 'entity' => 'FinancialTrxn',
282 'bao' => 'CRM_Financial_DAO_FinancialTrxn',
289 'name' => 'check_number',
290 'type' => CRM_Utils_Type
::T_STRING
,
291 'title' => ts('Check Number'),
292 'description' => ts('Check number'),
295 'where' => 'civicrm_financial_trxn.check_number',
296 'table_name' => 'civicrm_financial_trxn',
297 'entity' => 'FinancialTrxn',
298 'bao' => 'CRM_Financial_DAO_FinancialTrxn',
304 'pan_truncation' => [
305 'name' => 'pan_truncation',
306 'type' => CRM_Utils_Type
::T_STRING
,
307 'title' => ts('PAN Truncation'),
308 'description' => ts('Last 4 digits of credit card'),
311 'where' => 'civicrm_financial_trxn.pan_truncation',
312 'table_name' => 'civicrm_financial_trxn',
313 'entity' => 'FinancialTrxn',
314 'bao' => 'CRM_Financial_DAO_FinancialTrxn',
324 * Adjust Metadata for Get action.
326 * The metadata is used for setting defaults, documentation & validation.
328 * @param array $params
329 * Array of parameters determined by getfields.
331 function _civicrm_api3_payment_get_spec(&$params) {
333 'contribution_id' => [
334 'title' => ts('Contribution ID'),
335 'type' => CRM_Utils_Type
::T_INT
,
338 'title' => ts('Entity ID'),
339 'type' => CRM_Utils_Type
::T_INT
,
340 'api.aliases' => ['contribution_id'],
343 'title' => ts('Transaction ID'),
344 'description' => ts('Transaction id supplied by external processor. This may not be unique.'),
345 'type' => CRM_Utils_Type
::T_STRING
,
347 'order_reference' => [
348 'title' => ts('Order Reference'),
349 'description' => ts('Payment Processor external order reference'),
350 'type' => CRM_Utils_Type
::T_STRING
,
353 'title' => ts('Payment Date'),
354 'type' => CRM_Utils_Type
::T_TIMESTAMP
,
356 'financial_trxn_id' => [
357 'title' => ts('Payment ID'),
358 'description' => ts('The ID of the record in civicrm_financial_trxn'),
359 'type' => CRM_Utils_Type
::T_INT
,
360 'api.aliases' => ['payment_id', 'id'],
366 * Adjust Metadata for Delete action.
368 * The metadata is used for setting defaults, documentation & validation.
370 * @param array $params
371 * Array of parameters.
373 function _civicrm_api3_payment_delete_spec(&$params) {
377 'title' => 'Payment ID',
378 'type' => CRM_Utils_Type
::T_INT
,
379 'api.aliases' => ['payment_id'],
385 * Adjust Metadata for Cancel action.
387 * The metadata is used for setting defaults, documentation & validation.
389 * @param array $params
390 * Array of parameters.
392 function _civicrm_api3_payment_cancel_spec(&$params) {
396 'title' => 'Payment ID',
397 'type' => CRM_Utils_Type
::T_INT
,
398 'api.aliases' => ['payment_id'],
401 'title' => 'Cancel Date',
402 'type' => CRM_Utils_Type
::T_DATE + CRM_Utils_Type
::T_TIME
,
408 * Send a payment confirmation.
410 * @param array $params
416 function civicrm_api3_payment_sendconfirmation($params) {
422 $input = array_intersect_key($params, array_flip($allowedParams));
423 // use either the contribution or membership receipt, based on whether it’s a membership-related contrib or not
424 $result = CRM_Financial_BAO_Payment
::sendConfirmation($input);
425 return civicrm_api3_create_success([
427 'is_sent' => $result[0],
428 'subject' => $result[1],
429 'message_txt' => $result[2],
430 'message_html' => $result[3],
436 * Adjust Metadata for sendconfirmation action.
438 * The metadata is used for setting defaults, documentation & validation.
440 * @param array $params
441 * Array of parameters determined by getfields.
443 function _civicrm_api3_payment_sendconfirmation_spec(&$params) {
446 'title' => ts('Payment ID'),
447 'type' => CRM_Utils_Type
::T_INT
,
449 $params['from_email_address'] = [
450 'title' => ts('From email; an email string or the id of a valid email'),
451 'type' => CRM_Utils_Type
::T_STRING
,
453 $params['is_send_contribution_notification'] = [
454 'title' => ts('Send any event or contribution confirmations triggered by this payment'),
455 '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'),
456 'type' => CRM_Utils_Type
::T_BOOLEAN
,