Skip to main content

Integrating Your Gift Card Plugin with WeeConnectPay

Learn how to integrate your WooCommerce gift card plugin with WeeConnectPay to ensure gift cards are reflected in Clover orders.

Updated over 2 months ago

Overview

This guide explains how to integrate custom payment methods (like gift cards) with WeeConnectPay's WooCommerce integration. These custom tenders are tracked within WooCommerce orders and properly reflected in Clover transactions.

⚠️ IMPORTANT: Plugin Loading Order

Due to WordPress plugin loading order, you must implement your custom tender callback carefully to avoid dependency issues. Here's the recommended implementation pattern:

Create your callback file (e.g., my-custom-tender-callback.php):
​

<?php
/**
 * Custom Tender Callbacks
 */

// First, try to load the interface directly
if (!interface_exists('\WeeConnectPay\WordPress\Plugin\includes\CustomTenderInterface')) {
    if (!defined('ABSPATH')) {
        return;
    }
    $interface_path = WP_PLUGIN_DIR . '/weeconnectpay/includes/CustomTenderInterface.php';
    if (file_exists($interface_path)) {
        require_once $interface_path;
    }
}

// Now implement the interface if it exists
if (interface_exists('\WeeConnectPay\WordPress\Plugin\includes\CustomTenderInterface')) {
    if (!class_exists('MyCustomTenderCallback')) {
        class MyCustomTenderCallback implements \WeeConnectPay\WordPress\Plugin\includes\CustomTenderInterface
        {
            public static function chargeCreationCallback(array $data): array
            {
                // Handle successful charge
                error_log('Custom tender charge created: ' . json_encode($data));
                return $data;
            }

            public static function chargeRefundCallback(array $data): array
            {
                // Handle successful refund
                error_log('Custom tender refunded: ' . json_encode($data));
                return $data;
            }
        }
    }
}

🔧 Prerequisites

  1. WooCommerce must be active

  2. WeeConnectPay plugin must be installed and configured

  3. A Clover merchant account with custom tenders configured

Note: We plan on managing custom tenders on the merchant account on our end in the future. For the time being, they need to be created on the merchant account before using them through the plugin or the payment with the custom tender will fail.

📦 Namespace Information

The key classes for custom tender integration are in the following namespaces:

  1. CustomTenderInterface

\WeeConnectPay\WordPress\Plugin\includes\CustomTenderInterface

  1. WeeConnectPayCustomTenderHelper

\WeeConnectPay\WordPress\Plugin\includes\WeeConnectPayCustomTenderHelper

You can use these classes either with their fully qualified names or with use statements, as long as you implement proper existence checks as shown in the implementation pattern above.

🛠️ Helper Functions Reference

1. Add a Custom Tender to a WooCommerce Order

Function: WeeConnectPayCustomTenderHelper::setCustomTender

Purpose: Registers a custom tender's details on the order.

Example usage:

Usage Example:

try {
    $tender = WeeConnectPayCustomTenderHelper::setCustomTender(
        $order,                    // WooCommerce order object
        'My Custom Tender',        // Label in Clover
        2500,                      // Amount in cents ($25.00)
        MyCustomTenderCallback::class  // Your callback class
    );
    
    // Store the tender ID for later use
    $tenderId = $tender['id'];
    
} catch (InvalidArgumentException $e) {
    error_log('Error adding custom tender: ' . $e->getMessage());
}

Parameters:

  • $order: WooCommerce order object (WC_Order)

  • $customTenderLabel: Label matching your Clover custom tender (string)

  • $amountInCents: Amount in cents (integer)

  • $callbackClass: Your callback class name (string)

  • $uniqueId: Optional custom identifier (string|null)

Returns: Array containing tender details


​Exceptions:

  • Throws InvalidArgumentException if:

    • $customTenderLabel is an empty string.

    • $amountInCents is not a positive integer.

    • $callbackClass does not exist or does not implement CustomTenderInterface.

    • A custom tender with the same $uniqueId already exists in the order.

