Sanity Check Request - A Spin on Split Payment Implementation

[electricbamboo]

Hey guys,

No need for anyone to actually write anything code-wise, I'm just looking for someone to tell me "hey, that approach sounds reasonable" or "buddy, that's a fools-errand."

I have a client who is looking to implement something more or less in the ballpark of the attached screenshot (faithraiser_add_info_target). The idea is that in the payment flow the donor would have the option to give a percentage of the donation, or even a custom value donation, to the facilitating website (i.e. the website collecting the donations). My research wound me to the class-give-payment.php file (https://github.com/impress-org/givewp/blob/develop/includes/payments/class-give-payment.php) which in turn led me to the give_setup_payment hook.

I was thinking I could create a function that accepts the $this payment object as a parameter AND could access the new donate-to-the-site field(s) (i.e. are custom fields added to $payment or to some other variable?) and then hook it into the give_setup_payment hook. The function would copy most of the $this payment object into a new payment object, change the necessary fields (which I would want to confirm with you guys), and then process both simultaneously by adding it to the Give_Cache with a new ID.

I gather I would probably need to make the following changes to the payment objects:
$this (original payment object):

1. Deduct the site donation from the total and subtotal amounts

$siteDonation (new payment object):

1. Set ID and _ID
   $siteDonation->ID = absint( $payment_id );
   $siteDonation->_ID = absint( $payment_id );

2. Set donation info
   $siteDonation ->total = $this->setup_total();
   $siteDonation ->subtotal = $this->setup_subtotal();
   $siteDonation ->currency = $this->setup_currency();

3. Setup gateway info
   $siteDonation ->gateway = $this->setup_gateway();
   $siteDonation ->transaction_id = $this->setup_transaction_id();

4. Set Other Identifiers to avoid conflicts with the original payment (I'm even less sure about these):
   $siteDonation ->form_title = $this->setup_form_title();
   $siteDonation ->form_id = $this->setup_form_id();
   $siteDonation ->price_id = $this->setup_price_id();
   $siteDonation ->key = $this->setup_payment_key();
   $siteDonation ->number = $this->setup_payment_number();

5. Add the $siteDonation object to the Give_Cache:
   Give_Cache::set_group( $siteDonation ->ID, get_object_vars( $siteDonation ), 'give-donations' );

Am I close? Thank you so much for reviewing this and pointing me in the right direction. Again, I'm not looking for anyone to write code for me. I just need to know 1) Can I win with this trajectory? and 2) How would I go about accessing the custom fields added either through Form Field Manager or elsewhere (I'm assuming this gets rolled into a 'meta' field in the $payment object, but I could be way off there). Thanks for the cairns :)

Kind Regards,

Avery

Also, the screenshot has the donor fields in the info part of the flow. I could move this to the Give Amount part of the flow if that would be easier.

[jonwaldstein]

@electricbamboo what gateway(s) are you expecting this implementation to work with?

[electricbamboo]

They'd like to get this working with Authorize.net.

Any chance we'd be able to do this within a single hit on the payment gateway? Or is it 1 transaction = 1 hit? Not sure if you can 'bundle' transactions to be processed when delivering data to the gateway like this.

And thanks for the super fast response!! That was amazing :)

[jonwaldstein]

Okay, how are they looking to differentiate the 2 donations? Would you be using something like our Funds add-on to send the "siteDonation" to a different fund or something? Also would the "siteDonation" be added to the same authorize account?

Ultimately what it sounds like your trying to do is process 2 donations during 1 form request - which is not currently possible out-of-the-box. I have a few options in mind that might work but would definitely require coding.

Your current direction would be tricky because you would still need to trigger the gateway to process the additional payment. In which case it might be easier to actually extend the gateway and add the logic you need (to process 2 donations). After learning more about the expectations from the questions above I can point you in a direction.

[electricbamboo]

Okay, how are they looking to differentiate the 2 donations?
Clarified with the client - they actually want the option to donate to the site to appear below the Choose Amount fields (earlier in the flow than in my screenshot). Think: a slider or checkbox ("Would you like to give to the site?") causes a dropdown to appear with a list of percentages and 'Custom Value' - if 'Custom Value' is selected, a text field appears. They want to only hit the payment gateway once if at all possible.

Would you be using something like our Funds add-on to send the "siteDonation" to a different fund or something?
Using the Funds add-on is definitely an option if my current approach requires hitting the gateway twice (and therefore no-go). I imagine I would have to wire up a few fields on the "Donation Amount" (in the multi-step flow) to capture the site-donation, and then use Funds to re-assign that percentage (or custom value) to another Fund (Support the Site Fund) after-the-fact. Maybe this is the easiest approach?

