Saltar al contenido principal
Versión: 1.x

Plantilla de Gateway

La Plantilla de Gateway de WooCommerce proporciona un punto de partida para crear tus propias pasarelas de pago personalizadas para WooCommerce POS. Esta plantilla incluye todo el código de boilerplate necesario y la estructura para construir una pasarela de pago completamente funcional.

Características​

Plantilla Completa

Estructura de gateway lista para usar con todos los métodos requeridos

Integración POS

Preconfigurado para la compatibilidad con WooCommerce POS

Configuración Automatizada

Personalización del template basada en scripts

Extensible

Fácil de modificar y ampliar para proveedores de pago específicos

Comenzando​

Opción 1: Generación Automatizada de Plantillas​

La plantilla incluye un script que personaliza automáticamente la plantilla para tu gateway específico:

  1. Clona el Repositorio:

    git clone https://github.com/wcpos/woocommerce-gateway-template.git
    cd woocommerce-gateway-template

  2. Ejecuta el Script de Configuración:

    ./create-gateway.sh

  3. Sigue las Indicaciones:

    • Ingresa el nombre de tu gateway (por ejemplo, "Mi Pasarela de Pago")
    • Ingresa un slug de gateway (por ejemplo, "mi-pago")
    • Proporciona una descripción
    • El script generará un plugin personalizado

Opción 2: Uso Manual de la Plantilla​

Si prefieres la personalización manual:

  1. Descarga la Plantilla:

  2. Personaliza la Plantilla:

    • Reemplaza {{GATEWAY_NAME}} con el nombre que se mostrará de tu gateway
    • Reemplaza {{GATEWAY_SLUG}} con el identificador único de tu gateway
    • Reemplaza {{GATEWAY_DESCRIPTION}} con la descripción de tu gateway

  3. Renombra Archivos:

    • Renombra wcpos-{{GATEWAY_SLUG}}.php para que coincida con el slug de tu gateway
    • Actualiza los encabezados de archivo e información del plugin

Estructura de la Plantilla​

Archivo Principal del Plugin​

El archivo principal del plugin (wcpos-{{GATEWAY_SLUG}}.php) contiene:

  • Encabezado del Plugin: Información del plugin de WordPress
  • Clase de Gateway: Clase principal de la pasarela de pago
  • Inicialización: Configuración del plugin y hooks
  • Integración: Compatibilidad con WooCommerce POS

Componentes Clave​

Estructura de la Clase de Gateway:

class WCPOS_Gateway_{{GATEWAY_CLASS}} extends WC_Payment_Gateway {
    // Gateway configuration
    public function __construct() { }
    
    // Admin settings form
    public function init_form_fields() { }
    
    // Process payment (main logic goes here)
    public function process_payment( $order_id ) { }
    
    // POS-specific methods
    public function payment_fields() { }
}

Guía de Personalización​

Configuración Básica​

  1. Información de Gateway:

    $this->id = 'your_gateway_id';
    $this->title = 'Your Gateway Name';
    $this->description = 'Gateway description for customers';
    $this->method_title = 'Admin title';
    $this->method_description = 'Admin description';

  2. Características Soportadas:

    $this->supports = array(
        'products',
        'refunds',
        'subscriptions', // if applicable
    );

Procesamiento de Pagos​

La lógica principal de pagos va en el método process_payment():

public function process_payment( $order_id ) {
    $order = wc_get_order( $order_id );
    
    // Your payment processing logic here
    // Example: API calls, validation, etc.
    
    if ( $payment_successful ) {
        $order->payment_complete();
        return array(
            'result' => 'success',
            'redirect' => $this->get_return_url( $order )
        );
    } else {
        wc_add_notice( 'Payment failed', 'error' );
        return array(
            'result' => 'failure'
        );
    }
}

Configuración Administrativa​

Configura los ajustes administrativos en init_form_fields():

public function init_form_fields() {
    $this->form_fields = array(
        'enabled' => array(
            'title' => 'Enable/Disable',
            'type' => 'checkbox',
            'label' => 'Enable Your Gateway',
            'default' => 'yes'
        ),
        'api_key' => array(
            'title' => 'API Key',
            'type' => 'text',
            'description' => 'Enter your API key',
            'default' => '',
            'desc_tip' => true,
        ),
        // Add more settings as needed
    );
}

