api/v3/Payment.php

   1 <?php
   2 /*
   3  +--------------------------------------------------------------------+
   4  | CiviCRM version 5                                                  |
   5  +--------------------------------------------------------------------+
   6  | Copyright CiviCRM LLC (c) 2004-2019                                |
   7  +--------------------------------------------------------------------+
   8  | This file is a part of CiviCRM.                                    |
   9  |                                                                    |
  10  | CiviCRM is free software; you can copy, modify, and distribute it  |
  11  | under the terms of the GNU Affero General Public License           |
  12  | Version 3, 19 November 2007 and the CiviCRM Licensing Exception.   |
  13  |                                                                    |
  14  | CiviCRM is distributed in the hope that it will be useful, but     |
  15  | WITHOUT ANY WARRANTY; without even the implied warranty of         |
  16  | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.               |
  17  | See the GNU Affero General Public License for more details.        |
  18  |                                                                    |
  19  | You should have received a copy of the GNU Affero General Public   |
  20  | License and the CiviCRM Licensing Exception along                  |
  21  | with this program; if not, contact CiviCRM LLC                     |
  22  | at info[AT]civicrm[DOT]org. If you have questions about the        |
  23  | GNU Affero General Public License or the licensing of CiviCRM,     |
  24  | see the CiviCRM license FAQ at http://civicrm.org/licensing        |
  25  +--------------------------------------------------------------------+
  26  */
  27
  28 /**
  29  * This api exposes CiviCRM Contribution Payment records.
  30  *
  31  * @package CiviCRM_APIv3
  32  */
  33
  34 /**
  35  * Retrieve a set of financial transactions which are payments.
  36  *
  37  * @param array $params
  38  *  Input parameters.
  39  *
  40  * @return array
  41  *   Array of financial transactions which are payments, if error an array with an error id and error message
  42  */
  43 function civicrm_api3_payment_get($params) {
  44   $financialTrxn = [];
  45   $limit = '';
  46   if (isset($params['options']) && !empty($params['options']['limit'])) {
  47     $limit = CRM_Utils_Array::value('limit', $params['options']);
  48   }
  49   $params['options']['limit'] = 0;
  50   if (isset($params['trxn_id'])) {
  51     $params['financial_trxn_id.trxn_id'] = $params['trxn_id'];
  52   }
  53   $eft = civicrm_api3('EntityFinancialTrxn', 'get', $params);
  54   if (!empty($eft['values'])) {
  55     $eftIds = [];
  56     foreach ($eft['values'] as $efts) {
  57       if (empty($efts['financial_trxn_id'])) {
  58         continue;
  59       }
  60       $eftIds[] = $efts['financial_trxn_id'];
  61       $map[$efts['financial_trxn_id']] = $efts['entity_id'];
  62     }
  63     if (!empty($eftIds)) {
  64       $ftParams = [
  65         'id' => ['IN' => $eftIds],
  66         'is_payment' => 1,
  67       ];
  68       if ($limit) {
  69         $ftParams['options']['limit'] = $limit;
  70       }
  71       $financialTrxn = civicrm_api3('FinancialTrxn', 'get', $ftParams);
  72       foreach ($financialTrxn['values'] as &$values) {
  73         $values['contribution_id'] = $map[$values['id']];
  74       }
  75     }
  76   }
  77   return civicrm_api3_create_success(CRM_Utils_Array::value('values', $financialTrxn, []), $params, 'Payment', 'get');
  78 }
  79
  80 /**
  81  * Delete a payment.
  82  *
  83  * @param array $params
  84  *   Input parameters.
  85  *
  86  * @throws API_Exception
  87  * @return array
  88  *   Api result array
  89  */
  90 function civicrm_api3_payment_delete($params) {
  91   return civicrm_api3('FinancialTrxn', 'delete', $params);
  92 }
  93
  94 /**
  95  * Cancel/Refund a payment for a Contribution.
  96  *
  97  * @param array $params
  98  *   Input parameters.
  99  *
 100  * @throws API_Exception
 101  * @return array
 102  *   Api result array
 103  */
 104 function civicrm_api3_payment_cancel($params) {
 105   $eftParams = [
 106     'entity_table' => 'civicrm_contribution',
 107     'financial_trxn_id' => $params['id'],
 108   ];
 109   $entity = civicrm_api3('EntityFinancialTrxn', 'getsingle', $eftParams);
 110
 111   $paymentParams = [
 112     'total_amount' => -$entity['amount'],
 113     'contribution_id' => $entity['entity_id'],
 114     'trxn_date' => CRM_Utils_Array::value('trxn_date', $params, 'now'),
 115   ];
 116
 117   foreach (['trxn_id', 'payment_instrument_id'] as $permittedParam) {
 118     if (isset($params[$permittedParam])) {
 119       $paymentParams[$permittedParam] = $params[$permittedParam];
 120     }
 121   }
 122   $result = civicrm_api3('Payment', 'create', $paymentParams);
 123   return civicrm_api3_create_success($result['values'], $params, 'Payment', 'cancel');
 124 }
 125
 126 /**
 127  * Add a payment for a Contribution.
 128  *
 129  * @param array $params
 130  *   Input parameters.
 131  *
 132  * @throws API_Exception
 133  * @return array
 134  *   Api result array
 135  */
 136 function civicrm_api3_payment_create($params) {
 137   // Check if it is an update
 138   if (!empty($params['id'])) {
 139     $amount = $params['total_amount'];
 140     civicrm_api3('Payment', 'cancel', $params);
 141     $params['total_amount'] = $amount;
 142   }
 143   $trxn = CRM_Financial_BAO_Payment::create($params);
 144
 145   $values = [];
 146   _civicrm_api3_object_to_array_unique_fields($trxn, $values[$trxn->id]);
 147   return civicrm_api3_create_success($values, $params, 'Payment', 'create', $trxn);
 148 }
 149
 150 /**
 151  * Adjust Metadata for Create action.
 152  *
 153  * The metadata is used for setting defaults, documentation & validation.
 154  *
 155  * @param array $params
 156  *   Array of parameters.
 157  */
 158 function _civicrm_api3_payment_create_spec(&$params) {
 159   $params = [
 160     'contribution_id' => [
 161       'api.required' => 1,
 162       'title' => ts('Contribution ID'),
 163       'type' => CRM_Utils_Type::T_INT,
 164     ],
 165     'total_amount' => [
 166       'api.required' => 1,
 167       'title' => ts('Total Payment Amount'),
 168       'type' => CRM_Utils_Type::T_FLOAT,
 169     ],
 170     'payment_processor_id' => [
 171       'title' => ts('Payment Processor ID'),
 172       'type' => CRM_Utils_Type::T_INT,
 173       'description' => ts('Payment processor ID - required for payment processor payments'),
 174     ],
 175     'id' => [
 176       'title' => ts('Payment ID'),
 177       'type' => CRM_Utils_Type::T_INT,
 178       'api.aliases' => ['payment_id'],
 179     ],
 180     'trxn_date' => [
 181       'title' => ts('Cancel Date'),
 182       'type' => CRM_Utils_Type::T_DATE + CRM_Utils_Type::T_TIME,
 183     ],
 184     'is_send_contribution_notification' => [
 185       'title' => ts('Send out notifications based on contribution status change?'),
 186       'description' => ts('Most commonly this equates to emails relating to the contribution, event, etcwhen a payment completes a contribution'),
 187       'type' => CRM_Utils_Type::T_BOOLEAN,
 188       'api.default' => TRUE,
 189     ],
 190   ];
 191 }
 192
 193 /**
 194  * Adjust Metadata for Get action.
 195  *
 196  * The metadata is used for setting defaults, documentation & validation.
 197  *
 198  * @param array $params
 199  *   Array of parameters determined by getfields.
 200  */
 201 function _civicrm_api3_payment_get_spec(&$params) {
 202   $params = [
 203     'contribution_id' => [
 204       'title' => 'Contribution ID',
 205       'type' => CRM_Utils_Type::T_INT,
 206     ],
 207     'entity_table' => [
 208       'title' => 'Entity Table',
 209       'api.default' => 'civicrm_contribution',
 210     ],
 211     'entity_id' => [
 212       'title' => 'Entity ID',
 213       'type' => CRM_Utils_Type::T_INT,
 214       'api.aliases' => ['contribution_id'],
 215     ],
 216     'trxn_id' => [
 217       'title' => 'Transaction ID',
 218       'type' => CRM_Utils_Type::T_STRING,
 219     ],
 220   ];
 221 }
 222
 223 /**
 224  * Adjust Metadata for Delete action.
 225  *
 226  * The metadata is used for setting defaults, documentation & validation.
 227  *
 228  * @param array $params
 229  *   Array of parameters.
 230  */
 231 function _civicrm_api3_payment_delete_spec(&$params) {
 232   $params = [
 233     'id' => [
 234       'api.required' => 1,
 235       'title' => 'Payment ID',
 236       'type' => CRM_Utils_Type::T_INT,
 237       'api.aliases' => ['payment_id'],
 238     ],
 239   ];
 240 }
 241
 242 /**
 243  * Adjust Metadata for Cancel action.
 244  *
 245  * The metadata is used for setting defaults, documentation & validation.
 246  *
 247  * @param array $params
 248  *   Array of parameters.
 249  */
 250 function _civicrm_api3_payment_cancel_spec(&$params) {
 251   $params = [
 252     'id' => [
 253       'api.required' => 1,
 254       'title' => 'Payment ID',
 255       'type' => CRM_Utils_Type::T_INT,
 256       'api.aliases' => ['payment_id'],
 257     ],
 258     'trxn_date' => [
 259       'title' => 'Cancel Date',
 260       'type' => CRM_Utils_Type::T_DATE + CRM_Utils_Type::T_TIME,
 261     ],
 262   ];
 263 }
 264
 265 /**
 266  * Send a payment confirmation.
 267  *
 268  * @param array $params
 269  *   Input parameters.
 270  *
 271  * @return array
 272  * @throws Exception
 273  */
 274 function civicrm_api3_payment_sendconfirmation($params) {
 275   $allowedParams = [
 276     'receipt_from_email',
 277     'receipt_from_name',
 278     'cc_receipt',
 279     'bcc_receipt',
 280     'receipt_text',
 281     'id',
 282   ];
 283   $input = array_intersect_key($params, array_flip($allowedParams));
 284   // use either the contribution or membership receipt, based on whether it’s a membership-related contrib or not
 285   $result = CRM_Financial_BAO_Payment::sendConfirmation($input);
 286   return civicrm_api3_create_success([
 287     $params['id'] => [
 288       'is_sent' => $result[0],
 289       'subject' => $result[1],
 290       'message_txt' => $result[2],
 291       'message_html' => $result[3],
 292     ],
 293   ]);
 294 }
 295
 296 /**
 297  * Adjust Metadata for sendconfirmation action.
 298  *
 299  * The metadata is used for setting defaults, documentation & validation.
 300  *
 301  * @param array $params
 302  *   Array of parameters determined by getfields.
 303  */
 304 function _civicrm_api3_payment_sendconfirmation_spec(&$params) {
 305   $params['id'] = [
 306     'api.required' => 1,
 307     'title' => ts('Payment ID'),
 308     'type' => CRM_Utils_Type::T_INT,
 309   ];
 310 }