ASIM Giving Form

WordPress plugin for the ASIM donation form: one-time and monthly gifts through Stripe (Payment Element for card / bank, Express Checkout Element for Apple Pay / Google Pay / Link) and PayPal / Venmo through ASIM's own PayPal account (Stripe can't process PayPal for US businesses).

Setup

1. Keys. Upload the plugin zip (Plugins → Add New → Upload Plugin), activate it, and paste your Stripe keys under Settings → ASIM Giving (test keys while building).

   Optional: keys can instead live in wp-config.php, which takes precedence over the settings page:

   define( 'ASIM_GIVING_STRIPE_PUBLISHABLE_KEY', 'pk_test_...' );
   define( 'ASIM_GIVING_STRIPE_SECRET_KEY', 'sk_test_...' );
   define( 'ASIM_GIVING_STRIPE_WEBHOOK_SECRET', 'whsec_...' );

2. Payment methods. In Stripe → Settings → Payment methods, turn on Cards, ACH Direct Debit, Apple Pay, Google Pay (and Link if wanted). The form shows whatever is enabled there.

3. Webhook. In Stripe → Developers → Webhooks, add an endpoint (the settings page shows the exact URL):

   • URL: https://YOUR-SITE/wp-json/asim/v1/webhook
   • API version: 2025-03-31.basil (matches ASIM_Giving_Stripe::API_VERSION)
   • Events: payment_intent.succeeded, payment_intent.processing, payment_intent.payment_failed, invoice.paid, invoice.payment_failed, customer.subscription.deleted, charge.refunded

   Paste its signing secret into the settings page. Test and live mode each need their own endpoint.

4. Apple Pay. Register the site's domain under Stripe → Settings → Payment method domains.

5. PayPal (optional). At developer.paypal.com → Apps & Credentials, create a REST app (Sandbox first, then Live) and paste its Client ID and Secret under Settings → ASIM Giving → PayPal, with the matching environment. In the app's Webhooks section, add the URL and events the settings page lists, and paste the webhook's ID. The PayPal button appears once the Client ID and Secret are set.

   The "Monthly Gift" product and plan are created in PayPal on the first monthly PayPal gift; each subscription overrides the plan's price. Test with the sandbox personal account under Testing Tools → Sandbox accounts.

   Optional wp-config.php constants: ASIM_GIVING_PAYPAL_CLIENT_ID, ASIM_GIVING_PAYPAL_SECRET, ASIM_GIVING_PAYPAL_WEBHOOK_ID, ASIM_GIVING_PAYPAL_ENV (sandbox or live).

6. Ministry projects. Under Settings → ASIM Giving → Ministry projects, set each project's amount and its English / Russian title and description. Each shows as a fixed one-time gift button; the server only accepts a project gift at its configured amount. Gifts record the project's id (its English title, slugified) in metadata.project.

7. Spam protection. The form has a hidden honeypot field that only bots fill in, always on. For reCAPTCHA, paste a v2 Invisible site key and secret key under Settings → ASIM Giving → reCAPTCHA (or define ASIM_GIVING_RECAPTCHA_SITE_KEY / ASIM_GIVING_RECAPTCHA_SECRET_KEY). Every gift request is then checked with Google before anything is created in Stripe or PayPal. If Google can't be reached, or the secret key is wrong, gifts go through and the problem is written to the PHP error log.

8. Place the form. In Elementor, add a Shortcode widget with [asim_giving_form] (English by default; [asim_giving_form lang="ru"] to open in Russian). One form per page.

Local webhook testing

With the Stripe CLI:

stripe listen --forward-to https://YOUR-LOCAL-SITE/wp-json/asim/v1/webhook

Use the whsec_... it prints as the webhook secret while testing.

How a gift flows

1. The browser shows Stripe Elements with the expected amount (deferred intent: nothing is created in Stripe yet).
2. On submit, POST /wp-json/asim/v1/donate re-validates the amount, recomputes the covered fee, finds or creates the Stripe Customer, and creates a PaymentIntent (one-time) or Subscription (monthly).
3. The browser confirms the payment with Stripe. Bank (ACH) payments show a "processing" thank-you.
4. Stripe's webhook announces the outcome; the plugin turns it into a WordPress action.

Everything the form creates is tagged metadata.source = asim_giving_form, with the gift, fee, donor and consent details in metadata, so the Stripe dashboard is the record of every gift.

PayPal gifts go POST /paypal/start (creates an Order or Subscription) → the donor approves in PayPal's window → POST /paypal/confirm (captures the order). PayPal only carries a short custom_id, so the same details are kept in the asim_giving_paypal table, and PayPal's webhook raises the same events with processor = 'paypal' and PayPal's IDs in the payload's paypal block.

Mailchimp

Paste an API key and audience ID under Settings → ASIM Giving → Mailchimp (or define ASIM_GIVING_MAILCHIMP_API_KEY, ASIM_GIVING_MAILCHIMP_AUDIENCE_ID and ASIM_GIVING_MAILCHIMP_TAGS). Saving checks the connection. After each donation.succeeded, donors who agreed to email or SMS updates are added or updated in the audience (FNAME, LNAME, PHONE, language) and tagged, with Monthly donor added for monthly gifts and SMS consent for donors who agreed to texts. Mailchimp's member API can't set SMS status, so SMS consent contacts are imported into the SMS program from Mailchimp. SMS-only donors are added as transactional, not subscribed to email. The sync runs from WP-Cron and retries twice; failures go to the PHP error log.

Hooks

// Every event: donation.succeeded, donation.pending, donation.failed, donation.refunded,
// subscription.created, subscription.canceled
add_action( 'asim_giving_event', function ( $event, $donation ) { ... }, 10, 2 );

// Or one at a time
add_action( 'asim_giving_donation_succeeded', function ( $donation ) { ... } );

// Change amounts, minimums or fee rates (also sent to the browser)
add_filter( 'asim_giving_config', function ( $config ) { ... } );

// Read the visitor IP from a proxy header (Cloudflare etc.)
add_filter( 'asim_giving_client_ip', function ( $ip ) { ... } );

// Where Apple Pay sends monthly donors to manage their gift (defaults to the home page)
add_filter( 'asim_giving_manage_url', function ( $url ) { ... } );