CiviCRM Community Forums (archive)

Hi,

I have only used the pledge payment api for the situation where the original payment plan is adhered to - you are dealing with a situation where it changes 'on-the-fly'?

I found a solution to my issue, although it required modifying the implementation for the PledgePayment API.

Step 1)  I updated the PledgePayment API function called "civicrm_api3_pledge_payment_create"

I removed the 'contribution_id' from the list of mandatory fields as follows:

 //  civicrm_apto i3_verify_mandatory($params,null,array('pledge_id','status_id', 'contribution_id'));
   
civicrm_api3_verify_mandatory($params,null,array('pledge_id','status_id'));

Step 2)

I updated my batch script so that immediately after applying a completed contribution as a completed pledge payment, I check how much money is still owed toward the pledge.   If there is any money still owed, I call the API to create a new pledge payment, this time the status is "pending" and the contribution id is null.

Seems like "step 2" should be internal to the API.  If a developer does not do step 2, there is a good chance of ending up with a pledge in an invalid condition. ( ie money is owed against the pledge, yet the status is "completed" and there is no way to record the final payment. )

It makes sense to me to keep the api quite granular and not make lots of assumptions. For your use case of actual payment != scheduled amount, I think the following sequence make sense and would be good to support via the api:

1. Call pledge_payment_create w/ the pledge_id, contribution_id and actual payment amount (if different from scheduled amount). This results in completed pledge payment for actual amount paid. I think the api currently supports this step.

2. If you want to update the next payment to reflect remainder - call pledge_payment_create w/ id of next due pledge_payment. Pass update payment_amount, and do not pass contribution_id. This should update amount of next due payment only. This requires changing the api to make contribution_id NOT required as you've done.

2a. If you want to modify total pledge amount instead, then (hopefully) you can do that w/ the pledge api.

In general I also think it will be useful (and is consistent) to allow pledge_payment api to used to insert pledge payments. Currently this is not supported (based on my conversation w/ Eileen) since the api assumes that you are trying to make a payment against the "next / oldest pending" payment. I think Eileen is planning on chatting w/ api team about this issue.

When I call the PledgePayment API to create a new installment:  I pass the status parm to "pending", the "scheduled_amount" value as the the amount that I have previously calculated that is still owed on the pledge.

For example:

1) My batch script creates a pledge of $1,000. with one scheduled installment of $1,000.

(processes many records not related to this pledge)

2) The batch script finds a payment record of $100 for the previous pledge.  So I create a contribution, then call the create PledgePayment,passing in the contrib. id of this $100 contribution.

At this point the pledge looks like:

Total pledge amount: $1000,  paid so far: $100, balance: $900.    It contains one installment, that has the actual amount paid as "$100" and status as completed.  ( IMHO, this means the pledge is in an invalid condition. Money is owed, yet there is no way to record it and the pledge status wrongly shows as completed. )

3) Now I calculate the total pledge amount minus the amount paid  and set it to the variable "amount_due".   

If "amount_due" is more than zero, I call the the API for create "PledgePayment" again. This status is "pending", "scheduled_amount" = "amount_due" and contribution ID is empty.   

4) The script continues reading more records. If it encounters another record describing a payment for the same pledge,  then I repeat steps 2 and 3.

After processing the complete input file, The pledge of $1000 may have 4 payments of $100, a fifth payment of $150. So the pledge balance is "$450" and there are 5 completed payments as well as a single pending payment of $450 in the pledge payment list.

The problem with the data in the input file is that there is no schedule. The person paid basically arbitrary amounts in each payment against a certain obligation/pledge.     In some situations, the obligation is paid off in full over many payments. In other situations ( as I described in more detail) there is a balance due.   

The other possibility is that they end up paying more than the original obligation. In this case, I am still deciding if I should a) Adjust the pledge amount to the higher number or b) record the "extra" money as a contribution, but do not link it to the pledge.

My concern is that from a developers point of view, the pledge should act as a "container" for all the pledge payments. It does not make sense that I can arbitrarily manipulate the payments ( scheduled or completed) in a manor that creates a flawed pledge.  But maybe this issue is really related to the planned changes for the "CiviAccounts" project, where there is a cleaner structure for tracking what someone owes. 

Nah, this is a pretty special scenario - the pledge payments are created by the pledge API and ......  I won't go into it unless you REALLY want to get your head around it. It is different to the chaining / nesting concept.

You probably just want to focus on the syntax side of it per the new thread you started

Yep, we have PledgePayment create & pledge create. Pledge creates the pledge and the pledge payments and pledgePayment updates the pledge payments - except in extremely rare use cases it now needs to create them too - clear as mud?

Hi,

The API is a thin wrapper around the DAO/BAO
   $dao = CRM_Pledge_BAO_Payment::add( $paymentParams );

in that case it has an extra line that should do the trick:

     CRM_Pledge_BAO_Payment::updatePledgePaymentStatus( $params['pledge_id']);

One of the issue we encountered in the API is that some features that should have been in the BAO was in the Form class, so we had to refactor or duplicate code between the form and the API.

In general when developing it would be great to check if it's an UI related task (in that case that's in the form) or something that is about the business model and should be shared between the UI and the API (and be in the BAO).

Will mail the planning list next time I stumble upon one.

X+