api/v3/Payment.php

   1 <?php
   2 /*
   3  +--------------------------------------------------------------------+
   4  | CiviCRM version 5                                                  |
   5  +--------------------------------------------------------------------+
   6  | Copyright CiviCRM LLC (c) 2004-2020                                |
   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  * @return array
 101  *   Api result array
 102  *
 103  * @throws \CiviCRM_API3_Exception
 104  * @throws API_Exception
 105  */
 106 function civicrm_api3_payment_cancel($params) {
 107   $eftParams = [
 108     'entity_table' => 'civicrm_contribution',
 109     'financial_trxn_id' => $params['id'],
 110   ];
 111   $entity = civicrm_api3('EntityFinancialTrxn', 'getsingle', $eftParams);
 112
 113   $paymentParams = [
 114     'total_amount' => -$entity['amount'],
 115     'contribution_id' => $entity['entity_id'],
 116     'trxn_date' => CRM_Utils_Array::value('trxn_date', $params, 'now'),
 117     'cancelled_payment_id' => $params['id'],
 118   ];
 119
 120   foreach (['trxn_id', 'payment_instrument_id'] as $permittedParam) {
 121     if (isset($params[$permittedParam])) {
 122       $paymentParams[$permittedParam] = $params[$permittedParam];
 123     }
 124   }
 125   $result = civicrm_api3('Payment', 'create', $paymentParams);
 126   return civicrm_api3_create_success($result['values'], $params, 'Payment', 'cancel');
 127 }
 128
 129 /**
 130  * Add a payment for a Contribution.
 131  *
 132  * @param array $params
 133  *   Input parameters.
 134  *
 135  * @return array
 136  *   Api result array
 137  *
 138  * @throws \API_Exception
 139  * @throws \CRM_Core_Exception
 140  * @throws \CiviCRM_API3_Exception
 141  */
 142 function civicrm_api3_payment_create($params) {
 143   if (empty($params['skipCleanMoney'])) {
 144     foreach (['total_amount', 'net_amount', 'fee_amount'] as $field) {
 145       if (isset($params[$field])) {
 146         $params[$field] = CRM_Utils_Rule::cleanMoney($params[$field]);
 147       }
 148     }
 149   }
 150   if (!empty($params['payment_processor'])) {
 151     // I can't find evidence this is passed in - I was gonna just remove it but decided to deprecate  as I see getToFinancialAccount
 152     // also anticipates it.
 153     CRM_Core_Error::deprecatedFunctionWarning('passing payment_processor is deprecated - use payment_processor_id');
 154     $params['payment_processor_id'] = $params['payment_processor'];
 155   }
 156   // Check if it is an update
 157   if (!empty($params['id'])) {
 158     $amount = $params['total_amount'];
 159     civicrm_api3('Payment', 'cancel', $params);
 160     $params['total_amount'] = $amount;
 161   }
 162   $trxn = CRM_Financial_BAO_Payment::create($params);
 163
 164   $values = [];
 165   _civicrm_api3_object_to_array_unique_fields($trxn, $values[$trxn->id]);
 166   return civicrm_api3_create_success($values, $params, 'Payment', 'create', $trxn);
 167 }
 168
 169 /**
 170  * Adjust Metadata for Create action.
 171  *
 172  * The metadata is used for setting defaults, documentation & validation.
 173  *
 174  * @param array $params
 175  *   Array of parameters.
 176  */
 177 function _civicrm_api3_payment_create_spec(&$params) {
 178   $params = [
 179     'contribution_id' => [
 180       'api.required' => 1,
 181       'title' => ts('Contribution ID'),
 182       'type' => CRM_Utils_Type::T_INT,
 183       // We accept order_id as an alias so that we can chain like
 184       // civicrm_api3('Order', 'create', ['blah' => 'blah', 'contribution_status_id' => 'Pending', 'api.Payment.create => ['total_amount' => 5]]
 185       'api.aliases' => ['order_id'],
 186     ],
 187     'total_amount' => [
 188       'api.required' => 1,
 189       'title' => ts('Total Payment Amount'),
 190       'type' => CRM_Utils_Type::T_FLOAT,
 191     ],
 192     'payment_processor_id' => [
 193       'name' => 'payment_processor_id',
 194       'type' => CRM_Utils_Type::T_INT,
 195       'title' => ts('Payment Processor'),
 196       'description' => ts('Payment Processor for this payment'),
 197       'where' => 'civicrm_financial_trxn.payment_processor_id',
 198       'table_name' => 'civicrm_financial_trxn',
 199       'entity' => 'FinancialTrxn',
 200       'bao' => 'CRM_Financial_DAO_FinancialTrxn',
 201       'localizable' => 0,
 202       'FKClassName' => 'CRM_Financial_DAO_PaymentProcessor',
 203     ],
 204     'id' => [
 205       'title' => ts('Payment ID'),
 206       'type' => CRM_Utils_Type::T_INT,
 207       'api.aliases' => ['payment_id'],
 208     ],
 209     'trxn_date' => [
 210       'title' => ts('Payment Date'),
 211       'type' => CRM_Utils_Type::T_DATE + CRM_Utils_Type::T_TIME,
 212       'api.default' => 'now',
 213       'api.required' => TRUE,
 214     ],
 215     'is_send_contribution_notification' => [
 216       'title' => ts('Send out notifications based on contribution status change?'),
 217       'description' => ts('Most commonly this equates to emails relating to the contribution, event, etcwhen a payment completes a contribution'),
 218       'type' => CRM_Utils_Type::T_BOOLEAN,
 219       'api.default' => TRUE,
 220     ],
 221     'payment_instrument_id' => [
 222       'name' => 'payment_instrument_id',
 223       'type' => CRM_Utils_Type::T_INT,
 224       'title' => ts('Payment Method'),
 225       'description' => ts('FK to payment_instrument option group values'),
 226       'where' => 'civicrm_financial_trxn.payment_instrument_id',
 227       'table_name' => 'civicrm_financial_trxn',
 228       'entity' => 'FinancialTrxn',
 229       'bao' => 'CRM_Financial_DAO_FinancialTrxn',
 230       'localizable' => 0,
 231       'html' => [
 232         'type' => 'Select',
 233       ],
 234       'pseudoconstant' => [
 235         'optionGroupName' => 'payment_instrument',
 236         'optionEditPath' => 'civicrm/admin/options/payment_instrument',
 237       ],
 238     ],
 239     'card_type_id' => [
 240       'name' => 'card_type_id',
 241       'type' => CRM_Utils_Type::T_INT,
 242       'title' => ts('Card Type ID'),
 243       'description' => ts('FK to accept_creditcard option group values'),
 244       'where' => 'civicrm_financial_trxn.card_type_id',
 245       'table_name' => 'civicrm_financial_trxn',
 246       'entity' => 'FinancialTrxn',
 247       'bao' => 'CRM_Financial_DAO_FinancialTrxn',
 248       'localizable' => 0,
 249       'html' => [
 250         'type' => 'Select',
 251       ],
 252       'pseudoconstant' => [
 253         'optionGroupName' => 'accept_creditcard',
 254         'optionEditPath' => 'civicrm/admin/options/accept_creditcard',
 255       ],
 256     ],
 257     'trxn_result_code' => [
 258       'name' => 'trxn_result_code',
 259       'type' => CRM_Utils_Type::T_STRING,
 260       'title' => ts('Transaction Result Code'),
 261       'description' => ts('processor result code'),
 262       'maxlength' => 255,
 263       'size' => CRM_Utils_Type::HUGE,
 264       'where' => 'civicrm_financial_trxn.trxn_result_code',
 265       'table_name' => 'civicrm_financial_trxn',
 266       'entity' => 'FinancialTrxn',
 267       'bao' => 'CRM_Financial_DAO_FinancialTrxn',
 268       'localizable' => 0,
 269     ],
 270     'trxn_id' => [
 271       'name' => 'trxn_id',
 272       'type' => CRM_Utils_Type::T_STRING,
 273       'title' => ts('Transaction ID'),
 274       'description' => ts('Transaction id supplied by external processor. This may not be unique.'),
 275       'maxlength' => 255,
 276       'size' => 10,
 277       'where' => 'civicrm_financial_trxn.trxn_id',
 278       'table_name' => 'civicrm_financial_trxn',
 279       'entity' => 'FinancialTrxn',
 280       'bao' => 'CRM_Financial_DAO_FinancialTrxn',
 281       'localizable' => 0,
 282       'html' => [
 283         'type' => 'Text',
 284       ],
 285     ],
 286     'check_number' => [
 287       'name' => 'check_number',
 288       'type' => CRM_Utils_Type::T_STRING,
 289       'title' => ts('Check Number'),
 290       'description' => ts('Check number'),
 291       'maxlength' => 255,
 292       'size' => 6,
 293       'where' => 'civicrm_financial_trxn.check_number',
 294       'table_name' => 'civicrm_financial_trxn',
 295       'entity' => 'FinancialTrxn',
 296       'bao' => 'CRM_Financial_DAO_FinancialTrxn',
 297       'localizable' => 0,
 298       'html' => [
 299         'type' => 'Text',
 300       ],
 301     ],
 302     'pan_truncation' => [
 303       'name' => 'pan_truncation',
 304       'type' => CRM_Utils_Type::T_STRING,
 305       'title' => ts('Pan Truncation'),
 306       'description' => ts('Last 4 digits of credit card'),
 307       'maxlength' => 4,
 308       'size' => 4,
 309       'where' => 'civicrm_financial_trxn.pan_truncation',
 310       'table_name' => 'civicrm_financial_trxn',
 311       'entity' => 'FinancialTrxn',
 312       'bao' => 'CRM_Financial_DAO_FinancialTrxn',
 313       'localizable' => 0,
 314       'html' => [
 315         'type' => 'Text',
 316       ],
 317     ],
 318   ];
 319 }
 320
 321 /**
 322  * Adjust Metadata for Get action.
 323  *
 324  * The metadata is used for setting defaults, documentation & validation.
 325  *
 326  * @param array $params
 327  *   Array of parameters determined by getfields.
 328  */
 329 function _civicrm_api3_payment_get_spec(&$params) {
 330   $params = [
 331     'contribution_id' => [
 332       'title' => ts('Contribution ID'),
 333       'type' => CRM_Utils_Type::T_INT,
 334     ],
 335     'entity_table' => [
 336       'title' => ts('Entity Table'),
 337       'api.default' => 'civicrm_contribution',
 338     ],
 339     'entity_id' => [
 340       'title' => ts('Entity ID'),
 341       'type' => CRM_Utils_Type::T_INT,
 342       'api.aliases' => ['contribution_id'],
 343     ],
 344     'trxn_id' => [
 345       'title' => ts('Transaction ID'),
 346       'type' => CRM_Utils_Type::T_STRING,
 347     ],
 348     'trxn_date' => [
 349       'title' => ts('Payment Date'),
 350       'type' => CRM_Utils_Type::T_TIMESTAMP,
 351     ],
 352   ];
 353 }
 354
 355 /**
 356  * Adjust Metadata for Delete action.
 357  *
 358  * The metadata is used for setting defaults, documentation & validation.
 359  *
 360  * @param array $params
 361  *   Array of parameters.
 362  */
 363 function _civicrm_api3_payment_delete_spec(&$params) {
 364   $params = [
 365     'id' => [
 366       'api.required' => 1,
 367       'title' => 'Payment ID',
 368       'type' => CRM_Utils_Type::T_INT,
 369       'api.aliases' => ['payment_id'],
 370     ],
 371   ];
 372 }
 373
 374 /**
 375  * Adjust Metadata for Cancel action.
 376  *
 377  * The metadata is used for setting defaults, documentation & validation.
 378  *
 379  * @param array $params
 380  *   Array of parameters.
 381  */
 382 function _civicrm_api3_payment_cancel_spec(&$params) {
 383   $params = [
 384     'id' => [
 385       'api.required' => 1,
 386       'title' => 'Payment ID',
 387       'type' => CRM_Utils_Type::T_INT,
 388       'api.aliases' => ['payment_id'],
 389     ],
 390     'trxn_date' => [
 391       'title' => 'Cancel Date',
 392       'type' => CRM_Utils_Type::T_DATE + CRM_Utils_Type::T_TIME,
 393     ],
 394   ];
 395 }
 396
 397 /**
 398  * Send a payment confirmation.
 399  *
 400  * @param array $params
 401  *   Input parameters.
 402  *
 403  * @return array
 404  * @throws Exception
 405  */
 406 function civicrm_api3_payment_sendconfirmation($params) {
 407   $allowedParams = [
 408     'from',
 409     'id',
 410     'check_permissions',
 411   ];
 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([
 416     $params['id'] => [
 417       'is_sent' => $result[0],
 418       'subject' => $result[1],
 419       'message_txt' => $result[2],
 420       'message_html' => $result[3],
 421     ],
 422   ]);
 423 }
 424
 425 /**
 426  * Adjust Metadata for sendconfirmation action.
 427  *
 428  * The metadata is used for setting defaults, documentation & validation.
 429  *
 430  * @param array $params
 431  *   Array of parameters determined by getfields.
 432  */
 433 function _civicrm_api3_payment_sendconfirmation_spec(&$params) {
 434   $params['id'] = [
 435     'api.required' => 1,
 436     'title' => ts('Payment ID'),
 437     'type' => CRM_Utils_Type::T_INT,
 438   ];
 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,
 442   ];
 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,
 447     'api.default' => 0,
 448   ];
 449 }