Customization Guide

This guide shows you how to customize various aspects of the Paga con ZIGI plugin to fit your specific needs.

Extending the Gateway Class

The main payment gateway class Zigi_Payment_WC_Gateway extends WC_Payment_Gateway and can be customized by creating a child class.

Creating a Custom Gateway Extension

<?php
/**
 * Custom extension of ZIGI Payment Gateway
 */
class Custom_Zigi_Gateway extends Zigi_Payment_WC_Gateway
{
    public function __construct()
    {
        parent::__construct();
        
        // Override or add new properties
        $this->method_title = __('ZIGI Pro Payment', 'your-textdomain');
        $this->method_description = __('Enhanced ZIGI payment with custom features', 'your-textdomain');
        
        // Add custom hooks
        add_action('woocommerce_thankyou_' . $this->id, array($this, 'custom_thankyou_page'));
    }
    
    /**
     * Add custom fields to gateway settings
     */
    public function init_form_fields()
    {
        parent::init_form_fields();
        
        // Add custom field
        $this->form_fields['custom_message'] = array(
            'title'       => __('Custom Success Message', 'your-textdomain'),
            'type'        => 'textarea',
            'description' => __('Message shown after successful payment', 'your-textdomain'),
            'default'     => __('Thank you for your ZIGI payment!', 'your-textdomain'),
            'desc_tip'    => true,
        );
    }
    
    /**
     * Custom thank you page content
     */
    public function custom_thankyou_page($order_id)
    {
        $order = wc_get_order($order_id);
        $receipt_url = $order->get_meta('zigi-payment-qrcode', true);
        
        if (!empty($receipt_url)) {
            echo '<div class="zigi-receipt-confirmation">';
            echo '<h3>' . esc_html($this->get_option('custom_message')) . '</h3>';
            echo '<p>' . __('Your payment receipt has been received.', 'your-textdomain') . '</p>';
            echo '</div>';
        }
    }
}

// Register the custom gateway
add_filter('woocommerce_payment_gateways', 'add_custom_zigi_gateway');

function add_custom_zigi_gateway($gateways)
{
    $gateways[] = 'Custom_Zigi_Gateway';
    return $gateways;
}

When extending the gateway class, always call the parent constructor to ensure all default functionality is preserved.

Customize the payment popup’s look and behavior by modifying CSS and JavaScript.

Custom CSS Styling

add_action('wp_enqueue_scripts', 'custom_zigi_popup_styles', 20);

function custom_zigi_popup_styles()
{
    wp_enqueue_style(
        'custom-zigi-popup',
        get_stylesheet_directory_uri() . '/assets/css/custom-zigi.css',
        array('zigi_payment_qr'),
        '1.0.0'
    );
}

Custom JavaScript Behavior

add_action('wp_enqueue_scripts', 'custom_zigi_popup_scripts', 20);

function custom_zigi_popup_scripts()
{
    wp_enqueue_script(
        'custom-zigi-popup',
        get_stylesheet_directory_uri() . '/assets/js/custom-zigi.js',
        array('jquery', 'zigi_payment_qr'),
        '1.0.0',
        true
    );
    
    // Pass custom data to JavaScript
    wp_localize_script('custom-zigi-popup', 'customZigiData', array(
        'maxFileSize' => 5 * 1024 * 1024, // 5MB
        'allowedTypes' => array('image/jpeg', 'image/png', 'image/gif'),
        'confirmMessage' => __('Are you sure you want to proceed with this payment?', 'your-textdomain')
    ));
}

When customizing JavaScript, ensure your scripts load after the plugin’s scripts by using a higher priority (20+) in wp_enqueue_scripts.

Custom Receipt Validation

Implement custom validation logic for uploaded payment receipts.

/**
 * Add custom validation to receipt upload
 */
add_action('wp_ajax_zigi_payment_qr_code', 'custom_zigi_receipt_validation', 5);
add_action('wp_ajax_nopriv_zigi_payment_qr_code', 'custom_zigi_receipt_validation', 5);

function custom_zigi_receipt_validation()
{
    if (!isset($_FILES['files'])) {
        return;
    }
    
    $file = $_FILES['files'];
    
    // Custom validation: Check file size (max 3MB)
    $max_size = 3 * 1024 * 1024;
    if ($file['size'] > $max_size) {
        wp_send_json_error('El archivo es demasiado grande. Máximo 3MB.', 400);
        wp_die();
    }
    
    // Custom validation: Check image dimensions
    $image_info = getimagesize($file['tmp_name']);
    if ($image_info) {
        $width = $image_info[0];
        $height = $image_info[1];
        
        // Require minimum dimensions
        if ($width < 300 || $height < 300) {
            wp_send_json_error('La imagen es muy pequeña. Mínimo 300x300 píxeles.', 400);
            wp_die();
        }
        
        // Require maximum dimensions
        if ($width > 4000 || $height > 4000) {
            wp_send_json_error('La imagen es muy grande. Máximo 4000x4000 píxeles.', 400);
            wp_die();
        }
    }
    
    // All validation passed, continue with upload
}

