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     'return' => ['entity', 'amount', 'entity_id', 'financial_trxn_id.check_number'],
  98   ];
  99   $entity = civicrm_api3('EntityFinancialTrxn', 'getsingle', $eftParams);
 100
 101   $paymentParams = [
 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,
 107   ];
 108
 109   foreach (['trxn_id', 'payment_instrument_id'] as $permittedParam) {
 110     if (isset($params[$permittedParam])) {
 111       $paymentParams[$permittedParam] = $params[$permittedParam];
 112     }
 113   }
 114   $result = civicrm_api3('Payment', 'create', $paymentParams);
 115   return civicrm_api3_create_success($result['values'], $params, 'Payment', 'cancel');
 116 }
 117
 118 /**
 119  * Add a payment for a Contribution.
 120  *
 121  * @param array $params
 122  *   Input parameters.
 123  *
 124  * @return array
 125  *   Api result array
 126  *
 127  * @throws \CRM_Core_Exception
 128  * @throws \CiviCRM_API3_Exception
 129  */
 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]);
 135       }
 136     }
 137   }
 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;
 143   }
 144   $trxn = CRM_Financial_BAO_Payment::create($params);
 145
 146   $values = [];
 147   _civicrm_api3_object_to_array_unique_fields($trxn, $values[$trxn->id]);
 148   return civicrm_api3_create_success($values, $params, 'Payment', 'create', $trxn);
 149 }
 150
 151 /**
 152  * Adjust Metadata for Create action.
 153  *
 154  * The metadata is used for setting defaults, documentation & validation.
 155  *
 156  * @param array $params
 157  *   Array of parameters.
 158  */
 159 function _civicrm_api3_payment_create_spec(&$params) {
 160   $params = [
 161     'contribution_id' => [
 162       'api.required' => 1,
 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'],
 168     ],
 169     'total_amount' => [
 170       'api.required' => 1,
 171       'title' => ts('Total Payment Amount'),
 172       'type' => CRM_Utils_Type::T_FLOAT,
 173     ],
 174     'fee_amount' => [
 175       'title' => ts('Fee Amount'),
 176       'type' => CRM_Utils_Type::T_FLOAT,
 177     ],
 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',
 187       'localizable' => 0,
 188       'FKClassName' => 'CRM_Financial_DAO_PaymentProcessor',
 189     ],
 190     'id' => [
 191       'title' => ts('Payment ID'),
 192       'type' => CRM_Utils_Type::T_INT,
 193       'api.aliases' => ['payment_id'],
 194     ],
 195     'trxn_date' => [
 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,
 200     ],
 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,
 206     ],
 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',
 216       'localizable' => 0,
 217       'html' => [
 218         'type' => 'Select',
 219       ],
 220       'pseudoconstant' => [
 221         'optionGroupName' => 'payment_instrument',
 222         'optionEditPath' => 'civicrm/admin/options/payment_instrument',
 223       ],
 224     ],
 225     'card_type_id' => [
 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',
 234       'localizable' => 0,
 235       'html' => [
 236         'type' => 'Select',
 237       ],
 238       'pseudoconstant' => [
 239         'optionGroupName' => 'accept_creditcard',
 240         'optionEditPath' => 'civicrm/admin/options/accept_creditcard',
 241       ],
 242     ],
 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'),
 248       'maxlength' => 255,
 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',
 254       'localizable' => 0,
 255     ],
 256     'trxn_id' => [
 257       'name' => 'trxn_id',
 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.'),
 261       'maxlength' => 255,
 262       'size' => 10,
 263       'where' => 'civicrm_financial_trxn.trxn_id',
 264       'table_name' => 'civicrm_financial_trxn',
 265       'entity' => 'FinancialTrxn',
 266       'bao' => 'CRM_Financial_DAO_FinancialTrxn',
 267       'localizable' => 0,
 268       'html' => [
 269         'type' => 'Text',
 270       ],
 271     ],
 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',
 277       'maxlength' => 255,
 278       'size' => 25,
 279       'where' => 'civicrm_financial_trxn.order_reference',
 280       'table_name' => 'civicrm_financial_trxn',
 281       'entity' => 'FinancialTrxn',
 282       'bao' => 'CRM_Financial_DAO_FinancialTrxn',
 283       'localizable' => 0,
 284       'html' => [
 285         'type' => 'Text',
 286       ],
 287     ],
 288     'check_number' => [
 289       'name' => 'check_number',
 290       'type' => CRM_Utils_Type::T_STRING,
 291       'title' => ts('Check Number'),
 292       'description' => ts('Check number'),
 293       'maxlength' => 255,
 294       'size' => 6,
 295       'where' => 'civicrm_financial_trxn.check_number',
 296       'table_name' => 'civicrm_financial_trxn',
 297       'entity' => 'FinancialTrxn',
 298       'bao' => 'CRM_Financial_DAO_FinancialTrxn',
 299       'localizable' => 0,
 300       'html' => [
 301         'type' => 'Text',
 302       ],
 303     ],
 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'),
 309       'maxlength' => 4,
 310       'size' => 4,
 311       'where' => 'civicrm_financial_trxn.pan_truncation',
 312       'table_name' => 'civicrm_financial_trxn',
 313       'entity' => 'FinancialTrxn',
 314       'bao' => 'CRM_Financial_DAO_FinancialTrxn',
 315       'localizable' => 0,
 316       'html' => [
 317         'type' => 'Text',
 318       ],
 319     ],
 320   ];
 321 }
 322
 323 /**
 324  * Adjust Metadata for Get action.
 325  *
 326  * The metadata is used for setting defaults, documentation & validation.
 327  *
 328  * @param array $params
 329  *   Array of parameters determined by getfields.
 330  */
 331 function _civicrm_api3_payment_get_spec(&$params) {
 332   $params = [
 333     'contribution_id' => [
 334       'title' => ts('Contribution ID'),
 335       'type' => CRM_Utils_Type::T_INT,
 336     ],
 337     'entity_id' => [
 338       'title' => ts('Entity ID'),
 339       'type' => CRM_Utils_Type::T_INT,
 340       'api.aliases' => ['contribution_id'],
 341     ],
 342     'trxn_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,
 346     ],
 347     'order_reference' => [
 348       'title' => ts('Order Reference'),
 349       'description' => ts('Payment Processor external order reference'),
 350       'type' => CRM_Utils_Type::T_STRING,
 351     ],
 352     'trxn_date' => [
 353       'title' => ts('Payment Date'),
 354       'type' => CRM_Utils_Type::T_TIMESTAMP,
 355     ],
 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'],
 361     ],
 362   ];
 363 }
 364
 365 /**
 366  * Adjust Metadata for Delete action.
 367  *
 368  * The metadata is used for setting defaults, documentation & validation.
 369  *
 370  * @param array $params
 371  *   Array of parameters.
 372  */
 373 function _civicrm_api3_payment_delete_spec(&$params) {
 374   $params = [
 375     'id' => [
 376       'api.required' => 1,
 377       'title' => 'Payment ID',
 378       'type' => CRM_Utils_Type::T_INT,
 379       'api.aliases' => ['payment_id'],
 380     ],
 381   ];
 382 }
 383
 384 /**
 385  * Adjust Metadata for Cancel action.
 386  *
 387  * The metadata is used for setting defaults, documentation & validation.
 388  *
 389  * @param array $params
 390  *   Array of parameters.
 391  */
 392 function _civicrm_api3_payment_cancel_spec(&$params) {
 393   $params = [
 394     'id' => [
 395       'api.required' => 1,
 396       'title' => 'Payment ID',
 397       'type' => CRM_Utils_Type::T_INT,
 398       'api.aliases' => ['payment_id'],
 399     ],
 400     'trxn_date' => [
 401       'title' => 'Cancel Date',
 402       'type' => CRM_Utils_Type::T_DATE + CRM_Utils_Type::T_TIME,
 403     ],
 404   ];
 405 }
 406
 407 /**
 408  * Send a payment confirmation.
 409  *
 410  * @param array $params
 411  *   Input parameters.
 412  *
 413  * @return array
 414  * @throws Exception
 415  */
 416 function civicrm_api3_payment_sendconfirmation($params) {
 417   $allowedParams = [
 418     'from',
 419     'id',
 420     'check_permissions',
 421   ];
 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([
 426     $params['id'] => [
 427       'is_sent' => $result[0],
 428       'subject' => $result[1],
 429       'message_txt' => $result[2],
 430       'message_html' => $result[3],
 431     ],
 432   ]);
 433 }
 434
 435 /**
 436  * Adjust Metadata for sendconfirmation action.
 437  *
 438  * The metadata is used for setting defaults, documentation & validation.
 439  *
 440  * @param array $params
 441  *   Array of parameters determined by getfields.
 442  */
 443 function _civicrm_api3_payment_sendconfirmation_spec(&$params) {
 444   $params['id'] = [
 445     'api.required' => 1,
 446     'title' => ts('Payment ID'),
 447     'type' => CRM_Utils_Type::T_INT,
 448   ];
 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,
 452   ];
 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,
 457     'api.default' => 0,
 458   ];
 459 }