Also would the "siteDonation" be added to the same authorize account?
Yes.

_Ultimately what it sounds like your trying to do is process 2 donations during 1 form request - which is not currently possible out-of-the-box. _
This is what I had thought originally. After getting some clarification, I think it's more accurate to say I want to route funds to two different places during 1 form request.

I have a few options in mind that might work but would definitely require coding.
This is what I figured. I'm not opposed to that at all :)

Is it possible to do this only hitting the payment gateway once?

[jonwaldstein]

Okay so it sounds like you want authorize.net to handle the payment once, but have GiveWP record the donations as 2 records.

Option 1: Fee Recovery Add-on

• Use our fee-recovery add-on to handle the custom amount & calculation.
  This would probably require a little customization for your use cases (ie. updating donor-facing text, amount field, etc.). The nice part about this add-on is it does a lot of the leg work for you in terms of the calculation and connecting to GiveWP using donation meta.
• Use the GiveWP action give_update_payment_status to listen for the the completed ('publish') status and split up the donation record in GiveWP. The advantage of using the fee recovery add-on would be having first-class access to that _give_fee_amount from the donation meta and our Donation model ($donation->feeAmountRecovered). At that point I would use our Donation model to create a new donation using the fee amount and update the original donation to remove the fee amount. From here you can also assign the donation(s) to different funds.

Option 2: Custom Field

• Use our fields api to create the custom field and store the value in donation meta. You would have to calculate updating the total amount on the front-end and/or use the 'give_donation_total' filter and update the total amount for the gateway to use in combination with something like $_POST['siteDonation'].
• Use the GiveWP action give_update_payment_status to listen for the the completed ('publish') status and split up the donation record in GiveWP. The rest would be very similar to the above solution except you would need to use your custom meta ('siteDonation') instead of the fee recovery one.

[electricbamboo]

Jon,

Thank you SO much! This is exactly what I needed. I was able to clarify with the client and they're wanting to do this:

Which, from where I'm standing, looks 100% compatible with either approach. I imagine there's a static object that gets created at the beginning of the flow and then gets modified as it goes. The proposed change would only augment 'where' in the flow the changes occur , but before it's actually submitted. Am I tracking correctly here?

[electricbamboo]

Also, feel free to mark that last response as the answer :)
I think we're good to go!

[jonwaldstein]

Cool, yeah when the form submits we create a pending Donation model record in the database. That model instance gets passed along to the gateway who processes the payment using the total donation amount. Depending on how the gateway works, they will eventually mark the donation as complete and update the transaction ID and any other meta they need.

So, making sure the total donation amount is calculated correctly will allow the gateway to process the full payment. From there you can hook into the status change to listen for that completed status and modify the donation record in the database (along with creating a new one)

[electricbamboo]

Awesome. Thank you so much for your quick responses and great answers! I'll be bookmarking this page for the near future...

[electricbamboo]

Hey Jon,

Here are the relevant pieces of what I have going so far. The form loads and I'm able to drop in right at give_update_payment_status:

$siteSupport = [
					'status' => 'publish',
					'gatewayId' => $donation['_give_payment_gateway'][0],
					'amount' => Money::fromDecimal($frOrigFee, $frOrigCurrency),  //blows up here
					'donorId' => $donation['_give_payment_donor_id'][0],
					'firstName' => $donation['_give_donor_billing_first_name'][0],
					'lastName' => $donation['_give_donor_billing_last_name'][0],
					'email' => $donation['_give_payment_donor_email'][0],
					'formId' => $donation['_give_payment_form_id'][0],
					'formTitle' => $donation['_give_payment_form_title'][0],
					'billingAddress' => BillingAddress::fromArray([
						'country' => $frOrigAddress['country'],
						'city' => $frOrigAddress['city'],
						'state' => $frOrigAddress['state'],
						'zip' => $frOrigAddress['postalCode'],
						'address1' => $frOrigAddress['line1'],
						'address2' => $frOrigAddress['line2'],
					]),
					'levelId' => $donation['_give_payment_price_id'][0],
					'anonymous' => $donation['_give_anonymous_donation'][0],
					'company' => $frOrigCompany
				];
				

				//Now we need to deduct the donation from the original so we can process it separately.
				$donation['_give_payment_total'][0] = $frOrigTotal - $frOrigFee;
				$donation['_give_fee_amount'][0] = 0.00;
				$give->donations->update($donation);

				//Finally, we can insert the siteSupport donation
				$give->donations->insert($siteSupport);

Originally, I had '$siteSupport = new Donation([.....' , but Donation isn't available in the function and throws an error. I suppose I could hardcode a require_once statement and reference the Donation Model (as well as Money and BillingAddress), but I know that's a terrible idea. I searched for all instances where you guys are using "$give->" to see if there was a "$give->ValueObjects" kind of object so I could do $give->value_objects->donation->new(...). I saw in class-give-payment.php where the $donation object is created from a fairly simple array:

$donation = [
			'name'     => $donation->post_title,
			'id'       => $donation->ID,
			'price'    => round( $total, give_get_price_decimals( $this->ID ) ),
			'subtotal' => round( $total, give_get_price_decimals( $this->ID ) ),
			'price_id' => $args['price_id'],
			'action'   => 'add',
			'options'  => $options,
		];

So I dropped the "new Donation..." only to run into the same issue for the Money ValueObject. I suppose I could just use the same mechanics (round($total...etc)) you guys did there, but the fact that the Money::fromDecimal function takes in the currency as well implies there's some formatting going on I'd rather not try to work around. Is there a better way to be accessing these objects (or some documentation that I obviously need to read)?

Questions

1. Is there a way I can get to the Donation, Money, or BillingAddress objects? (Do I even need them?)
2. I'm assuming I will need to create another function to pass in the custom values I get from my dropdowns and hook into the 'give_pre_setup_payment' hook so I can have the fee recovery plugin do the actual calculation for me. Is that correct?
3. Am I still on the right track here?

Thanks so much - I sincerely appreciate your guidance.

Kind Regards,

Avery

[electricbamboo]

Thank you so much Jon. I sincerely appreciate your guidance on this. Warm regards :)

[electricbamboo]

I figured out the checkbox issue - I ended up re-activating the Fee Recovery plugin, copied down the fieldset for the checkbox code, and am adding it in as HTML instead. You've given me plenty to go on here! Have an awesome day!!

[electricbamboo]

Hey @jonwaldstein I think I found something possibly worthy of the documentation pile.
I did my best to find a cleaner method to access the updateDonationFund function in GiveFunds\Repositories\Revenue, but for the life of me couldn't figure out where a RevenueRepository was being exposed. A sampling of my head hitting the wall can be found here:

In the end, I just copied (stole?) the updateDonationFund code and moved on (it works). Just don't change the table name or column order anytime soon ;)

Hope your weekend is off to a great start :)

[electricbamboo]

Annndddddd....do I feel silly? Much yes. So wow.

$GiveFundsRevenue = new GiveFunds\Repositories\Revenue();
$GiveFundsRevenue->updateDonationFund( $siteDonation->id, $fundID );

[jonwaldstein]

nice!

[electricbamboo]

Thanks :)

If you have a moment, I'm trying to implement something and, while I'm experiencing marginal success, I'd like to make sure I'm not missing something obvious. Take a look at the following screenshot:

The idea is to give the admin the option to make the 'Add Donation to Site Support' choice for the donor, or pass the decision off on to them. So far, I've got the admin settings echoing to the front-end where I've got jQuery working to show/hide fields as appropriate, do the calculations, and save things to the donation meta. The issue is that I'm having trouble keeping the javascript for legacy forms from interfering with the javascript for the iframe-based forms as it causes some of the code to run twice (which is bad if you're, say, calculating a percentage of a donation amount and updating the donation amount field in javascript).

I did see this: https://givewp.com/documentation/developers/conditionally-load-give-styles-and-scripts/

But I don't need to gut the whole GiveWP javascript engine - just tweak a small part. I borrowed the piece of using the wp_print_scripts hook and that sort of worked but the legacy js wasn't registering when it was supposed to and the multi-form/sequoia wasn't deregistering when it was supposed to. It just feels like it should work.

