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  * @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   // Check if it is an update
 151   if (!empty($params['id'])) {
 152     $amount = $params['total_amount'];
 153     civicrm_api3('Payment', 'cancel', $params);
 154     $params['total_amount'] = $amount;
 155   }
 156   $trxn = CRM_Financial_BAO_Payment::create($params);
 157
 158   $values = [];
 159   _civicrm_api3_object_to_array_unique_fields($trxn, $values[$trxn->id]);
 160   return civicrm_api3_create_success($values, $params, 'Payment', 'create', $trxn);
 161 }
 162
 163 /**
 164  * Adjust Metadata for Create action.
 165  *
 166  * The metadata is used for setting defaults, documentation & validation.
 167  *
 168  * @param array $params
 169  *   Array of parameters.
 170  */
 171 function _civicrm_api3_payment_create_spec(&$params) {
 172   $params = [
 173     'contribution_id' => [
 174       'api.required' => 1,
 175       'title' => ts('Contribution ID'),
 176       'type' => CRM_Utils_Type::T_INT,
 177       // We accept order_id as an alias so that we can chain like
 178       // civicrm_api3('Order', 'create', ['blah' => 'blah', 'contribution_status_id' => 'Pending', 'api.Payment.create => ['total_amount' => 5]]
 179       'api.aliases' => ['order_id'],
 180     ],
 181     'total_amount' => [
 182       'api.required' => 1,
 183       'title' => ts('Total Payment Amount'),
 184       'type' => CRM_Utils_Type::T_FLOAT,
 185     ],
 186     'payment_processor_id' => [
 187       'name' => 'payment_processor_id',
 188       'type' => CRM_Utils_Type::T_INT,
 189       'title' => ts('Payment Processor'),
 190       'description' => ts('Payment Processor for this payment'),
 191       'where' => 'civicrm_financial_trxn.payment_processor_id',
 192       'table_name' => 'civicrm_financial_trxn',
 193       'entity' => 'FinancialTrxn',
 194       'bao' => 'CRM_Financial_DAO_FinancialTrxn',
 195       'localizable' => 0,
 196       'FKClassName' => 'CRM_Financial_DAO_PaymentProcessor',
 197     ],
 198     'id' => [
 199       'title' => ts('Payment ID'),
 200       'type' => CRM_Utils_Type::T_INT,
 201       'api.aliases' => ['payment_id'],
 202     ],
 203     'trxn_date' => [
 204       'title' => ts('Cancel Date'),
 205       'type' => CRM_Utils_Type::T_DATE + CRM_Utils_Type::T_TIME,
 206     ],
 207     'is_send_contribution_notification' => [
 208       'title' => ts('Send out notifications based on contribution status change?'),
 209       'description' => ts('Most commonly this equates to emails relating to the contribution, event, etcwhen a payment completes a contribution'),
 210       'type' => CRM_Utils_Type::T_BOOLEAN,
 211       'api.default' => TRUE,
 212     ],
 213     'payment_instrument_id' => [
 214       'name' => 'payment_instrument_id',
 215       'type' => CRM_Utils_Type::T_INT,
 216       'title' => ts('Payment Method'),
 217       'description' => ts('FK to payment_instrument option group values'),
 218       'where' => 'civicrm_financial_trxn.payment_instrument_id',
 219       'table_name' => 'civicrm_financial_trxn',
 220       'entity' => 'FinancialTrxn',
 221       'bao' => 'CRM_Financial_DAO_FinancialTrxn',
 222       'localizable' => 0,
 223       'html' => [
 224         'type' => 'Select',
 225       ],
 226       'pseudoconstant' => [
 227         'optionGroupName' => 'payment_instrument',
 228         'optionEditPath' => 'civicrm/admin/options/payment_instrument',
 229       ],
 230     ],
 231     'card_type_id' => [
 232       'name' => 'card_type_id',
 233       'type' => CRM_Utils_Type::T_INT,
 234       'title' => ts('Card Type ID'),
 235       'description' => ts('FK to accept_creditcard option group values'),
 236       'where' => 'civicrm_financial_trxn.card_type_id',
 237       'table_name' => 'civicrm_financial_trxn',
 238       'entity' => 'FinancialTrxn',
 239       'bao' => 'CRM_Financial_DAO_FinancialTrxn',
 240       'localizable' => 0,
 241       'html' => [
 242         'type' => 'Select',
 243       ],
 244       'pseudoconstant' => [
 245         'optionGroupName' => 'accept_creditcard',
 246         'optionEditPath' => 'civicrm/admin/options/accept_creditcard',
 247       ],
 248     ],
 249     'trxn_result_code' => [
 250       'name' => 'trxn_result_code',
 251       'type' => CRM_Utils_Type::T_STRING,
 252       'title' => ts('Transaction Result Code'),
 253       'description' => ts('processor result code'),
 254       'maxlength' => 255,
 255       'size' => CRM_Utils_Type::HUGE,
 256       'where' => 'civicrm_financial_trxn.trxn_result_code',
 257       'table_name' => 'civicrm_financial_trxn',
 258       'entity' => 'FinancialTrxn',
 259       'bao' => 'CRM_Financial_DAO_FinancialTrxn',
 260       'localizable' => 0,
 261     ],
 262     'trxn_id' => [
 263       'name' => 'trxn_id',
 264       'type' => CRM_Utils_Type::T_STRING,
 265       'title' => ts('Transaction ID'),
 266       'description' => ts('Transaction id supplied by external processor. This may not be unique.'),
 267       'maxlength' => 255,
 268       'size' => 10,
 269       'where' => 'civicrm_financial_trxn.trxn_id',
 270       'table_name' => 'civicrm_financial_trxn',
 271       'entity' => 'FinancialTrxn',
 272       'bao' => 'CRM_Financial_DAO_FinancialTrxn',
 273       'localizable' => 0,
 274       'html' => [
 275         'type' => 'Text',
 276       ],
 277     ],
 278     'check_number' => [
 279       'name' => 'check_number',
 280       'type' => CRM_Utils_Type::T_STRING,
 281       'title' => ts('Check Number'),
 282       'description' => ts('Check number'),
 283       'maxlength' => 255,
 284       'size' => 6,
 285       'where' => 'civicrm_financial_trxn.check_number',
 286       'table_name' => 'civicrm_financial_trxn',
 287       'entity' => 'FinancialTrxn',
 288       'bao' => 'CRM_Financial_DAO_FinancialTrxn',
 289       'localizable' => 0,
 290       'html' => [
 291         'type' => 'Text',
 292       ],
 293     ],
 294     'pan_truncation' => [
 295       'name' => 'pan_truncation',
 296       'type' => CRM_Utils_Type::T_STRING,
 297       'title' => ts('Pan Truncation'),
 298       'description' => ts('Last 4 digits of credit card'),
 299       'maxlength' => 4,
 300       'size' => 4,
 301       'where' => 'civicrm_financial_trxn.pan_truncation',
 302       'table_name' => 'civicrm_financial_trxn',
 303       'entity' => 'FinancialTrxn',
 304       'bao' => 'CRM_Financial_DAO_FinancialTrxn',
 305       'localizable' => 0,
 306       'html' => [
 307         'type' => 'Text',
 308       ],
 309     ],
 310   ];
 311 }
 312
 313 /**
 314  * Adjust Metadata for Get action.
 315  *
 316  * The metadata is used for setting defaults, documentation & validation.
 317  *
 318  * @param array $params
 319  *   Array of parameters determined by getfields.
 320  */
 321 function _civicrm_api3_payment_get_spec(&$params) {
 322   $params = [
 323     'contribution_id' => [
 324       'title' => 'Contribution ID',
 325       'type' => CRM_Utils_Type::T_INT,
 326     ],
 327     'entity_table' => [
 328       'title' => 'Entity Table',
 329       'api.default' => 'civicrm_contribution',
 330     ],
 331     'entity_id' => [
 332       'title' => 'Entity ID',
 333       'type' => CRM_Utils_Type::T_INT,
 334       'api.aliases' => ['contribution_id'],
 335     ],
 336     'trxn_id' => [
 337       'title' => 'Transaction ID',
 338       'type' => CRM_Utils_Type::T_STRING,
 339     ],
 340   ];
 341 }
 342
 343 /**
 344  * Adjust Metadata for Delete action.
 345  *
 346  * The metadata is used for setting defaults, documentation & validation.
 347  *
 348  * @param array $params
 349  *   Array of parameters.
 350  */
 351 function _civicrm_api3_payment_delete_spec(&$params) {
 352   $params = [
 353     'id' => [
 354       'api.required' => 1,
 355       'title' => 'Payment ID',
 356       'type' => CRM_Utils_Type::T_INT,
 357       'api.aliases' => ['payment_id'],
 358     ],
 359   ];
 360 }
 361
 362 /**
 363  * Adjust Metadata for Cancel action.
 364  *
 365  * The metadata is used for setting defaults, documentation & validation.
 366  *
 367  * @param array $params
 368  *   Array of parameters.
 369  */
 370 function _civicrm_api3_payment_cancel_spec(&$params) {
 371   $params = [
 372     'id' => [
 373       'api.required' => 1,
 374       'title' => 'Payment ID',
 375       'type' => CRM_Utils_Type::T_INT,
 376       'api.aliases' => ['payment_id'],
 377     ],
 378     'trxn_date' => [
 379       'title' => 'Cancel Date',
 380       'type' => CRM_Utils_Type::T_DATE + CRM_Utils_Type::T_TIME,
 381     ],
 382   ];
 383 }
 384
 385 /**
 386  * Send a payment confirmation.
 387  *
 388  * @param array $params
 389  *   Input parameters.
 390  *
 391  * @return array
 392  * @throws Exception
 393  */
 394 function civicrm_api3_payment_sendconfirmation($params) {
 395   $allowedParams = [
 396     'from',
 397     'id',
 398     'check_permissions',
 399   ];
 400   $input = array_intersect_key($params, array_flip($allowedParams));
 401   // use either the contribution or membership receipt, based on whether it’s a membership-related contrib or not
 402   $result = CRM_Financial_BAO_Payment::sendConfirmation($input);
 403   return civicrm_api3_create_success([
 404     $params['id'] => [
 405       'is_sent' => $result[0],
 406       'subject' => $result[1],
 407       'message_txt' => $result[2],
 408       'message_html' => $result[3],
 409     ],
 410   ]);
 411 }
 412
 413 /**
 414  * Adjust Metadata for sendconfirmation action.
 415  *
 416  * The metadata is used for setting defaults, documentation & validation.
 417  *
 418  * @param array $params
 419  *   Array of parameters determined by getfields.
 420  */
 421 function _civicrm_api3_payment_sendconfirmation_spec(&$params) {
 422   $params['id'] = [
 423     'api.required' => 1,
 424     'title' => ts('Payment ID'),
 425     'type' => CRM_Utils_Type::T_INT,
 426   ];
 427   $params['from_email_address'] = [
 428     'title' => ts('From email; an email string or the id of a valid email'),
 429     'type' => CRM_Utils_Type::T_STRING,
 430   ];
 431 }