Skip to main content

​
Overview

This guide will walk you through the complete setup process from activating the plugin to accepting your first ZIGI payment. You’ll learn how to configure the payment gateway, upload your QR code, and test the payment flow.
Estimated Time: 10-15 minutesMake sure you have your ZIGI QR code image ready before starting.

​
Step 1: Access Payment Settings

After installing and activating the plugin, configure the payment gateway:
1

Navigate to WooCommerce Settings

From your WordPress admin dashboard:Go to WooCommerce → Settings → PaymentsYou should see “Paga con ZIGI” listed among available payment methods
2

Access ZIGI Settings

Locate Paga con ZIGI in the payment methods listClick Manage or Set up to open the configuration page
The payment method is disabled by default. You’ll enable it after configuration.

​
Step 2: Basic Configuration

Configure the essential settings for your payment gateway:
1

Enable the Payment Method

Check the box for “Habilitar Paga con ZIGI” (Enable Paga con ZIGI)This makes the payment method visible at checkout
2

Set Payment Title

Field: Título (Title)Default: “Paga con ZIGI”This is what customers see as the payment method name at checkout
Example: Paga con ZIGI - Código QR
Keep the title clear and recognizable. Most users keep the default.
3

Configure Checkout Description

Field: Descripción (Description)Default: “Método de pago vía QR ZIGI. Al realizar el pago, debes adjuntar el comprobante con la orden de compra.”This appears below the payment method at checkout
Example: Escanea el código QR con tu app ZIGI y completa el pago. 
Recuerda adjuntar tu comprobante de pago.
4

Set Popup Description

Field: Descripción del Popup (Popup Description)Default: “Debes escanear el código QR, hacer clic en continuar para adjuntar la captura (es el único comprobante de pago) y podrás completar la compra.”This appears in the payment popup modal shown to customers
This is crucial for guiding customers through the payment process

​
Step 3: Upload Your ZIGI QR Code

The QR code is the most important element - customers will scan it to make payments:
1

Locate QR Upload Section

Scroll to “Seleccionar Imagen QR” (Select QR Image)Click the upload area or “Sube el QR aquí” button
2

Select Your QR Code Image

The WordPress media library will open
  • Upload new: Click “Upload files” and select your ZIGI QR code image
  • Use existing: Select a previously uploaded QR code
Supported formats: JPG, PNG, GIF
Make sure your QR code is clear and scannable. Test it with your ZIGI app before uploading.
3

Verify QR Preview

After selecting, the QR code should appear in the “Vista Previa” (Preview) sectionVerify that:
  • The image is clear and readable
  • The QR code is correctly oriented
  • No important parts are cut off
Click the preview image to view it full-size and ensure quality

​
QR Code Best Practices

  • Resolution: Use at least 500x500 pixels for clarity
  • Format: PNG recommended for best quality
  • Background: Ensure good contrast between QR code and background
  • Testing: Always test the QR code with the ZIGI app before going live

​
Step 4: Configure Advanced Settings (Optional)

Customize additional settings based on your business needs:
Restrict payments to specific amount ranges:Monto Límite (Amount Limit)
Example: 500
This sets a maximum payment amount (e.g., 500 GTQ per transaction)Mensaje de Monto Límite (Limit Message)
Example: Este método no permite pagos mayores a 500 por día.
This message displays when the cart total exceeds the limit
Leave empty if you don’t want to set payment limits
Display your ZIGI-affiliated phone number for customer support:Número de Teléfono Afiliado
Example: +502 1234-5678
This creates a clickable link in the payment popup:
Agregar Contacto: +502 1234-5678
Customers can click to add your number or call directly
Include country code for international format: +502 for Guatemala
Add a custom icon next to the payment method name at checkout:The icon appears in the $this->icon property:
$this->icon = ''; // Currently no default icon
To add a custom icon, you can modify the code or use a filter hook

​
Step 5: Save Settings

Finalize your configuration:
1

Review All Settings

Scroll through the page and verify:
  • ✅ Payment method is enabled
  • ✅ Title and descriptions are set
  • ✅ QR code is uploaded and previews correctly
  • ✅ Optional settings configured (if needed)
2

Save Changes

Click “Save changes” at the bottom of the pageYou should see a success message:
Your settings have been saved.
3

Verify Payment Method is Active

Return to WooCommerce → Settings → PaymentsConfirm “Paga con ZIGI” shows a green checkmark or “Enabled” status

​
Step 6: Test the Payment Flow

Before accepting real payments, test the complete flow:
1

Create a Test Order

  1. Visit your store’s frontend
  2. Add a product to cart
  3. Proceed to checkout
  4. Fill in billing details (use test data)
2

Select Paga con ZIGI

At the payment methods section:
  • You should see “Paga con ZIGI” as an option
  • The description you configured appears below it
  • Select the radio button to choose this payment method
If you don’t see the payment method, verify:
  • Plugin is activated
  • Payment method is enabled in settings
  • WooCommerce cache is cleared
3

Place Order and View Popup