function enqueue_scripts() {
// Get the global $post object and identify which form is currently being loaded
global $post;
$form_type = Give\Helpers\Form\Template::getActiveID();
		
    //Deregister unnecessary scripts and load appropriate js for Legacy Forms
    if( is_a( $post, 'WP_Post' ) && $form_type == "legacy" ) {		
	    wp_deregister_script( $this->plugin_name . 'classic-form');
	    wp_dequeue_script($this->plugin_name . 'classic-form');
	    wp_deregister_script( $this->plugin_name . 'multi-form');
	    wp_dequeue_script($this->plugin_name . 'multi-form');
    
	    wp_register_script( $this->plugin_name . 'legacy-form', plugin_dir_url( __FILE__ ) . 'js/faithraiser-site-support-public-legacy-form.js', array( 'jquery' ), $this->version, true );
	    wp_enqueue_script($this->plugin_name . 'legacy-form');
    }

    //Deregister unnecessary scripts and load appropriate js for Classic Forms
    if( is_a( $post, 'WP_Post' ) && $form_type == "classic" ) {		
	    wp_deregister_script( $this->plugin_name . 'legacy-form');
	    wp_dequeue_script($this->plugin_name . 'legacy-form');
	    wp_deregister_script( $this->plugin_name . 'multi-form');
	    wp_dequeue_script($this->plugin_name . 'multi-form');
    
	    wp_register_script( $this->plugin_name . 'classic-form', plugin_dir_url( __FILE__ ) . 'js/faithraiser-site-support-public-classic-form.js', array( 'jquery' ), $this->version, true );
	    wp_enqueue_script($this->plugin_name . 'classic-form');
    }

    //Deregister unnecessary scripts and load appropriate js for the Multi-Step Forms,
    //sequoia is the GiveWP internal name for iframe-based forms
    if( is_a( $post, 'WP_Post' ) && $form_type == "sequoia" ) {
	   wp_deregister_script( $this->plugin_name . 'legacy-form');	
	    wp_dequeue_script($this->plugin_name . 'legacy-form');
	    wp_deregister_script( $this->plugin_name . 'classic-form');
	    wp_dequeue_script($this->plugin_name . 'classic-form');
    
	    wp_register_script( $this->plugin_name . 'multi-form', plugin_dir_url( __FILE__ ) . 'js/faithraiser-site-support-public-multi-form.js', array( 'jquery' ), $this->version, true );
	    wp_enqueue_script($this->plugin_name . 'multi-form');
    }
}
add_action( 'wp_print_scripts', $plugin_public, 'enqueue_scripts',999 );

But as I alluded to above, that only worked for the iframe-based forms and stopped working altogether for the legacy form. At that point, the solution was to put everything into one js file and use jQuery('iframe[name="give-embed-form"]').contents().find('') to sort out whether or not I was in a legacy form or a sequoia one (which led to the aforementioned 'code running twice' issue).

Question 1) ALL of the donor-selected values are being saved to the donation meta so I could be doing all of this on the server side. Should I be? Does it matter?

Question 2) Is my thinking right concerning the js approach of putting everything in one file and abandoning trying to manage the registration and deregistration manually? Admittedly, putting all the js code in one place cleans up both the client and server side, but it means there's unused code in places and man using jQuery('iframe[name="give-embed-form"]').contents().find('') feels kind of hacky.

I attached my js (js_update.txt) if you want to take a look (if not, totally cool - like I said, I've got this mostly working so I understand if you don't have time).

Thanks for any input, thoughts, or direction,

Avery

js_update.txt

[jonwaldstein]

Hey @electricbamboo

Welcome back 👋

So what you have working is probably limited to (what we call) our legacy forms (pre GiveWP 3.0). Forms created using our visual form builder is a whole new rendering system that is actually easier to extend - being a react framework that uses hooks. So in terms of future proof, there will be some extra work to have it work on both types of forms. However, we are here to help 🧙

I would love to learn more about how you are using GiveWP and ways we can improve the developer experience. If you are open to chatting more, please email me at [email protected] and we can setup a call together 😄

[electricbamboo]

Hey Jon!

Thanks for getting back with me so fast! I'll send you an email here to set up that call :)

As an aside, how much longer should the client expect those 'legacy' forms to work? Additionally, I could see my client asking 'well, how do I know that they won't release GiveWP 4.0 and we're right back here in a year?' I can imagine what your answers might be (given the flexibility of using react), but I'd rather not guess ;)

You guys are awesome 😎

Kind Regards,

Avery

[jonwaldstein]

Avery, looking forward to your email!

We plan to support our legacy forms for a while. Eventually our forms using the form builder will become the default GiveWP forms but the legacy ones will still work (backwards compatible). It's still too early to say what specific version we will stop supporting those but rest assure, we have all our customers in mind and want every transition to go as smooth as possible - so expect plenty of early notice when those decisions are made 😄

[electricbamboo]

Hey Jon! I just sent you an email :)
Any thoughts on a tool to pull (convert) older legacy forms into the light of 3.0?

[jonwaldstein]

@electricbamboo thanks, looking forward to it!

Yes on the form migration we have a way built-in (still working on specific add-on compatibility):
https://givewp.com/documentation/core/give-forms/migrate-donation-forms-to-the-visual-form-builder/