Plantilla de Pasarela

La Plantilla de Pasarela te proporciona un punto de partida para construir tu propia pasarela de pago solo para POS. Produce un plugin de WordPress funcional con un solo archivo PHP que puedes instalar y personalizar según tus necesidades.

Características

Código Mínimo

Un solo archivo PHP con solo lo esencial — fácil de leer y modificar

Solo POS

Deshabilitada en el pago web por defecto, habilitada a través de la configuración de WCPOS

Configuración Automatizada

Un script de shell maneja todos los reemplazos de marcadores por ti

Versiones de GitHub

Haz un bump de versión y GitHub Actions construye un ZIP descargable

Empezando

1

Clona el Repositorio de la Plantilla

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

O haz clic en el botón Usar esta plantilla en el repositorio de GitHub para crear tu propia copia.

2

Ejecuta el Script de Configuración

./create-gateway.sh

El script solicita algunos detalles: el nombre de tu pasarela, una breve descripción y tu nombre de usuario de GitHub, y luego genera un plugin listo para usar en un directorio de tu elección.

3

Instala el Plugin

Tienes dos opciones:

Opción A — Copia la carpeta directamente (si tienes acceso al servidor): Copia la carpeta de la pasarela generada en el directorio wp-content/plugins/ de tu sitio.

Opción B — Comprimir y subir (la más fácil para la mayoría de las personas):

1. Comprime la carpeta generada en un archivo .zip
2. En WordPress, ve a Plugins > Añadir Nuevo > Subir Plugin
3. Selecciona el archivo zip y haz clic en Instalar Ahora

4

Habilitar en WCPOS

1. Ve a WP Admin > WCPOS > Configuración > Checkout
2. Encuentra tu nueva pasarela en la lista y habilítala

nota

La pasarela está deshabilitada en el pago web regular por defecto. WCPOS controla qué pasarelas aparecen en el POS a través de su propia configuración.

Configuración Manual

Si prefieres no usar el script, puedes reemplazar los marcadores tú mismo. Abre cada archivo en un editor de texto y busca y reemplaza lo siguiente:

Marcador	Qué ingresar	Ejemplo
{{GATEWAY_NAME}}	El nombre para mostrar de tu pasarela	Pago en Efectivo
{{GATEWAY_SLUG}}	Un identificador seguro para URL (minúsculas, guiones)	pago-en-efectivo
{{GATEWAY_DESCRIPTION}}	Breve descripción de la pasarela	Aceptar pagos en efectivo en WCPOS
{{GATEWAY_DEFAULT_DESCRIPTION}}	Texto mostrado al cajero en el pago	Pagar en efectivo en el punto de venta
{{GITHUB_USERNAME}}	Tu nombre de usuario de GitHub	kilbot
{{REPO_NAME}}	El nombre de tu repositorio	pasarela-pago-en-efectivo
{{AUTHOR_NAME}}	Tu nombre	kilbot
{{GATEWAY_ID}}	Slug con guiones bajos en lugar de guiones	pago_en_efectivo
{{GATEWAY_CLASS_NAME}}	Cada palabra capitalizada, unida por guiones bajos	Pago_En_Efectivo
{{GATEWAY_FUNCTION_PREFIX}}	Igual que el ID de la Pasarela	pago_en_efectivo

Luego renombra wcpos-{{GATEWAY_SLUG}}.php para que coincida con tu slug (por ejemplo, wcpos-pago-en-efectivo.php).

consejo

El script de configuración deriva automáticamente GATEWAY_ID, GATEWAY_CLASS_NAME, y GATEWAY_FUNCTION_PREFIX del nombre y del slug, así que solo necesitas pensar en estos al hacer la configuración manual.

Cómo Funciona

El plugin generado registra una clase de pasarela de pago de WooCommerce. Aquí están las cosas clave que debes saber:

• $this->enabled = 'no' — La pasarela está oculta en el pago web. WCPOS la habilita en el POS según tu configuración del POS.
• process_payment() — Llama a $order->payment_complete(), que marca el pedido como pagado y maneja la reducción de stock automáticamente.
• init_form_fields() — Define los campos de Título y Descripción que aparecen en la configuración de WooCommerce.

