Aller directement à la fin des métadonnées
Aller au début des métadonnées

Overview

This is a high level API intended to wrap the accounting functionality and business object workflow associated with CiviCRM receiving a payment. It will support partial and full payments for a contribution, as well as cancelling a payment.

Phase I is intended to implement the API so that it can be used by extensions and new core functionality. A later phase may refactor core code to improve maintainability of contribution, membership, participant, and pledge payment functionality.

Schema Change and Upgrade SQL

While the bookkeeping transactions have been correct, to provide CiviCRM users with insight into Payments that have been made requires identifying which entries in civicrm_financial_trxn correspond to payments. Without a knowledge of the configuration of other parts of the system at the time transactions are entered it is not possible to distinguish Pay Later from Payment entries, unfortunately. So as part of Phase I, a new field needs to be added to civicrm_financial_trxn in order to provide an assured way of determining which are payments:

<field>
 <name>is_payment</name> 
 <title>Is Payment?</title> 
 <type>boolean</type> 
 <default>0</default> 
 <import>true</import>

 

 

<comment>Is this entry either a payment or a reversal of a payment?</comment>

 <add>4.7</add> 
 <html> 
  <type>CheckBox</type>
 </html> 
</field  

Implement use of field as per references to it on CiviAccounts Data Flow added June 12.

For upgrade, use

ALTER TABLE civicrm_financial_trxn ADD COLUMN is_payment tinyint(4) DEFAULT '0' COMMENT 'Is this entry either a payment or a reversal of a payment?';

To determine with a very high confidence level which civicrm_financial_trxn records are for payments, we note that financial_accounts currently configured to be in a relationship of 'Asset account is' with a financial type are exceptionally unlikely to have transactions recorded against them in the same db when they were used for a different purpose. These accounts are:

select financial_account_id from civicrm_entity_financial_account efa inner join civicrm_option_value v ON efa.account_relationship=v.value AND v.name='Asset Account is' INNER JOIN civicrm_option_group g on v.option_group_id=g.id where g.name='account_relationship' group by financial_account_id;

So the payment transactions for upgrade purposes are updated as follows:

UPDATE civicrm_financial_trxn ft INNER JOIN (select financial_account_id from civicrm_entity_financial_account efa inner join civicrm_option_value v ON efa.account_relationship=v.value AND v.name='Asset Account is' INNER JOIN civicrm_option_group g on v.option_group_id=g.id where g.name='account_relationship' group by financial_account_id) AS asset_fa ON ft.to_financial_account_id=asset_fa.financial_account_id SET ft.is_payment=TRUE;

Create

Payments set the civicrm_financial_trxn.is_payment field to TRUE. This is true even for payments with a negative total_amount, which may represent cancelled payments that should show up in a payments tab or report.

Simple payment (total_amount of payment is distributed proportionally among line items)

civicrm_api3('payment', 'create', array( 'sequential' => 1, 'contribution_id' => 11, 'total_amount' => '100.00', 'payment_instrument_id' => 4));

Payment with specified distribution between line items

civicrm_api3('payment','create', array( 'sequential' => 1, 'contribution_id' => 11, /* optional: 'total_amount' => '100.00', */ 'payment_instrument_id' => 4,

  line_item => array( array('id' = 44, '75.00'), array(45,'25.00'))  ) );

Spec

function _civicrm_api3_payment_create_spec(&$params) {
$params['contribution_id']['api.required'] = TRUE;
  $params['total_amount']['api.required'] = TRUE; 
  $params['payment_instrument_id']['api.required'] = FALSE; // if not provided, Financial Account of default Asset account will be used  
  $params['payment_processor_id']['api.required'] = FALSE; // offline payments do not involve a payment processor
  $params['payment_processor_id']['description'] = 'Payment processor ID - required for payment processor payments'; 
}

Tests

Create unit tests similar to some in https://github.com/civicrm/civicrm-core/blob/master/tests/phpunit/CRM/Contribute/Form/ContributionTest.php

Get

civicrm_api3('payment', 'get', array('sequential' => 1, 'contribution_id' => 11) );

This returns all of civicrm_financial_trxn rows with is_payment=1 for contribution with id=11.

Spec

function _civicrm_api3_payment_get_spec(&$params) {

 }

Update

Updates of payments are implemented as a reversal of the original payment transaction and the creation of a new one according the parameters provided. civicrm_financial_trxn.is_payment is set to TRUE for the reversal and the new payment. This is true even for payments with a negative total_amount.

Simple payment (total_amount of payment is distributed proportionally among line items)

civicrm_api3('payment', 'update', array( 'sequential' => 1, 'payment_id' => 12, 'contribution_id' => 11, 'total_amount' => '10.00', 'payment_instrument_id' => 6));

Payment with specified distribution between line items

civicrm_api3('payment','create', array( 'sequential' => 1, 'payment_id' => 12, 'contribution_id' => 11, /* optional: 'total_amount' => '10.00', */ 'payment_instrument_id' => 6,
  line_item => array( array('id' = 44, '7.50'), array(45, '2.50'))  ) );
function _civicrm_api3_payment_update_spec(&$params) {
  $params['civicrm_financial_trxn_id']['api.required'] = TRUE; // NB: can also be referred to as payment_id
}

Cancel

Cancellation of payments is implemented as a reversal of the original payment transaction. civicrm_financial_trxn.is_payment is set to TRUE for the reversal.

civicrm_api3('payment', 'cancel', array( 'sequential' => 1, 'payment_id' => 12)
function _civicrm_api3_payment_cancel_spec(&$params) {
  $params['civicrm_financial_trxn_id']['api.required'] = TRUE; // NB: can also be referred to as payment_id
}

Delete

Deletion of payments should never be done for records created during normal operation. Payments on test contributions and incorrect imports are two use cases where it might make sense.

civicrm_api3('payment', 'delete', array( 'sequential' => 1, 'payment_id' => 12)
function _civicrm_api3_payment_update_spec(&$params) {
  $params['civicrm_financial_trxn_id']['api.required'] = TRUE; // NB: can also be referred to as payment_id
}
Étiquette
  • Aucun

Creative Commons License
Except where otherwise noted, content on this site is licensed under a Creative Commons Attribution-Share Alike 3.0 United States Licence.