Custom gateway recurring donations. Email notifications.

[joshAppDev]

I have written a custom gateway add-on, following the methodology of givewp-example-gateway. One-time payments work as expected. I am implementing recurring payments using a SubscriptionModule class.

The gateway handles recurring payments on its own. I use GiveWP to set up the subscription, and the recurring payments will continue to be made without intervention by GiveWP. The gateway does notify my add-on when a recurring payment is made, using a webhook/callback. Same thing for when the recurring payment fails or is modified externally.

Question 1: What is the recommended way of creating the donation record when I am notified by the gateway of a new recurring payment?

This is roughly what I have now. Is there a better way?

$initialDonation = $subscription->initialDonation();
$newDonation = new Donation([
    'subscriptionId' => $subscription->id,
    'type' => DonationType::RENEWAL(),
    'gatewayId' => MY_GATEWAY_ID,
    // Clone the other properties from initial donation
    'formId' => $initialDonation->formId,
    'formTitle' => $initialDonation->formTitle,
    ...
]);
$newDonation->gatewayTransactionId = 'NEW_TRANSACTION_ID';
$newDonation->amount = Money::fromDecimal('NEW_AMOUNT', $subscription->getCurrency());
$newDonation->status = DonationStatus::COMPLETE();
$newDonation->save();

$subscription->bumpRenewalDate()

Question 2: Do I need to manually trigger the user email notifications?

For successful and failed payments, is it enough to just create the new Donation object, assign the status, and save? Or should I call give_email_donation_receipt() or something like that?

How do I trigger email notifications for subscriptions that are cancelled or modified externally? Is it enough to just update the status on the Subscription object and save?

Question 3: Does my GiveWP know that the recurring payments are initiated externally?

Do I need to worry about GiveWP trying to initiate payments by itself when the renewal interval comes around? Is this something I need to specify somehow?

[jonwaldstein]

Hey @joshAppDev!

Thanks for reaching out, glad to hear you are making progress on a custom gateway solution!

1. What you have roughly looks like the right approach. With webhooks we receive the gateway data typically using the built in $routeMethods option in the gateway api - then find the subscription using the gateway transaction ID and create a new donation record like you are doing.
2. You do not need to manually trigger email notifications as the framework will typically listen for donation status changes and dispatch the appropriate listeners like email notifications.
3. What do you mean by GiveWP trying to initiate payments by itself?

[joshAppDev]

Thanks for the reply and confirmation. I'll try to elaborate on my thought process regarding question 3.

My general understanding is that recurring payments can be initiated either externally by the user/gateway, or internally by the merchant (here that would be GiveWP). The gateway that I am working with executes the recurring payments automatically, and then notifies the merchant. I see this as an externally initiated payment. On the other hand, an internally initiated payment would be where the billing details were saved by the merchant, and the merchant uses that to submit a new charge to the gateway every month, rather than just waiting to be notified.

So my custom gateway add-on handles external recurring payments. I want to know whether GiveWP will try to renew the subscription internally.

[jonwaldstein]

Thanks for the clarification!

To answer your question - no, GiveWP will not try to renew the subscription internally. The subscriptions are relied on by the gateway (externally) to communicate to GiveWP that a renewal needs to be created.

[joshAppDev]

Do I need to invoke the give_recurring_add_subscription_payment hook? What about the give_recurring_record_payment hook?