Click “Place order” buttonA popup modal should appear displaying:
  • Your uploaded QR code
  • Total amount to pay
  • Your phone number (if configured)
  • Payment instructions
// The popup is triggered by frontend JavaScript
// Located in: assets/woopro-front.js
4

Simulate Payment

For testing purposes:
  1. Take a screenshot of any payment (or use a sample image)
  2. Click “Continuar” (Continue) in the popup
  3. Upload the test image via drag-and-drop or file selector
  4. Click “Completar Compra” (Complete Purchase)
The AJAX upload handler validates that only image files (JPG, PNG, GIF) are accepted
5

Verify Order Creation

After completing the test:
  • You should be redirected to the order received page
  • Order status should be “On hold” (awaiting payment verification)
  • Check WooCommerce → Orders to see the new order
6

Check Payment Receipt

Open the test order in admin:
  1. Go to WooCommerce → Orders
  2. Click on your test order
  3. Scroll to the “Comprobante de Pago QR” meta box
  4. Verify the uploaded receipt image appears
// Receipt stored in order meta:
$zigi_payment_qrcode = $order->get_meta('zigi-payment-qrcode', true);
Click the receipt image to view it in a new tab at full resolution

​
Understanding the Payment Flow

Here’s what happens behind the scenes:

​
Frontend Process

// 1. Customer selects payment method
// 2. Popup displays QR code from settings:
var popup_qr = options.preview_qr; // From WooCommerce settings

// 3. Customer uploads receipt via AJAX:
wp_ajax_zigi_payment_qr_code

// 4. Receipt URL stored in hidden field:
<input type="hidden" name="zigi-payment-qrcode" id="zigi-payment-qrcode" value="uploaded_url" />

​
Backend Processing

public function process_payment($order_id)
{
    $order = wc_get_order($order_id);
    
    // Store receipt URL in order meta
    if (isset($_POST['zigi-payment-qrcode']) && !empty($_POST['zigi-payment-qrcode'])) {
        $order->update_meta_data('zigi-payment-qrcode', esc_url_raw($_POST['zigi-payment-qrcode']));
        $order->save();
    }
    
    // Set order to on-hold status
    $order->update_status('on-hold', __('Esperando pago offline', 'paga-con-zigi'));
    
    // Reduce stock and empty cart
    $order->reduce_order_stock();
    WC()->cart->empty_cart();
    
    // Redirect to thank you page
    return array(
        'result'    => 'success',
        'redirect'  => $this->get_return_url($order)
    );
}

​
Managing Orders

After customers place orders, here’s how to manage them:
1

View Pending Orders

Navigate to WooCommerce → OrdersFilter by status: “On hold”These are orders awaiting payment verification
2

Verify Payment Receipt

Open an order and check the “Comprobante de Pago QR” meta boxVerify the payment receipt shows:
  • Correct amount
  • Valid ZIGI transaction
  • Timestamp matches order date
3

Update Order Status

After verifying payment:
  • Change status to “Processing” or “Completed”
  • Add an order note confirming payment verification
  • Customer receives automatic email notification

​
Automated Status Updates

This plugin does not automatically verify payments. Manual verification is required to ensure payment authenticity before fulfillment.
For automated verification, you would need to integrate with ZIGI’s API (if available).

​
Common Configuration Examples

Título: Paga con ZIGI
Descripción: Escanea el código QR con tu app ZIGI
Monto Límite: (empty - no limit)
Teléfono: (empty)

​
Troubleshooting

Possible causes:
  1. QR image not uploaded correctly
  2. JavaScript not loading
  3. Theme conflict
Solutions:
  • Re-upload QR code and save settings
  • Check browser console for JavaScript errors
  • Test with a default WordPress theme
  • Clear browser and server cache
Error: “error: Tipo de archivo inválido”Solution:Only JPG, JPEG, PNG, and GIF formats are accepted:
if (!in_array($ext, ['jpg', 'jpeg', 'png', 'gif'])) {
    wp_send_json_error('error: Tipo de archivo inválido...');
}
Convert other formats before uploading.
Check these items:
  1. ✅ Plugin activated
  2. ✅ Payment method enabled in settings
  3. ✅ Cart total within configured limits
  4. ✅ WooCommerce properly configured
Debug code:
// Check if gateway is enabled
$gateways = WC()->payment_gateways->get_available_payment_gateways();
var_dump(isset($gateways['zigi_payment']));
Verify:
  • Order meta exists:
$receipt = get_post_meta($order_id, 'zigi-payment-qrcode', true);
echo $receipt; // Should show URL
  • File uploaded successfully to /wp-content/uploads/zigi-payment-qrcode/
  • Meta box registered for HPOS compatibility

​
Next Steps

Configuration Guide

Explore advanced configuration options

Customization

Learn how to customize appearance and behavior

Hooks & Filters

Developer documentation for hooks and filters

Troubleshooting

Detailed solutions for common issues

​
Support Resources

Need help? Here are your support options:
For the best support experience, include:
  • WordPress version
  • WooCommerce version
  • PHP version
  • Description of the issue
  • Screenshots or error messages

Build docs developers (and LLMs) love

Get started for freeTalk to us