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