Personalizando Tu Pasarela

Agregar Campos de Pago

Si tu pasarela necesita entrada del cajero (por ejemplo, un número de referencia), sobreescribe el método payment_fields():

public function payment_fields() {
    if ( $this->description ) {
        echo wpautop( wptexturize( $this->description ) );
    }

    woocommerce_form_field( 'my_gateway_reference', array(
        'type'        => 'text',
        'label'       => __( 'Reference Number', 'your-text-domain' ),
        'required'    => true,
    ) );
}

Luego puedes leer el valor enviado en process_payment() a través de $_POST['my_gateway_reference']. Recuerda limpiar cualquier entrada con sanitize_text_field().

Cambiar el Comportamiento de Pago

La plantilla por defecto marca los pedidos como pagados de inmediato. Si tu flujo de trabajo requiere pago posterior (como una factura), reemplaza payment_complete() con una actualización de estado:

public function process_payment( $order_id ) {
    $order = wc_get_order( $order_id );

    // Set to pending — the customer will pay later.
    $order->update_status( 'pending', __( 'Awaiting payment', 'your-text-domain' ) );

    // Stock must be reduced manually when not using payment_complete().
    wc_reduce_stock_levels( $order_id );

    return array(
        'result'   => 'success',
        'redirect' => $this->get_return_url( $order ),
    );
}

Realizando Cambios y Actualizando

Después de instalar tu pasarela, puedes seguir editando el archivo del plugin para ajustar la lógica de pago. Para instalar una versión actualizada:

1. Edita wcpos-tu-slug.php en la carpeta generada
2. Actualiza el número de Versión: en el encabezado del plugin (por ejemplo, de 0.1.0 a 0.2.0)
3. Comprime la carpeta y súbela de nuevo a través de Plugins > Añadir Nuevo > Subir Plugin, o reemplaza la carpeta directamente en wp-content/plugins/

consejo

WordPress te preguntará si deseas reemplazar el plugin existente cuando subas un zip con el mismo nombre de plugin — haz clic en Reemplazar el actual con el subido para actualizar.

Versiones Automatizadas con GitHub

Si empujas tu pasarela a un repositorio de GitHub, la plantilla incluye un flujo de trabajo de GitHub Actions que crea releases automáticamente:

1. Actualiza el número de Versión: en el encabezado del plugin
2. Haz commit y empuja a la rama main
3. GitHub Actions detecta el cambio de versión y crea una nueva release con un ZIP descargable

Otros usuarios pueden luego descargar el ZIP desde la página de Lanzamientos de tu repositorio e instalarlo como cualquier plugin de WordPress.

Resolución de Problemas

La pasarela no aparece en el POS

• Verifica que el plugin esté activado en WP Admin > Plugins
• Ve a WP Admin > WCPOS > Configuración > Checkout y asegúrate de que la pasarela esté habilitada
• Verifica que WooCommerce esté instalado y activo

La pasarela aparece en el pago web

• Asegúrate de que $this->enabled = 'no'; esté establecido en el constructor de la pasarela
• WCPOS anula esta configuración para las solicitudes de POS, por lo que la pasarela solo debe aparecer en el POS

Los pedidos permanecen en 'Procesando' en lugar de 'Completado'

• WooCommerce establece el estado del pedido según los tipos de productos. Los pedidos que contienen productos físicos permanecen en "Procesando" — este es un comportamiento normal de WooCommerce. Solo los pedidos con productos exclusivamente virtuales o descargables se marcan como "Completados" automáticamente.

Recursos

• GitHub: woocommerce-gateway-template
• API de Pasarela de Pago de WooCommerce: Documentación de WC_Payment_Gateway

Pasarelas de Ejemplo

Estas pasarelas existentes se construyeron con el mismo enfoque y son buenas referencias:

• Factura por Email — Envía un correo electrónico de factura para que el cliente pueda pagar más tarde
• Pago Web — Redirige a la tienda web para el pago