Error Logging for Gift Card Failure Due to session being cleared

[m-muhsin]

Enhance gift card error logging with debug_log() checks, message prefixes, and source context, and add logging for missing payment tokens.

All Submissions:

• Does your code follow the WooCommerce Sniffs variant of WordPress coding standards?
• Have you written new tests for your changes, as applicable?
• Have you successfully run tests with your changes locally?
• Will this change require new documentation or changes to existing documentation?

---

Changes proposed in this Pull Request:

When a gift card application fails due to a missing payment token in the session, users see the error message "There was an error while applying the gift card" but no log entry is created. This makes it difficult for store owners and developers to diagnose why gift cards aren't working.

This PR adds error logging when:

The woocommerce_square_gift_card_payment_token is missing from the session
The Square API returns errors (improved existing logging with source context)
Both logging cases now:

• Respect the Debug Mode setting via $this->debug_log()
• Include a descriptive source context (woocommerce-square-gift-card) for easy filtering in WooCommerce logs
• Prefix error messages with "Gift card error:" for clarity

Closes #38.
Closes https://linear.app/a8c/issue/SQUARE-83/gift-card-failure-not-logged

Steps to test the changes in this Pull Request:

⚠️ Note: The error logging code paths are only executed in Production mode, not Sandbox mode. Sandbox mode uses hardcoded balance values and bypasses the API calls where these errors would occur. Full testing requires a Production Square account.

1. Enable Debug Mode in WooCommerce → Settings → Payments → Square → Gift Cards (set to "Save to Log")
2. Ensure Square Credit Card gateway and Gift Cards are enabled
3. Add a product to cart and proceed to checkout
4. Apply a valid Square gift card
5. Clear the session token by adding this temporary code to your theme's functions.php:

add_action( 'init', function() {
    if ( isset( $_GET['clear_gc_token'] ) && $_GET['clear_gc_token'] === '1' ) {
        if ( WC()->session ) {
            WC()->session->set( 'woocommerce_square_gift_card_payment_token', null );
        }
        wp_die( 'Gift card token cleared!' );
    }
});

6. Visit yoursite.com/?clear_gc_token=1 to clear the token
7. Return to checkout - the gift card form should reset
8. Check WooCommerce → Status → Logs for a woocommerce-square-gift-card-* log file
9. Verify the log contains: Gift card error: Payment token (woocommerce_square_gift_card_payment_token) is missing from session.

Changelog entry

Add - Error logging when gift card application fails due to missing session token or Square API errors.

[iamdharmesh]

Thanks for the PR @m-muhsin. Added one minor note. Could you please help to check once?

[qasumitbagthariya]

QA Update ✅

---

I have verified this PR in the fix/sqr-38 branch, which has been fixed and is functioning as intended.

I tested the following on this branch:

Screen.Recording.2025-12-15.at.2.03.11.PM.mov

Testing Environment

Details

• WordPress: 6.9
• Theme: Storefront 4.6.2
• Theme: Twenty Twenty-Five 1.4
• WooCommerce - 10.4.0
• PHP: 8.0.30
• Web Server: Nginx 1.20.2
• Browser: Chrome
• OS: macOS 15.2
• Branch: fix/sqr-38

Steps to Test- As mentioned in the PR description.
Test Results - It is working as expected.
Functional Demo / Screencast -
Special Notes - Ready for UAT
Testing Document status:
Cases related to this Issue/PR are added to the Critical Flow Wiki pages:

• Yes
• Not Required/Applicable for this PR

---