Changing Upload Directory Structure

Customize where and how payment receipts are stored.

/**
 * Custom upload directory structure
 * Organizes receipts by order ID
 */
function custom_zigi_upload_directory($dirs)
{
    // Get current order ID from session or POST
    $order_id = WC()->session->get('order_awaiting_payment');
    
    if (!$order_id && isset($_POST['order_id'])) {
        $order_id = absint($_POST['order_id']);
    }
    
    // Create path: /zigi-payments/orders/ORDER_ID/
    $custom_subdir = '/zigi-payments/orders/' . ($order_id ? $order_id : 'pending');
    
    $new_path = $dirs['basedir'] . $custom_subdir;
    $new_url  = $dirs['baseurl'] . $custom_subdir;
    
    // Create directory
    wp_mkdir_p($new_path);
    
    // Add index.html for security
    $index_file = $new_path . '/index.html';
    if (!file_exists($index_file)) {
        file_put_contents($index_file, '<!-- Silence is golden -->');
    }
    
    return array_merge($dirs, array(
        'path'   => $new_path,
        'url'    => $new_url,
        'subdir' => $custom_subdir,
    ));
}

// Replace the default upload_dir filter
remove_filter('upload_dir', 'zigi_payment_qr_code_upload_dir');
add_filter('upload_dir', 'custom_zigi_upload_directory');

When changing the upload directory structure, ensure proper security measures are in place to prevent unauthorized access to payment receipts.

Adding Custom Order Statuses

Create custom order statuses for better payment tracking.

/**
 * Register custom order statuses for ZIGI payments
 */
add_action('init', 'register_zigi_order_statuses');

function register_zigi_order_statuses()
{
    register_post_status('wc-zigi-pending', array(
        'label'                     => __('ZIGI Pending Verification', 'your-textdomain'),
        'public'                    => true,
        'exclude_from_search'       => false,
        'show_in_admin_all_list'    => true,
        'show_in_admin_status_list' => true,
        'label_count'               => _n_noop(
            'ZIGI Pending <span class="count">(%s)</span>',
            'ZIGI Pending <span class="count">(%s)</span>',
            'your-textdomain'
        ),
    ));
    
    register_post_status('wc-zigi-verified', array(
        'label'                     => __('ZIGI Payment Verified', 'your-textdomain'),
        'public'                    => true,
        'exclude_from_search'       => false,
        'show_in_admin_all_list'    => true,
        'show_in_admin_status_list' => true,
        'label_count'               => _n_noop(
            'ZIGI Verified <span class="count">(%s)</span>',
            'ZIGI Verified <span class="count">(%s)</span>',
            'your-textdomain'
        ),
    ));
}

/**
 * Add custom statuses to WooCommerce order statuses
 */
add_filter('wc_order_statuses', 'add_zigi_order_statuses');

function add_zigi_order_statuses($order_statuses)
{
    $new_statuses = array();
    
    // Add custom statuses after 'on-hold'
    foreach ($order_statuses as $key => $status) {
        $new_statuses[$key] = $status;
        
        if ('wc-on-hold' === $key) {
            $new_statuses['wc-zigi-pending'] = __('ZIGI Pending Verification', 'your-textdomain');
            $new_statuses['wc-zigi-verified'] = __('ZIGI Payment Verified', 'your-textdomain');
        }
    }
    
    return $new_statuses;
}

Email Customization

Customize email notifications for ZIGI payments.

/**
 * Add payment receipt to order emails
 */
add_action('woocommerce_email_order_meta', 'add_zigi_receipt_to_email', 10, 3);

function add_zigi_receipt_to_email($order, $sent_to_admin, $plain_text)
{
    if ($order->get_payment_method() !== 'zigi_payment') {
        return;
    }
    
    $receipt_url = $order->get_meta('zigi-payment-qrcode', true);
    
    if (!empty($receipt_url)) {
        if ($plain_text) {
            echo "\n" . __('ZIGI Payment Receipt:', 'your-textdomain') . "\n";
            echo esc_url($receipt_url) . "\n";
        } else {
            echo '<h2>' . __('ZIGI Payment Receipt', 'your-textdomain') . '</h2>';
            echo '<p><a href="' . esc_url($receipt_url) . '">';
            echo '<img src="' . esc_url($receipt_url) . '" alt="Payment Receipt" style="max-width: 300px; border: 2px solid #ddd;" />';
            echo '</a></p>';
        }
    }
}