Returns: A pending custom tender. (Not yet processed by Clover)

When to Use: Call this function whenever a custom tender is applied to an order in your plugin, ensuring it is properly tracked and processed within the Clover system.

2. Remove a Pending Custom Tender from an Order

Function: WeeConnectPayCustomTenderHelper::deletePendingCustomTender

Purpose: Removes a pending custom tender from the order before payment is processed. If the tender has already been paid, the refund function must be used instead.

Usage Example:

try {
    WeeConnectPayCustomTenderHelper::deletePendingCustomTender(
        $order,         // WooCommerce order object
        $tenderId       // Unique tender identifier
    );
} catch (InvalidArgumentException $e) {
    error_log('Error deleting custom tender: ' . $e->getMessage());
}

Parameters:

  • $order: The WooCommerce order object (WC_Order).

  • $tenderId: Unique identifier of the custom tender to be deleted (string).

Exceptions:

Throws InvalidArgumentException if:

  • A custom tender with the provided $tenderId is not found.

  • The custom tender has already been refunded.

  • The custom tender has already processed a transaction (use the refund function instead).

When to Use: Call this function before payment has been processed if you need to remove a pending custom tender. Once payment is made, the refund function must be used instead.

Returns: void (nothing)

3. Refund a Custom Tender Charge

Function: WeeConnectPayCustomTenderHelper::refundCustomTender

Purpose:
Refunds a processed custom tender charge. This function verifies that the custom tender is refundable (i.e. its status is "success" and it has an associated charge_id), then sends a refund request. Upon a successful refund, it updates the custom tender’s status to "refunded" and returns the API response details.

Usage Example:

try {
    $refundResponse = WeeConnectPayCustomTenderHelper::refundCustomTender(
        $order,     // WooCommerce order object
        $tenderId   // Unique tender identifier
    );
    // Process refund response if needed
} catch (Exception $e) {
    error_log('Error refunding custom tender: ' . $e->getMessage());
}

Parameters:

  • $order: The WooCommerce order object (WC_Order).

  • $tenderId: The unique identifier of the custom tender to be refunded (string).

Exceptions:
Throws an exception if:

  • The custom tender with the specified $tenderId is not found.

  • The custom tender is not in a refundable state (its status is not "success" or it lacks a valid charge_id).

  • The refund API request fails or the API response does not pass validation.

Returns:
An array containing the API response details from Clover (e.g., refund ID, amount, status, and related metadata) if the refund is successful.

🚨 Common Issues and Solutions

1. "Class not found" errors

Solution: Use the provided interface loading pattern shown at the start of this guide.

2. Custom tender not appearing in Clover

Solutions:

  • Verify your Clover merchant configuration

  • Ensure tender label matches exactly

  • Check error logs for issues

3. Refund failures

Solutions:

  • Verify tender status is 'success'

  • Ensure charge_id exists

  • Review Clover API response

📋 Best Practices

1. Error Handling

  1. Always use try-catch blocks

  2. Log errors appropriately

  3. Provide user-friendly messages

2. Data Validation

  1. Sanitize all inputs

  2. Verify amounts and currencies

  3. Check tender status before operations

3. Security

  1. Use WordPress nonces when appropriate

  2. Validate user capabilities

  3. Escape output

🧪 Testing Your Integration

Basic Integration Test

  1. Implement the interface using the provided pattern

  2. Add a test custom tender

  3. Verify it appears in WooCommerce order meta

  4. Complete the order

  5. Verify it appears in Clover

Refund Flow Test

  1. Process a test order with your custom tender

  2. Attempt a refund

  3. Verify refund status in both WooCommerce and Clover

🆘 Need Help?

If you encounter issues, please contact our support team with:

  1. Integration Website URL

  2. Clover merchant name/UUID

  3. WooCommerce order ID

  4. Error logs

  5. Steps to reproduce the issue

We'll be happy to assist you further!

Related Articles
API Quick-start Documentation
Using Credit Card Charge Metadata for Custom Integrations in WeeConnectPay
Did this answer your question?