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