api/v3/Payment.php

   1 <?php
   2 /*
   3  +--------------------------------------------------------------------+
   4  | CiviCRM version 4.7                                                |
   5  +--------------------------------------------------------------------+
   6  | Copyright CiviCRM LLC (c) 2004-2016                                |
   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 = array();
  45   $limit = '';
  46   if (isset($params['options']) && CRM_Utils_Array::value('limit', $params['options'])) {
  47     $limit = CRM_Utils_Array::value('limit', $params['options']);
  48   }
  49   $params['options']['limit'] = 0;
  50   $eft = civicrm_api3('EntityFinancialTrxn', 'get', $params);
  51   if (!empty($eft['values'])) {
  52     $eftIds = array();
  53     foreach ($eft['values'] as $efts) {
  54       if (empty($efts['financial_trxn_id'])) {
  55         continue;
  56       }
  57       $eftIds[] = $efts['financial_trxn_id'];
  58       $map[$efts['financial_trxn_id']] = $efts['entity_id'];
  59     }
  60     if (!empty($eftIds)) {
  61       $ftParams = array(
  62         'id' => array('IN' => $eftIds),
  63         'is_payment' => 1,
  64       );
  65       if ($limit) {
  66         $ftParams['options']['limit'] = $limit;
  67       }
  68       $financialTrxn = civicrm_api3('FinancialTrxn', 'get', $ftParams);
  69       foreach ($financialTrxn['values'] as &$values) {
  70         $values['contribution_id'] = $map[$values['id']];
  71       }
  72     }
  73   }
  74   return civicrm_api3_create_success(CRM_Utils_Array::value('values', $financialTrxn, array()), $params, 'Payment', 'get');
  75 }
  76
  77 /**
  78  * Delete a payment.
  79  *
  80  * @param array $params
  81  *   Input parameters.
  82  *
  83  * @throws API_Exception
  84  * @return array
  85  *   Api result array
  86  */
  87 function civicrm_api3_payment_delete(&$params) {
  88   return civicrm_api3('FinancialTrxn', 'delete', $params);
  89 }
  90
  91 /**
  92  * Cancel/Refund a payment for a Contribution.
  93  *
  94  * @param array $params
  95  *   Input parameters.
  96  *
  97  * @throws API_Exception
  98  * @return array
  99  *   Api result array
 100  */
 101 function civicrm_api3_payment_cancel(&$params) {
 102   $eftParams = array(
 103     'entity_table' => 'civicrm_contribution',
 104     'financial_trxn_id' => $params['id'],
 105   );
 106   $entity = civicrm_api3('EntityFinancialTrxn', 'getsingle', $eftParams);
 107   $contributionId = $entity['entity_id'];
 108   $params['total_amount'] = $entity['amount'];
 109   unset($params['id']);
 110
 111   $trxn = CRM_Contribute_BAO_Contribution::recordAdditionalPayment($contributionId, $params, 'refund', NULL, FALSE);
 112
 113   $values = array();
 114   _civicrm_api3_object_to_array_unique_fields($trxn, $values[$trxn->id]);
 115   return civicrm_api3_create_success($values, $params, 'Payment', 'cancel', $trxn);
 116 }
 117
 118 /**
 119  * Add a payment for a Contribution.
 120  *
 121  * @param array $params
 122  *   Input parameters.
 123  *
 124  * @throws API_Exception
 125  * @return array
 126  *   Api result array
 127  */
 128 function civicrm_api3_payment_create(&$params) {
 129   // Check if it is an update
 130   if (CRM_Utils_Array::value('id', $params)) {
 131     $amount = $params['total_amount'];
 132     civicrm_api3('Payment', 'cancel', $params);
 133     $params['total_amount'] = $amount;
 134   }
 135   // Get contribution
 136   $contribution = civicrm_api3('Contribution', 'getsingle', array('id' => $params['contribution_id']));
 137   if ($contribution['contribution_status'] != 'Partially paid') {
 138     throw new API_Exception('Please select a contribution which has a partial payment');
 139   }
 140   else {
 141     $trxn = CRM_Contribute_BAO_Contribution::recordPartialPayment($contribution, $params);
 142     $paid = CRM_Core_BAO_FinancialTrxn::getTotalPayments($params['contribution_id']);
 143     $total = CRM_Core_DAO::getFieldValue('CRM_Contribute_DAO_Contribution', $params['contribution_id'], 'total_amount');
 144     $cmp = bccomp($total, $paid, 5);
 145     if ($cmp == 0 || $cmp == -1) {// If paid amount is greater or equal to total amount
 146       civicrm_api3('Contribution', 'completetransaction', array('id' => $contribution['id']));
 147     }
 148   }
 149   if (CRM_Utils_Array::value('line_item', $params) && !empty($trxn)) {
 150     foreach ($params['line_item'] as $values) {
 151       foreach ($values as $id => $amount) {
 152         $p = array('id' => $id);
 153         $check = CRM_Price_BAO_LineItem::retrieve($p, $defaults);
 154         if (empty($check)) {
 155           throw new API_Exception('Please specify a valid Line Item.');
 156         }
 157         // get financial item
 158         $sql = "SELECT fi.id
 159           FROM civicrm_financial_item fi
 160           INNER JOIN civicrm_line_item li ON li.id = fi.entity_id
 161           WHERE li.contribution_id = %1 AND li.id = %2";
 162         $sqlParams = array(
 163           1 => array($params['contribution_id'], 'Integer'),
 164           2 => array($id, 'Integer'),
 165         );
 166         $fid = CRM_Core_DAO::singleValueQuery($sql, $sqlParams);
 167         // Record Entity Financial Trxn
 168         $eftParams = array(
 169           'entity_table' => 'civicrm_financial_item',
 170           'financial_trxn_id' => $trxn->id,
 171           'amount' => $amount,
 172           'entity_id' => $fid,
 173         );
 174         civicrm_api3('EntityFinancialTrxn', 'create', $eftParams);
 175       }
 176     }
 177   }
 178   elseif (!empty($trxn)) {
 179     // Assign the lineitems proportionally
 180     CRM_Contribute_BAO_Contribution::assignProportionalLineItems($params, $trxn, $contribution);
 181   }
 182   $values = array();
 183   _civicrm_api3_object_to_array_unique_fields($trxn, $values[$trxn->id]);
 184   return civicrm_api3_create_success($values, $params, 'Payment', 'create', $trxn);
 185 }
 186
 187 /**
 188  * Adjust Metadata for Create action.
 189  *
 190  * The metadata is used for setting defaults, documentation & validation.
 191  *
 192  * @param array $params
 193  *   Array of parameters.
 194  */
 195 function _civicrm_api3_payment_create_spec(&$params) {
 196   $params = array(
 197     'contribution_id' => array(
 198       'api.required' => 1 ,
 199       'title' => 'Contribution ID',
 200       'type' => CRM_Utils_Type::T_INT,
 201     ),
 202     'total_amount' => array(
 203       'api.required' => 1 ,
 204       'title' => 'Total Payment Amount',
 205       'type' => CRM_Utils_Type::T_FLOAT,
 206     ),
 207     'payment_processor_id' => array(
 208       'title' => 'Payment Processor ID',
 209       'type' => CRM_Utils_Type::T_INT,
 210       'description' => ts('Payment processor ID - required for payment processor payments'),
 211     ),
 212     'id' => array(
 213       'title' => 'Payment ID',
 214       'type' => CRM_Utils_Type::T_INT,
 215       'api.aliases' => array('payment_id'),
 216     ),
 217   );
 218 }
 219
 220 /**
 221  * Adjust Metadata for Get action.
 222  *
 223  * The metadata is used for setting defaults, documentation & validation.
 224  *
 225  * @param array $params
 226  *   Array of parameters determined by getfields.
 227  */
 228 function _civicrm_api3_payment_get_spec(&$params) {
 229   $params = array(
 230     'contribution_id' => array(
 231       'title' => 'Contribution ID',
 232       'type' => CRM_Utils_Type::T_INT,
 233     ),
 234     'entity_table' => array(
 235       'title' => 'Entity Table',
 236       'api.default' => 'civicrm_contribution',
 237     ),
 238     'entity_id' => array(
 239       'title' => 'Entity ID',
 240       'type' => CRM_Utils_Type::T_INT,
 241       'api.aliases' => array('contribution_id'),
 242     ),
 243   );
 244 }
 245
 246 /**
 247  * Adjust Metadata for Delete action.
 248  *
 249  * The metadata is used for setting defaults, documentation & validation.
 250  *
 251  * @param array $params
 252  *   Array of parameters.
 253  */
 254 function _civicrm_api3_payment_delete_spec(&$params) {
 255   $params = array(
 256     'id' => array(
 257       'api.required' => 1 ,
 258       'title' => 'Payment ID',
 259       'type' => CRM_Utils_Type::T_INT,
 260       'api.aliases' => array('payment_id'),
 261     ),
 262   );
 263 }
 264
 265 /**
 266  * Adjust Metadata for Cancel action.
 267  *
 268  * The metadata is used for setting defaults, documentation & validation.
 269  *
 270  * @param array $params
 271  *   Array of parameters.
 272  */
 273 function _civicrm_api3_payment_cancel_spec(&$params) {
 274   $params = array(
 275     'id' => array(
 276       'api.required' => 1 ,
 277       'title' => 'Payment ID',
 278       'type' => CRM_Utils_Type::T_INT,
 279       'api.aliases' => array('payment_id'),
 280     ),
 281   );
 282 }