api/v3/Payment.php

   1 <?php
   2 /*
   3  +--------------------------------------------------------------------+
   4  | Copyright CiviCRM LLC. All rights reserved.                        |
   5  |                                                                    |
   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  +--------------------------------------------------------------------+
  10  */
  11
  12 /**
  13  * This api exposes CiviCRM Contribution Payment records.
  14  *
  15  * @package CiviCRM_APIv3
  16  */
  17
  18 /**
  19  * Retrieve a set of financial transactions which are payments.
  20  *
  21  * @param array $params
  22  *  Input parameters.
  23  *
  24  * @return array
  25  *   Array of financial transactions which are payments, if error an array with an error id and error message
  26  *
  27  * @throws \CiviCRM_API3_Exception
  28  */
  29 function civicrm_api3_payment_get($params) {
  30   $params['is_payment'] = TRUE;
  31   $contributionID = $params['entity_id'] ?? NULL;
  32
  33   // In order to support contribution id we need to do an extra lookup.
  34   if ($contributionID) {
  35     $eftParams = [
  36       'entity_id' => $contributionID,
  37       'entity_table' => 'civicrm_contribution',
  38       'options' => ['limit' => 0],
  39       'financial_trxn_id.is_payment' => 1,
  40     ];
  41     $eft = civicrm_api3('EntityFinancialTrxn', 'get', $eftParams)['values'];
  42     if (empty($eft)) {
  43       return civicrm_api3_create_success([], $params, 'Payment', 'get');
  44     }
  45     foreach ($eft as $entityFinancialTrxn) {
  46       $params['financial_trxn_id']['IN'][] = $entityFinancialTrxn['financial_trxn_id'];
  47     }
  48   }
  49
  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;
  54     }
  55   }
  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'];
  60     }
  61   }
  62
  63   return civicrm_api3_create_success($financialTrxn, $params, 'Payment', 'get');
  64 }
  65
  66 /**
  67  * Delete a payment.
  68  *
  69  * @param array $params
  70  *   Input parameters.
  71  *
  72  * @return array
  73  *   Api result array
  74  *
  75  * @throws \CiviCRM_API3_Exception
  76  */
  77 function civicrm_api3_payment_delete($params) {
  78   return civicrm_api3('FinancialTrxn', 'delete', $params);
  79 }
  80
  81 /**
  82  * Cancel/Refund a payment for a Contribution.
  83  *
  84  * @param array $params
  85  *   Input parameters.
  86  *
  87  * @return array
  88  *   Api result array
  89  *
  90  * @throws \CiviCRM_API3_Exception
  91  * @throws API_Exception
  92  */
  93 function civicrm_api3_payment_cancel($params) {
  94   $eftParams = [
  95     'entity_table' => 'civicrm_contribution',
  96     'financial_trxn_id' => $params['id'],
  97   ];
  98   $entity = civicrm_api3('EntityFinancialTrxn', 'getsingle', $eftParams);
  99
 100   $paymentParams = [
 101     'total_amount' => -$entity['amount'],
 102     'contribution_id' => $entity['entity_id'],
 103     'trxn_date' => $params['trxn_date'] ?? 'now',
 104     'cancelled_payment_id' => $params['id'],
 105   ];
 106
 107   foreach (['trxn_id', 'payment_instrument_id'] as $permittedParam) {
 108     if (isset($params[$permittedParam])) {
 109       $paymentParams[$permittedParam] = $params[$permittedParam];
 110     }
 111   }
 112   $result = civicrm_api3('Payment', 'create', $paymentParams);
 113   return civicrm_api3_create_success($result['values'], $params, 'Payment', 'cancel');
 114 }
 115
 116 /**
 117  * Add a payment for a Contribution.
 118  *
 119  * @param array $params
 120  *   Input parameters.
 121  *
 122  * @return array
 123  *   Api result array
 124  *
 125  * @throws \CRM_Core_Exception
 126  * @throws \CiviCRM_API3_Exception
 127  */
 128 function civicrm_api3_payment_create($params) {
 129   if (empty($params['skipCleanMoney'])) {
 130     foreach (['total_amount', 'net_amount', 'fee_amount'] as $field) {
 131       if (isset($params[$field])) {
 132         $params[$field] = CRM_Utils_Rule::cleanMoney($params[$field]);
 133       }
 134     }
 135   }
 136   if (!empty($params['payment_processor'])) {
 137     // I can't find evidence this is passed in - I was gonna just remove it but decided to deprecate  as I see getToFinancialAccount
 138     // also anticipates it.
 139     CRM_Core_Error::deprecatedFunctionWarning('passing payment_processor is deprecated - use payment_processor_id');
 140     $params['payment_processor_id'] = $params['payment_processor'];
 141   }
 142   // Check if it is an update
 143   if (!empty($params['id'])) {
 144     $amount = $params['total_amount'];
 145     civicrm_api3('Payment', 'cancel', $params);
 146     $params['total_amount'] = $amount;
 147   }
 148   $trxn = CRM_Financial_BAO_Payment::create($params);
 149
 150   $values = [];
 151   _civicrm_api3_object_to_array_unique_fields($trxn, $values[$trxn->id]);
 152   return civicrm_api3_create_success($values, $params, 'Payment', 'create', $trxn);
 153 }
 154
 155 /**
 156  * Adjust Metadata for Create action.
 157  *
 158  * The metadata is used for setting defaults, documentation & validation.
 159  *
 160  * @param array $params
 161  *   Array of parameters.
 162  */
 163 function _civicrm_api3_payment_create_spec(&$params) {
 164   $params = [
 165     'contribution_id' => [
 166       'api.required' => 1,
 167       'title' => ts('Contribution ID'),
 168       'type' => CRM_Utils_Type::T_INT,
 169       // We accept order_id as an alias so that we can chain like
 170       // civicrm_api3('Order', 'create', ['blah' => 'blah', 'contribution_status_id' => 'Pending', 'api.Payment.create => ['total_amount' => 5]]
 171       'api.aliases' => ['order_id'],
 172     ],
 173     'total_amount' => [
 174       'api.required' => 1,
 175       'title' => ts('Total Payment Amount'),
 176       'type' => CRM_Utils_Type::T_FLOAT,
 177     ],
 178     'fee_amount' => [
 179       'title' => ts('Fee Amount'),
 180       'type' => CRM_Utils_Type::T_FLOAT,
 181     ],
 182     'payment_processor_id' => [
 183       'name' => 'payment_processor_id',
 184       'type' => CRM_Utils_Type::T_INT,
 185       'title' => ts('Payment Processor'),
 186       'description' => ts('Payment Processor for this payment'),
 187       'where' => 'civicrm_financial_trxn.payment_processor_id',
 188       'table_name' => 'civicrm_financial_trxn',
 189       'entity' => 'FinancialTrxn',
 190       'bao' => 'CRM_Financial_DAO_FinancialTrxn',
 191       'localizable' => 0,
 192       'FKClassName' => 'CRM_Financial_DAO_PaymentProcessor',
 193     ],
 194     'id' => [
 195       'title' => ts('Payment ID'),
 196       'type' => CRM_Utils_Type::T_INT,
 197       'api.aliases' => ['payment_id'],
 198     ],
 199     'trxn_date' => [
 200       'title' => ts('Payment Date'),
 201       'type' => CRM_Utils_Type::T_DATE + CRM_Utils_Type::T_TIME,
 202       'api.default' => 'now',
 203       'api.required' => TRUE,
 204     ],
 205     'is_send_contribution_notification' => [
 206       'title' => ts('Send out notifications based on contribution status change?'),
 207       'description' => ts('Most commonly this equates to emails relating to the contribution, event, etcwhen a payment completes a contribution'),
 208       'type' => CRM_Utils_Type::T_BOOLEAN,
 209       'api.default' => TRUE,
 210     ],
 211     'payment_instrument_id' => [
 212       'name' => 'payment_instrument_id',
 213       'type' => CRM_Utils_Type::T_INT,
 214       'title' => ts('Payment Method'),
 215       'description' => ts('FK to payment_instrument option group values'),
 216       'where' => 'civicrm_financial_trxn.payment_instrument_id',
 217       'table_name' => 'civicrm_financial_trxn',
 218       'entity' => 'FinancialTrxn',
 219       'bao' => 'CRM_Financial_DAO_FinancialTrxn',
 220       'localizable' => 0,
 221       'html' => [
 222         'type' => 'Select',
 223       ],
 224       'pseudoconstant' => [
 225         'optionGroupName' => 'payment_instrument',
 226         'optionEditPath' => 'civicrm/admin/options/payment_instrument',
 227       ],
 228     ],
 229     'card_type_id' => [
 230       'name' => 'card_type_id',
 231       'type' => CRM_Utils_Type::T_INT,
 232       'title' => ts('Card Type ID'),
 233       'description' => ts('FK to accept_creditcard option group values'),
 234       'where' => 'civicrm_financial_trxn.card_type_id',
 235       'table_name' => 'civicrm_financial_trxn',
 236       'entity' => 'FinancialTrxn',
 237       'bao' => 'CRM_Financial_DAO_FinancialTrxn',
 238       'localizable' => 0,
 239       'html' => [
 240         'type' => 'Select',
 241       ],
 242       'pseudoconstant' => [
 243         'optionGroupName' => 'accept_creditcard',
 244         'optionEditPath' => 'civicrm/admin/options/accept_creditcard',
 245       ],
 246     ],
 247     'trxn_result_code' => [
 248       'name' => 'trxn_result_code',
 249       'type' => CRM_Utils_Type::T_STRING,
 250       'title' => ts('Transaction Result Code'),
 251       'description' => ts('processor result code'),
 252       'maxlength' => 255,
 253       'size' => CRM_Utils_Type::HUGE,
 254       'where' => 'civicrm_financial_trxn.trxn_result_code',
 255       'table_name' => 'civicrm_financial_trxn',
 256       'entity' => 'FinancialTrxn',
 257       'bao' => 'CRM_Financial_DAO_FinancialTrxn',
 258       'localizable' => 0,
 259     ],
 260     'trxn_id' => [
 261       'name' => 'trxn_id',
 262       'type' => CRM_Utils_Type::T_STRING,
 263       'title' => ts('Transaction ID'),
 264       'description' => ts('Transaction id supplied by external processor. This may not be unique.'),
 265       'maxlength' => 255,
 266       'size' => 10,
 267       'where' => 'civicrm_financial_trxn.trxn_id',
 268       'table_name' => 'civicrm_financial_trxn',
 269       'entity' => 'FinancialTrxn',
 270       'bao' => 'CRM_Financial_DAO_FinancialTrxn',
 271       'localizable' => 0,
 272       'html' => [
 273         'type' => 'Text',
 274       ],
 275     ],
 276     'order_reference' => [
 277       'name' => 'order_reference',
 278       'type' => CRM_Utils_Type::T_STRING,
 279       'title' => 'Order Reference',
 280       'description' => 'Payment Processor external order reference',
 281       'maxlength' => 255,
 282       'size' => 25,
 283       'where' => 'civicrm_financial_trxn.order_reference',
 284       'table_name' => 'civicrm_financial_trxn',
 285       'entity' => 'FinancialTrxn',
 286       'bao' => 'CRM_Financial_DAO_FinancialTrxn',
 287       'localizable' => 0,
 288       'html' => [
 289         'type' => 'Text',
 290       ],
 291     ],
 292     'check_number' => [
 293       'name' => 'check_number',
 294       'type' => CRM_Utils_Type::T_STRING,
 295       'title' => ts('Check Number'),
 296       'description' => ts('Check number'),
 297       'maxlength' => 255,
 298       'size' => 6,
 299       'where' => 'civicrm_financial_trxn.check_number',
 300       'table_name' => 'civicrm_financial_trxn',
 301       'entity' => 'FinancialTrxn',
 302       'bao' => 'CRM_Financial_DAO_FinancialTrxn',
 303       'localizable' => 0,
 304       'html' => [
 305         'type' => 'Text',
 306       ],
 307     ],
 308     'pan_truncation' => [
 309       'name' => 'pan_truncation',
 310       'type' => CRM_Utils_Type::T_STRING,
 311       'title' => ts('PAN Truncation'),
 312       'description' => ts('Last 4 digits of credit card'),
 313       'maxlength' => 4,
 314       'size' => 4,
 315       'where' => 'civicrm_financial_trxn.pan_truncation',
 316       'table_name' => 'civicrm_financial_trxn',
 317       'entity' => 'FinancialTrxn',
 318       'bao' => 'CRM_Financial_DAO_FinancialTrxn',
 319       'localizable' => 0,
 320       'html' => [
 321         'type' => 'Text',
 322       ],
 323     ],
 324   ];
 325 }
 326
 327 /**
 328  * Adjust Metadata for Get action.
 329  *
 330  * The metadata is used for setting defaults, documentation & validation.
 331  *
 332  * @param array $params
 333  *   Array of parameters determined by getfields.
 334  */
 335 function _civicrm_api3_payment_get_spec(&$params) {
 336   $params = [
 337     'contribution_id' => [
 338       'title' => ts('Contribution ID'),
 339       'type' => CRM_Utils_Type::T_INT,
 340     ],
 341     'entity_id' => [
 342       'title' => ts('Entity ID'),
 343       'type' => CRM_Utils_Type::T_INT,
 344       'api.aliases' => ['contribution_id'],
 345     ],
 346     'trxn_id' => [
 347       'title' => ts('Transaction ID'),
 348       'description' => ts('Transaction id supplied by external processor. This may not be unique.'),
 349       'type' => CRM_Utils_Type::T_STRING,
 350     ],
 351     'trxn_date' => [
 352       'title' => ts('Payment Date'),
 353       'type' => CRM_Utils_Type::T_TIMESTAMP,
 354     ],
 355     'financial_trxn_id' => [
 356       'title' => ts('Payment ID'),
 357       'description' => ts('The ID of the record in civicrm_financial_trxn'),
 358       'type' => CRM_Utils_Type::T_INT,
 359       'api.aliases' => ['payment_id', 'id'],
 360     ],
 361   ];
 362 }
 363
 364 /**
 365  * Adjust Metadata for Delete action.
 366  *
 367  * The metadata is used for setting defaults, documentation & validation.
 368  *
 369  * @param array $params
 370  *   Array of parameters.
 371  */
 372 function _civicrm_api3_payment_delete_spec(&$params) {
 373   $params = [
 374     'id' => [
 375       'api.required' => 1,
 376       'title' => 'Payment ID',
 377       'type' => CRM_Utils_Type::T_INT,
 378       'api.aliases' => ['payment_id'],
 379     ],
 380   ];
 381 }
 382
 383 /**
 384  * Adjust Metadata for Cancel action.
 385  *
 386  * The metadata is used for setting defaults, documentation & validation.
 387  *
 388  * @param array $params
 389  *   Array of parameters.
 390  */
 391 function _civicrm_api3_payment_cancel_spec(&$params) {
 392   $params = [
 393     'id' => [
 394       'api.required' => 1,
 395       'title' => 'Payment ID',
 396       'type' => CRM_Utils_Type::T_INT,
 397       'api.aliases' => ['payment_id'],
 398     ],
 399     'trxn_date' => [
 400       'title' => 'Cancel Date',
 401       'type' => CRM_Utils_Type::T_DATE + CRM_Utils_Type::T_TIME,
 402     ],
 403   ];
 404 }
 405
 406 /**
 407  * Send a payment confirmation.
 408  *
 409  * @param array $params
 410  *   Input parameters.
 411  *
 412  * @return array
 413  * @throws Exception
 414  */
 415 function civicrm_api3_payment_sendconfirmation($params) {
 416   $allowedParams = [
 417     'from',
 418     'id',
 419     'check_permissions',
 420   ];
 421   $input = array_intersect_key($params, array_flip($allowedParams));
 422   // use either the contribution or membership receipt, based on whether it’s a membership-related contrib or not
 423   $result = CRM_Financial_BAO_Payment::sendConfirmation($input);
 424   return civicrm_api3_create_success([
 425     $params['id'] => [
 426       'is_sent' => $result[0],
 427       'subject' => $result[1],
 428       'message_txt' => $result[2],
 429       'message_html' => $result[3],
 430     ],
 431   ]);
 432 }
 433
 434 /**
 435  * Adjust Metadata for sendconfirmation action.
 436  *
 437  * The metadata is used for setting defaults, documentation & validation.
 438  *
 439  * @param array $params
 440  *   Array of parameters determined by getfields.
 441  */
 442 function _civicrm_api3_payment_sendconfirmation_spec(&$params) {
 443   $params['id'] = [
 444     'api.required' => 1,
 445     'title' => ts('Payment ID'),
 446     'type' => CRM_Utils_Type::T_INT,
 447   ];
 448   $params['from_email_address'] = [
 449     'title' => ts('From email; an email string or the id of a valid email'),
 450     'type' => CRM_Utils_Type::T_STRING,
 451   ];
 452   $params['is_send_contribution_notification'] = [
 453     'title' => ts('Send any event or contribution confirmations triggered by this payment'),
 454     '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'),
 455     'type' => CRM_Utils_Type::T_BOOLEAN,
 456     'api.default' => 0,
 457   ];
 458 }