Suma Woo Emails

Location: web/app/plugins/suma-woo-emails/ Author: Rhino Group Plugin Header: Plugin Name: Suma Woo Emails

---

Overview

The suma-woo-emails plugin registers 6 custom WooCommerce email types that cover the specific order lifecycle events of a precious metals store — events that the default WooCommerce email set does not support.

All email classes extend the standard WC_Email class and integrate fully with WooCommerce's email management system (WooCommerce → Settings → Emails).

---

File Structure

suma-woo-emails/
├── suma-woo-emails.php          ← Main plugin file / bootstrap
├── emails/
│   ├── class-wc-customer-pending-payment-order.php
│   ├── class-wc-customer-cancelled-for-fraud-order.php
│   ├── class-wc-customer-cancelled-bwt-email.php
│   ├── class-wc-customer-bank-wire-complete-email.php
│   ├── class-wc-admin-vault-order.php
│   └── class-wc-admin-solana-pending-payment.php
└── templates/
    └── emails/
        ├── plain/                              ← Plain text versions
        │   ├── wc-customer-pending-payment-order.php
        │   ├── wc-customer-cancelled-for-fraud-order.php
        │   ├── wc-customer-cancelled-bwt-email.php
        │   ├── wc-customer-bank-wire-complete-email.php
        │   ├── wc-admin-vault-order.php
        │   └── wc-admin-solana-pending-payment.php
        ├── wc-customer-pending-payment-order.php
        ├── wc-customer-cancelled-for-fraud-order.php
        ├── wc-customer-cancelled-bwt-email.php
        ├── wc-customer-bank-wire-complete-email.php
        ├── wc-admin-vault-order.php
        └── wc-admin-solana-pending-payment.php

---

Main Plugin Class: Custom_WC_Email

File: suma-woo-emails.php

This class acts as the plugin orchestrator. It:

1. Registers all 6 custom email classes with WooCommerce via the woocommerce_email_classes hook
2. Hooks into order status changes to trigger the appropriate emails
3. Triggers bank wire complete emails on the standard woocommerce_order_status_processing hook

class Custom_WC_Email {
    public function __construct() {
        add_filter( 'woocommerce_email_classes', [ $this, 'register_email' ], 90 );
        add_action( 'woocommerce_thankyou', [ $this, 'send_notices' ], 50 );
        add_action( 'woocommerce_order_status_processing', [ $this, 'trigger_bank_wire_complete_email' ], 10 );
    }
}

---

Custom Email Classes

1. WC_Customer_Pending_Payment_Order

Property	Value
File	emails/class-wc-customer-pending-payment-order.php
Email ID	wc_customer_pending_payment_order
Title	"Pending Payment ACH to Customer"
Recipient	Customer
Trigger	Order status changes to wc-pending-ach
Payment methods	wc_itransact, scottsdale-ach-gateway

Purpose: Notifies the customer that their ACH bank transfer has been initiated and is pending processing. Includes instructions about expected timelines and what to expect.

---

2. WC_Customer_Cancelled_For_Fraud_Order

Property	Value
File	emails/class-wc-customer-cancelled-for-fraud-order.php
Recipient	Customer
Trigger	Order cancelled (Kount fraud decision: Decline)

Purpose: Notifies the customer their order was cancelled due to a security review. Email is intentionally vague about fraud detection to avoid giving fraudsters information.

caution

This email is triggered by the Kount ENS handler when a fraud decision returns "Decline". Do not trigger this manually without verifying the order was actually flagged by Kount.

---

3. WC_Customer_Cancelled_BWT_Email

Property	Value
File	emails/class-wc-customer-cancelled-bwt-email.php
Recipient	Customer
Trigger	Order status changed, cancellation for bank wire transfer orders

Purpose: Notifies the customer their bank wire transfer order was cancelled. May be triggered by admin when a bank wire is not received within the expected timeframe.

---

4. WC_Customer_Bank_Wire_Complete_Email

Property	Value
File	emails/class-wc-customer-bank-wire-complete-email.php
Recipient	Customer
Trigger	woocommerce_order_status_processing (only for bank wire orders)

Purpose: Confirms to the customer that their bank wire/ACH payment has been received and the order is now being processed.

The trigger_bank_wire_complete_email() method checks the order's payment method before sending — this email only fires for applicable gateway IDs.

---

5. WC_Admin_Vault_Order

Property	Value
File	emails/class-wc-admin-vault-order.php
Email ID	(admin-only)
Title	"Vault Notice to Admin"
Recipient	Store admin email
Trigger	Vault/tokenization order placed

Purpose: Notifies store administrators when an order involves vault storage (customer is storing metals at the Scottsdale Mint facility rather than taking physical delivery). Includes order details and vault instructions.

---

6. WC_Admin_Solana_Pending_Payment

Property	Value
File	emails/class-wc-admin-solana-pending-payment.php
Recipient	Store admin email
Trigger	Solana (SOL) cryptocurrency payment initiated

Purpose: Notifies admins when a Solana payment is pending blockchain confirmation. Solana can have variable confirmation times depending on network conditions.

---

WordPress Hooks

Hook	Method	Priority	Description
woocommerce_email_classes (filter)	register_email()	90	Registers all 6 custom email classes with WooCommerce
woocommerce_thankyou (action)	send_notices()	50	Fires on the thank you page to trigger relevant notices
woocommerce_order_status_processing (action)	trigger_bank_wire_complete_email()	10	Triggers bank wire complete email when order moves to processing
woocommerce_order_status_changed (action)	trigger() (in BWT email class)	10	Monitors all status changes for BWT cancellation

---

Email Templates

Each email has both HTML and plain text versions:

• HTML: templates/emails/{email-slug}.php
• Plain text: templates/emails/plain/{email-slug}.php

Templates use standard WooCommerce email template conventions and can be overridden by placing a copy in the active theme's woocommerce/emails/ directory.

---

WooCommerce Settings Integration

All 6 email types appear in WooCommerce → Settings → Emails and support the standard configuration options:

• Enable/Disable the email
• Set custom subject line
• Set custom email heading
• Set recipient(s) (for admin emails)
• Preview email template

---

Adding a New Custom Email

To add a new custom WooCommerce email:

1. Create emails/class-wc-{your-email-slug}.php extending WC_Email
2. Create templates/emails/{your-email-slug}.php (HTML template)
3. Create templates/emails/plain/{your-email-slug}.php (plain text template)
4. Register the class in Custom_WC_Email::register_email():

public function register_email( array $email_classes ) : array {
    $email_classes['WC_Your_New_Email'] = new WC_Your_New_Email();
    return $email_classes;
}

5. Add the trigger hook in the constructor or Custom_WC_Email