Advanced Customizations

Add QR Code Watermark

/**
 * Add watermark to uploaded receipts
 */
add_filter('wp_handle_upload', 'zigi_add_receipt_watermark');

function zigi_add_receipt_watermark($upload)
{
    // Only process ZIGI uploads
    if (!isset($_POST['action']) || $_POST['action'] !== 'zigi_payment_qr_code') {
        return $upload;
    }
    
    $image_path = $upload['file'];
    $image_type = wp_check_filetype($image_path)['type'];
    
    // Create image resource
    switch ($image_type) {
        case 'image/jpeg':
            $image = imagecreatefromjpeg($image_path);
            break;
        case 'image/png':
            $image = imagecreatefrompng($image_path);
            break;
        case 'image/gif':
            $image = imagecreatefromgif($image_path);
            break;
        default:
            return $upload;
    }
    
    if (!$image) {
        return $upload;
    }
    
    // Add watermark text
    $watermark_text = 'ZIGI Payment - ' . date('Y-m-d H:i');
    $font_size = 12;
    $text_color = imagecolorallocatealpha($image, 255, 255, 255, 50);
    
    // Position watermark at bottom right
    $image_width = imagesx($image);
    $image_height = imagesy($image);
    
    imagestring(
        $image,
        $font_size,
        $image_width - 200,
        $image_height - 20,
        $watermark_text,
        $text_color
    );
    
    // Save watermarked image
    switch ($image_type) {
        case 'image/jpeg':
            imagejpeg($image, $image_path, 90);
            break;
        case 'image/png':
            imagepng($image, $image_path, 9);
            break;
        case 'image/gif':
            imagegif($image, $image_path);
            break;
    }
    
    imagedestroy($image);
    
    return $upload;
}

Integration with External APIs

/**
 * Send webhook notification when payment is received
 */
add_action('woocommerce_order_status_on-hold', 'zigi_send_webhook_notification');

function zigi_send_webhook_notification($order_id)
{
    $order = wc_get_order($order_id);
    
    if ($order->get_payment_method() !== 'zigi_payment') {
        return;
    }
    
    $receipt_url = $order->get_meta('zigi-payment-qrcode', true);
    
    if (empty($receipt_url)) {
        return;
    }
    
    $webhook_url = get_option('zigi_webhook_url');
    
    if (empty($webhook_url)) {
        return;
    }
    
    $payload = array(
        'order_id'     => $order->get_id(),
        'order_number' => $order->get_order_number(),
        'total'        => $order->get_total(),
        'currency'     => $order->get_currency(),
        'receipt_url'  => $receipt_url,
        'customer'     => array(
            'email'      => $order->get_billing_email(),
            'first_name' => $order->get_billing_first_name(),
            'last_name'  => $order->get_billing_last_name(),
        ),
        'timestamp'    => current_time('mysql'),
    );
    
    wp_remote_post($webhook_url, array(
        'body'    => json_encode($payload),
        'headers' => array(
            'Content-Type' => 'application/json',
        ),
    ));
}

Get Started

Configuration

User Guide

Development

Support

Extending the Gateway Class

Creating a Custom Gateway Extension

Custom CSS Styling

Custom JavaScript Behavior

Custom Receipt Validation

Changing Upload Directory Structure

Adding Custom Order Statuses

Email Customization

Advanced Customizations

Add QR Code Watermark

Integration with External APIs

Next Steps

Hooks & Filters

Configuration

Build docs developers (and LLMs) love

Get Started

Configuration

User Guide

Development

Support

​Extending the Gateway Class

​Creating a Custom Gateway Extension

​Modifying Popup Appearance

​Custom CSS Styling

​Custom JavaScript Behavior

​Custom Receipt Validation

​Changing Upload Directory Structure

​Adding Custom Order Statuses

​Email Customization

​Advanced Customizations

​Add QR Code Watermark

​Integration with External APIs

​Next Steps

Hooks & Filters

Configuration

Build docs developers (and LLMs) love

Extending the Gateway Class

Creating a Custom Gateway Extension

Modifying Popup Appearance

Custom CSS Styling

Custom JavaScript Behavior

Custom Receipt Validation

Changing Upload Directory Structure

Adding Custom Order Statuses

Email Customization

Advanced Customizations

Add QR Code Watermark

Integration with External APIs

Next Steps