CRM/Financial/BAO/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  *
  14  * @package CRM
  15  * @copyright CiviCRM LLC https://civicrm.org/licensing
  16  */
  17
  18 /**
  19  * This class contains payment related functions.
  20  */
  21 class CRM_Financial_BAO_Payment {
  22
  23   /**
  24    * Function to process additional payment for partial and refund contributions.
  25    *
  26    * This function is called via API payment.create function. All forms that add payments
  27    * should use this.
  28    *
  29    * @param array $params
  30    *   - contribution_id
  31    *   - total_amount
  32    *   - line_item
  33    *
  34    * @return \CRM_Financial_DAO_FinancialTrxn
  35    *
  36    * @throws \CRM_Core_Exception
  37    * @throws \CiviCRM_API3_Exception
  38    */
  39   public static function create($params) {
  40     $contribution = civicrm_api3('Contribution', 'getsingle', ['id' => $params['contribution_id']]);
  41     $contributionStatus = CRM_Core_PseudoConstant::getName('CRM_Contribute_BAO_Contribution', 'contribution_status_id', $contribution['contribution_status_id']);
  42     $isPaymentCompletesContribution = self::isPaymentCompletesContribution($params['contribution_id'], $params['total_amount'], $contributionStatus);
  43     $lineItems = self::getPayableLineItems($params);
  44
  45     $whiteList = ['check_number', 'payment_processor_id', 'fee_amount', 'total_amount', 'contribution_id', 'net_amount', 'card_type_id', 'pan_truncation', 'trxn_result_code', 'payment_instrument_id', 'trxn_id', 'trxn_date', 'order_reference'];
  46     $paymentTrxnParams = array_intersect_key($params, array_fill_keys($whiteList, 1));
  47     $paymentTrxnParams['is_payment'] = 1;
  48     // Really we should have a DB default.
  49     $paymentTrxnParams['fee_amount'] = $paymentTrxnParams['fee_amount'] ?? 0;
  50
  51     if (isset($paymentTrxnParams['payment_processor_id']) && empty($paymentTrxnParams['payment_processor_id'])) {
  52       // Don't pass 0 - ie the Pay Later processor as it is  a pseudo-processor.
  53       unset($paymentTrxnParams['payment_processor_id']);
  54     }
  55     if (empty($paymentTrxnParams['payment_instrument_id'])) {
  56       if (!empty($params['payment_processor_id'])) {
  57         $paymentTrxnParams['payment_instrument_id'] = civicrm_api3('PaymentProcessor', 'getvalue', ['return' => 'payment_instrument_id', 'id' => $paymentTrxnParams['payment_processor_id']]);
  58       }
  59       else {
  60         // Fall back  on the payment instrument  already  used - should  we  deprecate  this?
  61         $paymentTrxnParams['payment_instrument_id'] = $contribution['payment_instrument_id'];
  62       }
  63     }
  64     if (empty($paymentTrxnParams['trxn_id']) && !empty($paymentTrxnParams['contribution_trxn_id'])) {
  65       CRM_Core_Error::deprecatedFunctionWarning('contribution_trxn_id is deprecated - use trxn_id');
  66       $paymentTrxnParams['trxn_id'] = $paymentTrxnParams['contribution_trxn_id'];
  67     }
  68
  69     $paymentTrxnParams['currency'] = $contribution['currency'];
  70
  71     $accountsReceivableAccount = CRM_Financial_BAO_FinancialAccount::getFinancialAccountForFinancialTypeByRelationship($contribution['financial_type_id'], 'Accounts Receivable Account is');
  72     $paymentTrxnParams['to_financial_account_id'] = CRM_Contribute_BAO_Contribution::getToFinancialAccount($contribution, $params);
  73     $paymentTrxnParams['from_financial_account_id'] = $accountsReceivableAccount;
  74
  75     if ($params['total_amount'] > 0) {
  76       $paymentTrxnParams['status_id'] = CRM_Core_PseudoConstant::getKey('CRM_Core_BAO_FinancialTrxn', 'status_id', 'Completed');
  77     }
  78     elseif ($params['total_amount'] < 0) {
  79       $paymentTrxnParams['status_id'] = CRM_Core_PseudoConstant::getKey('CRM_Contribute_BAO_Contribution', 'contribution_status_id', 'Refunded');
  80     }
  81
  82     $trxn = CRM_Core_BAO_FinancialTrxn::create($paymentTrxnParams);
  83
  84     if ($params['total_amount'] < 0 && !empty($params['cancelled_payment_id'])) {
  85       self::reverseAllocationsFromPreviousPayment($params, $trxn->id);
  86       return $trxn;
  87     }
  88     list($ftIds, $taxItems) = CRM_Contribute_BAO_Contribution::getLastFinancialItemIds($params['contribution_id']);
  89
  90     foreach ($lineItems as $key => $value) {
  91       if ($value['allocation'] === (float) 0) {
  92         continue;
  93       }
  94
  95       if (!empty($ftIds[$value['price_field_value_id']])) {
  96         $financialItemID = $ftIds[$value['price_field_value_id']];
  97       }
  98       else {
  99         $financialItemID = self::getNewFinancialItemID($value, $params['trxn_date'], $contribution['contact_id'], $paymentTrxnParams['currency']);
 100       }
 101
 102       $eftParams = [
 103         'entity_table' => 'civicrm_financial_item',
 104         'financial_trxn_id' => $trxn->id,
 105         'entity_id' => $financialItemID,
 106         'amount' => $value['allocation'],
 107       ];
 108
 109       civicrm_api3('EntityFinancialTrxn', 'create', $eftParams);
 110
 111       if (array_key_exists($value['price_field_value_id'], $taxItems)) {
 112         // @todo - this is expected to be broken - it should be fixed to
 113         // a) have the getPayableLineItems add the amount to allocate for tax
 114         // b) call EntityFinancialTrxn directly - per above.
 115         // - see https://github.com/civicrm/civicrm-core/pull/14763
 116         $entityParams = [
 117           'contribution_total_amount' => $contribution['total_amount'],
 118           'trxn_total_amount' => $params['total_amount'],
 119           'trxn_id' => $trxn->id,
 120           'line_item_amount' => $taxItems[$value['price_field_value_id']]['amount'],
 121         ];
 122         $eftParams['entity_id'] = $taxItems[$value['price_field_value_id']]['financial_item_id'];
 123         CRM_Contribute_BAO_Contribution::createProportionalEntry($entityParams, $eftParams);
 124       }
 125     }
 126
 127     if ($isPaymentCompletesContribution) {
 128       if ($contributionStatus === 'Pending refund') {
 129         // Ideally we could still call completetransaction as non-payment related actions should
 130         // be outside this class. However, for now we just update the contribution here.
 131         // Unit test cover in CRM_Event_BAO_AdditionalPaymentTest::testTransactionInfo.
 132         civicrm_api3('Contribution', 'create',
 133           [
 134             'id' => $contribution['id'],
 135             'contribution_status_id' => 'Completed',
 136           ]
 137         );
 138       }
 139       else {
 140         civicrm_api3('Contribution', 'completetransaction', [
 141           'id' => $contribution['id'],
 142           'is_post_payment_create' => TRUE,
 143           'is_email_receipt' => $params['is_send_contribution_notification'],
 144           'trxn_date' => $params['trxn_date'],
 145         ]);
 146         // Get the trxn
 147         $trxnId = CRM_Core_BAO_FinancialTrxn::getFinancialTrxnId($contribution['id'], 'DESC');
 148         $ftParams = ['id' => $trxnId['financialTrxnId']];
 149         $trxn = CRM_Core_BAO_FinancialTrxn::retrieve($ftParams);
 150       }
 151     }
 152     elseif ($contributionStatus === 'Pending' && $params['total_amount'] > 0) {
 153       self::updateContributionStatus($contribution['id'], 'Partially Paid');
 154       $participantPayments = civicrm_api3('ParticipantPayment', 'get', [
 155         'contribution_id' => $contribution['id'],
 156         'participant_id.status_id' => ['IN' => ['Pending from pay later', 'Pending from incomplete transaction']],
 157       ])['values'];
 158       foreach ($participantPayments as $participantPayment) {
 159         civicrm_api3('Participant', 'create', ['id' => $participantPayment['participant_id'], 'status_id' => 'Partially paid']);
 160       }
 161     }
 162     elseif ($contributionStatus === 'Completed' && ((float) CRM_Core_BAO_FinancialTrxn::getTotalPayments($contribution['id'], TRUE) === 0.0)) {
 163       // If the contribution has previously been completed (fully paid) and now has total payments adding up to 0
 164       //  change status to refunded.
 165       self::updateContributionStatus($contribution['id'], 'Refunded');
 166     }
 167     self::updateRelatedContribution($params, $params['contribution_id']);
 168     CRM_Contribute_BAO_Contribution::recordPaymentActivity($params['contribution_id'], CRM_Utils_Array::value('participant_id', $params), $params['total_amount'], $trxn->currency, $trxn->trxn_date);
 169     return $trxn;
 170   }
 171
 172   /**
 173    * Function to update contribution's check_number and trxn_id by
 174    *  concatenating values from financial trxn's check_number and trxn_id respectively
 175    *
 176    * @param array $params
 177    * @param int $contributionID
 178    */
 179   public static function updateRelatedContribution($params, $contributionID) {
 180     $contributionDAO = new CRM_Contribute_DAO_Contribution();
 181     $contributionDAO->id = $contributionID;
 182     $contributionDAO->find(TRUE);
 183
 184     foreach (['trxn_id', 'check_number'] as $fieldName) {
 185       if (!empty($params[$fieldName])) {
 186         $values = [];
 187         if (!empty($contributionDAO->$fieldName)) {
 188           $values = explode(',', $contributionDAO->$fieldName);
 189         }
 190         // if submitted check_number or trxn_id value is
 191         //   already present then ignore else add to $values array
 192         if (!in_array($params[$fieldName], $values)) {
 193           $values[] = $params[$fieldName];
 194         }
 195         $contributionDAO->$fieldName = implode(',', $values);
 196       }
 197     }
 198
 199     $contributionDAO->save();
 200   }
 201
 202   /**
 203    * Send an email confirming a payment that has been received.
 204    *
 205    * @param array $params
 206    *
 207    * @return array
 208    *
 209    * @throws \CiviCRM_API3_Exception
 210    */
 211   public static function sendConfirmation($params) {
 212
 213     $entities = self::loadRelatedEntities($params['id']);
 214     $sendTemplateParams = [
 215       'groupName' => 'msg_tpl_workflow_contribution',
 216       'valueName' => 'payment_or_refund_notification',
 217       'PDFFilename' => ts('notification') . '.pdf',
 218       'contactId' => $entities['contact']['id'],
 219       'toName' => $entities['contact']['display_name'],
 220       'toEmail' => $entities['contact']['email'],
 221       'tplParams' => self::getConfirmationTemplateParameters($entities),
 222     ];
 223     if (!empty($params['from']) && !empty($params['check_permissions'])) {
 224       // Filter from against permitted emails.
 225       $validEmails = self::getValidFromEmailsForPayment($entities['event']['id'] ?? NULL);
 226       if (!isset($validEmails[$params['from']])) {
 227         // Ignore unpermitted parameter.
 228         unset($params['from']);
 229       }
 230     }
 231     $sendTemplateParams['from'] = $params['from'] ?? key(CRM_Core_BAO_Email::domainEmails());
 232     return CRM_Core_BAO_MessageTemplate::sendTemplate($sendTemplateParams);
 233   }
 234
 235   /**
 236    * Get valid from emails for payment.
 237    *
 238    * @param int $eventID
 239    *
 240    * @return array
 241    */
 242   public static function getValidFromEmailsForPayment($eventID = NULL) {
 243     if ($eventID) {
 244       $emails = CRM_Event_BAO_Event::getFromEmailIds($eventID);
 245     }
 246     else {
 247       $emails['from_email_id'] = CRM_Core_BAO_Email::getFromEmail();
 248     }
 249     return $emails['from_email_id'];
 250   }
 251
 252   /**
 253    * Load entities related to the current payment id.
 254    *
 255    * This gives us all the data we need to send an email confirmation but avoiding
 256    * getting anything not tested for the confirmations. We retrieve the 'full' event as
 257    * it has been traditionally assigned in full.
 258    *
 259    * @param int $id
 260    *
 261    * @return array
 262    *   - contact = ['id' => x, 'display_name' => y, 'email' => z]
 263    *   - event = [.... full event details......]
 264    *   - contribution = ['id' => x],
 265    *   - payment = [payment info + payment summary info]
 266    * @throws \CiviCRM_API3_Exception
 267    */
 268   protected static function loadRelatedEntities($id) {
 269     $entities = [];
 270     $contributionID = (int) civicrm_api3('EntityFinancialTrxn', 'getvalue', [
 271       'financial_trxn_id' => $id,
 272       'entity_table' => 'civicrm_contribution',
 273       'return' => 'entity_id',
 274     ]);
 275     $entities['contribution'] = ['id' => $contributionID];
 276     $entities['payment'] = array_merge(civicrm_api3('FinancialTrxn', 'getsingle', ['id' => $id]),
 277       CRM_Contribute_BAO_Contribution::getPaymentInfo($contributionID)
 278     );
 279
 280     $contactID = self::getPaymentContactID($contributionID);
 281     list($displayName, $email)  = CRM_Contact_BAO_Contact_Location::getEmailDetails($contactID);
 282     $entities['contact'] = ['id' => $contactID, 'display_name' => $displayName, 'email' => $email];
 283     $contact = civicrm_api3('Contact', 'getsingle', ['id' => $contactID, 'return' => 'email_greeting']);
 284     $entities['contact']['email_greeting'] = $contact['email_greeting_display'];
 285
 286     $participantRecords = civicrm_api3('ParticipantPayment', 'get', [
 287       'contribution_id' => $contributionID,
 288       'api.Participant.get' => ['return' => 'event_id'],
 289       'sequential' => 1,
 290     ])['values'];
 291     if (!empty($participantRecords)) {
 292       $entities['event'] = civicrm_api3('Event', 'getsingle', ['id' => $participantRecords[0]['api.Participant.get']['values'][0]['event_id']]);
 293       if (!empty($entities['event']['is_show_location'])) {
 294         $locationParams = [
 295           'entity_id' => $entities['event']['id'],
 296           'entity_table' => 'civicrm_event',
 297         ];
 298         $entities['location'] = CRM_Core_BAO_Location::getValues($locationParams, TRUE);
 299       }
 300     }
 301
 302     return $entities;
 303   }
 304
 305   /**
 306    * @param int $contributionID
 307    *
 308    * @return int
 309    * @throws \CiviCRM_API3_Exception
 310    * @throws \CiviCRM_API3_Exception
 311    */
 312   public static function getPaymentContactID($contributionID) {
 313     $contribution = civicrm_api3('Contribution', 'getsingle', [
 314       'id' => $contributionID ,
 315       'return' => ['contact_id'],
 316     ]);
 317     return (int) $contribution['contact_id'];
 318   }
 319
 320   /**
 321    * @param array $entities
 322    *   Related entities as an array keyed by the various entities.
 323    *
 324    * @return array
 325    *   Values required for the notification
 326    *   - contact_id
 327    *   - template_variables
 328    *     - event (DAO of event if relevant)
 329    */
 330   public static function getConfirmationTemplateParameters($entities) {
 331     $templateVariables = [
 332       'contactDisplayName' => $entities['contact']['display_name'],
 333       'emailGreeting' => $entities['contact']['email_greeting'],
 334       'totalAmount' => $entities['payment']['total'],
 335       'amountOwed' => $entities['payment']['balance'],
 336       'totalPaid' => $entities['payment']['paid'],
 337       'paymentAmount' => $entities['payment']['total_amount'],
 338       'checkNumber' => $entities['payment']['check_number'] ?? NULL,
 339       'receive_date' => $entities['payment']['trxn_date'],
 340       'paidBy' => CRM_Core_PseudoConstant::getLabel('CRM_Core_BAO_FinancialTrxn', 'payment_instrument_id', $entities['payment']['payment_instrument_id']),
 341       'isShowLocation' => (!empty($entities['event']) ? $entities['event']['is_show_location'] : FALSE),
 342       'location' => $entities['location'] ?? NULL,
 343       'event' => $entities['event'] ?? NULL,
 344       'component' => (!empty($entities['event']) ? 'event' : 'contribution'),
 345       'isRefund' => $entities['payment']['total_amount'] < 0,
 346       'isAmountzero' => $entities['payment']['total_amount'] === 0,
 347       'refundAmount' => ($entities['payment']['total_amount'] < 0 ? $entities['payment']['total_amount'] : NULL),
 348       'paymentsComplete' => ($entities['payment']['balance'] == 0),
 349     ];
 350
 351     return self::filterUntestedTemplateVariables($templateVariables);
 352   }
 353
 354   /**
 355    * Filter out any untested variables.
 356    *
 357    * This just serves to highlight if any variables are added without a unit test also being added.
 358    *
 359    * (if hit then add a unit test for the param & add to this array).
 360    *
 361    * @param array $params
 362    *
 363    * @return array
 364    */
 365   public static function filterUntestedTemplateVariables($params) {
 366     $testedTemplateVariables = [
 367       'contactDisplayName',
 368       'totalAmount',
 369       'amountOwed',
 370       'paymentAmount',
 371       'event',
 372       'component',
 373       'checkNumber',
 374       'receive_date',
 375       'paidBy',
 376       'isShowLocation',
 377       'location',
 378       'isRefund',
 379       'isAmountzero',
 380       'refundAmount',
 381       'totalPaid',
 382       'paymentsComplete',
 383       'emailGreeting',
 384     ];
 385     // These are assigned by the payment form - they still 'get through' from the
 386     // form for now without being in here but we should ideally load
 387     // and assign. Note we should update the tpl to use {if $billingName}
 388     // and ditch contributeMode - although it might need to be deprecated rather than removed.
 389     $todoParams = [
 390       'contributeMode',
 391       'billingName',
 392       'address',
 393       'credit_card_type',
 394       'credit_card_number',
 395       'credit_card_exp_date',
 396     ];
 397     $filteredParams = [];
 398     foreach ($testedTemplateVariables as $templateVariable) {
 399       // This will cause an a-notice if any are NOT set - by design. Ensuring
 400       // they are set prevents leakage.
 401       $filteredParams[$templateVariable] = $params[$templateVariable];
 402     }
 403     return $filteredParams;
 404   }
 405
 406   /**
 407    * Does this payment complete the contribution.
 408    *
 409    * @param int $contributionID
 410    * @param float $paymentAmount
 411    * @param string $previousStatus
 412    *
 413    * @return bool
 414    */
 415   protected static function isPaymentCompletesContribution($contributionID, $paymentAmount, $previousStatus) {
 416     if ($previousStatus === 'Completed') {
 417       return FALSE;
 418     }
 419     $outstandingBalance = CRM_Contribute_BAO_Contribution::getContributionBalance($contributionID);
 420     $cmp = bccomp($paymentAmount, $outstandingBalance, 5);
 421     return ($cmp == 0 || $cmp == 1);
 422   }
 423
 424   /**
 425    * Update the status of the contribution.
 426    *
 427    * We pass the is_post_payment_create as we have already created the line items
 428    *
 429    * @param int $contributionID
 430    * @param string $status
 431    *
 432    * @throws \CiviCRM_API3_Exception
 433    */
 434   private static function updateContributionStatus(int $contributionID, string $status) {
 435     civicrm_api3('Contribution', 'create',
 436       [
 437         'id' => $contributionID,
 438         'is_post_payment_create' => TRUE,
 439         'contribution_status_id' => $status,
 440       ]
 441     );
 442   }
 443
 444   /**
 445    * Get the line items for the contribution.
 446    *
 447    * Retrieve the line items and wrangle the following
 448    *
 449    * - get the outstanding balance on a line item basis.
 450    * - determine what amount is being paid on this line item - we get the total being paid
 451    *   for the whole contribution and determine the ratio of the balance that is being paid
 452    *   and then assign apply that ratio to each line item.
 453    * - if overrides have been passed in we use those amounts instead.
 454    *
 455    * @param $params
 456    *
 457    * @return array
 458    * @throws \CiviCRM_API3_Exception
 459    */
 460   protected static function getPayableLineItems($params): array {
 461     $lineItems = CRM_Price_BAO_LineItem::getLineItemsByContributionID($params['contribution_id']);
 462     $lineItemOverrides = [];
 463     if (!empty($params['line_item'])) {
 464       // The format is a bit weird here - $params['line_item'] => [[1 => 10], [2 => 40]]
 465       // Squash to [1 => 10, 2 => 40]
 466       foreach ($params['line_item'] as $lineItem) {
 467         $lineItemOverrides += $lineItem;
 468       }
 469     }
 470     $outstandingBalance = CRM_Contribute_BAO_Contribution::getContributionBalance($params['contribution_id']);
 471     if ($outstandingBalance !== 0.0) {
 472       $ratio = $params['total_amount'] / $outstandingBalance;
 473     }
 474     else {
 475       // Help we are making a payment but no money is owed. We won't allocate the overpayment to any line item.
 476       $ratio = 0;
 477     }
 478     foreach ($lineItems as $lineItemID => $lineItem) {
 479       // Ideally id would be set deeper but for now just add in here.
 480       $lineItems[$lineItemID]['id'] = $lineItemID;
 481       $lineItems[$lineItemID]['paid'] = self::getAmountOfLineItemPaid($lineItemID);
 482       $lineItems[$lineItemID]['balance'] = $lineItem['subTotal'] - $lineItems[$lineItemID]['paid'];
 483
 484       if (!empty($lineItemOverrides)) {
 485         $lineItems[$lineItemID]['allocation'] = $lineItemOverrides[$lineItemID] ?? NULL;
 486       }
 487       else {
 488         $lineItems[$lineItemID]['allocation'] = $lineItems[$lineItemID]['balance'] * $ratio;
 489       }
 490     }
 491     return $lineItems;
 492   }
 493
 494   /**
 495    * Get the amount paid so far against this line item.
 496    *
 497    * @param int $lineItemID
 498    *
 499    * @return float
 500    *
 501    * @throws \CiviCRM_API3_Exception
 502    */
 503   protected static function getAmountOfLineItemPaid($lineItemID) {
 504     $paid = 0;
 505     $financialItems = civicrm_api3('FinancialItem', 'get', [
 506       'entity_id' => $lineItemID,
 507       'entity_table' => 'civicrm_line_item',
 508       'options' => ['sort' => 'id DESC', 'limit' => 0],
 509     ])['values'];
 510     if (!empty($financialItems)) {
 511       $entityFinancialTrxns = civicrm_api3('EntityFinancialTrxn', 'get', [
 512         'entity_table' => 'civicrm_financial_item',
 513         'entity_id' => ['IN' => array_keys($financialItems)],
 514         'options' => ['limit' => 0],
 515         'financial_trxn_id.is_payment' => 1,
 516       ])['values'];
 517       foreach ($entityFinancialTrxns as $entityFinancialTrxn) {
 518         $paid += $entityFinancialTrxn['amount'];
 519       }
 520     }
 521     return (float) $paid;
 522   }
 523
 524   /**
 525    * Reverse the entity financial transactions associated with the cancelled payment.
 526    *
 527    * The reversals are linked to the new payemnt.
 528    *
 529    * @param array $params
 530    * @param int $trxnID
 531    *
 532    * @throws \CiviCRM_API3_Exception
 533    */
 534   protected static function reverseAllocationsFromPreviousPayment($params, $trxnID) {
 535     // Do a direct reversal of any entity_financial_trxn records being cancelled.
 536     $entityFinancialTrxns = civicrm_api3('EntityFinancialTrxn', 'get', [
 537       'entity_table' => 'civicrm_financial_item',
 538       'options' => ['limit' => 0],
 539       'financial_trxn_id.id' => $params['cancelled_payment_id'],
 540     ])['values'];
 541     foreach ($entityFinancialTrxns as $entityFinancialTrxn) {
 542       civicrm_api3('EntityFinancialTrxn', 'create', [
 543         'entity_table' => 'civicrm_financial_item',
 544         'entity_id' => $entityFinancialTrxn['entity_id'],
 545         'amount' => -$entityFinancialTrxn['amount'],
 546         'financial_trxn_id' => $trxnID,
 547       ]);
 548     }
 549   }
 550
 551   /**
 552    * Create a financial items & return the ID.
 553    *
 554    * Ideally this will never be called.
 555    *
 556    * However, I hit a scenario in testing where 'something' had  created a pending payment with
 557    * no financial items and that would result in a fatal error without handling here. I failed
 558    * to replicate & am not investigating via a new test methodology
 559    * https://github.com/civicrm/civicrm-core/pull/15706
 560    *
 561    * After this is in I will do more digging & once I feel confident new instances are not being
 562    * created I will add deprecation notices into this function with a view to removing.
 563    *
 564    * However, I think we want to add it in 5.20 as there is a risk of users experiencing an error
 565    * if there is incorrect data & we need time to ensure that what I hit was not a 'thing.
 566    * (it might be the demo site data is a bit flawed & that was the issue).
 567    *
 568    * @param array $lineItem
 569    * @param string $trxn_date
 570    * @param int $contactID
 571    * @param string $currency
 572    *
 573    * @return int
 574    *
 575    * @throws \CiviCRM_API3_Exception
 576    */
 577   protected static function getNewFinancialItemID($lineItem, $trxn_date, $contactID, $currency): int {
 578     $financialAccount = CRM_Financial_BAO_FinancialAccount::getFinancialAccountForFinancialTypeByRelationship(
 579       $lineItem['financial_type_id'],
 580       'Income Account Is'
 581     );
 582     $itemParams = [
 583       'transaction_date' => $trxn_date,
 584       'contact_id' => $contactID,
 585       'currency' => $currency,
 586       'amount' => $lineItem['line_total'],
 587       'description' => $lineItem['label'],
 588       'status_id' => 'Unpaid',
 589       'financial_account_id' => $financialAccount,
 590       'entity_table' => 'civicrm_line_item',
 591       'entity_id' => $lineItem['id'],
 592     ];
 593     return (int) civicrm_api3('FinancialItem', 'create', $itemParams)['id'];
 594   }
 595
 596 }