Integración POS​

Para la funcionalidad específica de POS, implementa:

public function payment_fields() {
    // Custom payment form for POS
    if ( is_admin() && isset( $_GET['page'] ) && $_GET['page'] === 'wc-pos' ) {
        // POS-specific payment fields
        echo '<div class="pos-payment-fields">';
        // Your custom POS interface
        echo '</div>';
    } else {
        // Standard web checkout fields
        parent::payment_fields();
    }
}

Mejores Prácticas de Desarrollo​

Estándares de Código​

  • Estándares de Codificación de WordPress: Sigue los estándares de codificación PHP de WordPress
  • Guías de WooCommerce: Adhiérete a las prácticas de desarrollo de WooCommerce
  • Seguridad: Sanea entradas, valida datos, usa nonces
  • Internacionalización: Haz que las cadenas sean traducibles usando __() y _e()

Manejo de Errores​

// Proper error handling
try {
    $result = $this->process_api_call( $data );
    if ( is_wp_error( $result ) ) {
        throw new Exception( $result->get_error_message() );
    }
} catch ( Exception $e ) {
    $order->add_order_note( 'Payment failed: ' . $e->getMessage() );
    wc_add_notice( 'Payment processing error', 'error' );
    return array( 'result' => 'failure' );
}

Registro​

// Add logging for debugging
if ( $this->debug ) {
    $this->log( 'Payment processing started for order ' . $order_id );
}

private function log( $message ) {
    if ( empty( $this->logger ) ) {
        $this->logger = wc_get_logger();
    }
    $this->logger->info( $message, array( 'source' => $this->id ) );
}

Pruebas de Tu Gateway​

Entorno de Desarrollo​

  1. Modo de Prueba: Implementa siempre un modo de prueba/sandbox
  2. Registro de Depuración: Incluye registros exhaustivos para solución de problemas
  3. Escenarios de Error: Prueba diversas condiciones de fallo
  4. Pruebas en POS: Prueba específicamente en el entorno POS

Casos de Prueba​

  • Pagos Exitosos: Verifica que los pedidos se completen correctamente
  • Pagos Fallidos: Asegúrate de un manejo de errores adecuado
  • Reembolsos: Prueba la funcionalidad de reembolsos si se admite
  • Casos Límite: Prueba con diversas cantidades y configuraciones de pedido

Despliegue​

Empaque del Plugin​

  1. Eliminar Archivos de Desarrollo: Limpia archivos de prueba y herramientas de desarrollo
  2. Control de Versiones: Actualiza los números de versión en el encabezado del plugin
  3. Documentación: Incluye README con instrucciones de instalación
  4. Paquete Zip: Crea un archivo zip instalable

Distribución​

  • Versiones de GitHub: Usa versiones de GitHub para la gestión de versiones
  • Directorio de Plugins de WordPress: Considera enviar a WordPress.org
  • Distribución Privada: Alojalo en tus propios servidores si es necesario

Características Avanzadas​

Webhooks​

Para actualizaciones de pago en tiempo real:

public function handle_webhook() {
    $payload = file_get_contents( 'php://input' );
    $data = json_decode( $payload, true );
    
    // Verify webhook signature
    if ( $this->verify_webhook_signature( $payload ) ) {
        $this->process_webhook_data( $data );
    }
}

Soporte a Suscripciones​

Para pagos recurrentes:

// Add subscription support
$this->supports[] = 'subscriptions';
$this->supports[] = 'subscription_cancellation';
$this->supports[] = 'subscription_suspension';

Multi-moneda​

Para pagos internacionales:

public function get_supported_currencies() {
    return array( 'USD', 'EUR', 'GBP', 'CAD' );
}

Recursos​

Documentación​

Repositorio de Plantilla​

  • GitHub: woocommerce-gateway-template
  • Problemas: Reporta problemas de plantilla o solicita funciones
  • Contribuciones: Envía mejoras a través de pull requests

Obtener Ayuda​

Para soporte de desarrollo:

  • Visita el repositorio de GitHub para problemas específicos de la plantilla
  • Consulta la documentación de desarrollo de WooCommerce para preguntas sobre la API
  • Únete a la comunidad de desarrolladores de WooCommerce para orientación general

Gateways de Ejemplo​

Estudia estas pasarelas personalizadas existentes para ejemplos de implementación: