Plantilla de pasarela

La plantilla de pasarela ofrece un punto de partida para crear su propia pasarela de pago solo para POS. Genera un plugin de WordPress funcional con un único archivo PHP que puede instalar y personalizar según sus necesidades.

Características

Código mínimo

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

Solo POS

Desactivada de forma predeterminada en la finalización de compra web, activada mediante los ajustes de WCPOS

Configuración automatizada

Un script de shell se encarga de reemplazar todos los marcadores de posición

Versiones de GitHub

Al enviar una actualización de versión, GitHub Actions genera un ZIP descargable

Primeros pasos

1

Clonar el repositorio de plantilla

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

También puede hacer clic en el botón Usar esta plantilla del repositorio de GitHub para crear su propia copia.

2

Ejecutar el script de configuración

./create-gateway.sh

El script solicita algunos datos —el nombre de la pasarela, una breve descripción y su nombre de usuario de GitHub— y, a continuación, genera un plugin listo para usar en el directorio que elija.

3

Instalar el plugin

Hay dos opciones:

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

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

1. Comprima la carpeta generada en un archivo .zip
2. En WordPress, vaya a Plugins > Añadir nuevo > Subir plugin
3. Seleccione el archivo ZIP y haga clic en Instalar ahora

4

Activar en WCPOS

1. Vaya a WP Admin > WCPOS > Ajustes > Finalizar compra
2. Busque la nueva pasarela en la lista y actívela

nota

La pasarela está desactivada de forma predeterminada en el proceso de pago web normal. WCPOS controla qué pasarelas aparecen en el POS mediante sus propios ajustes.

Configuración manual

Si prefiere no usar el script, puede reemplazar los marcadores de posición manualmente. Abra cada archivo en un editor de texto y busque y reemplace lo siguiente:

Marcador de posición	Qué introducir	Ejemplo
{{GATEWAY_NAME}}	El nombre visible de la pasarela	Pago en efectivo
{{GATEWAY_SLUG}}	Un identificador apto para URL (minúsculas, guiones)	pago-en-efectivo
{{GATEWAY_DESCRIPTION}}	Descripción breve de la pasarela	Aceptar pagos en efectivo en WCPOS
{{GATEWAY_DEFAULT_DESCRIPTION}}	Texto que se muestra al cajero en el pago	Pagar en efectivo en el punto de venta
{{GITHUB_USERNAME}}	Su nombre de usuario de GitHub	usuario-github
{{REPO_NAME}}	El nombre de su repositorio	pasarela-pago-efectivo
{{AUTHOR_NAME}}	Su nombre	Nombre Autor
{{GATEWAY_ID}}	Slug con guiones bajos en lugar de guiones	pago_efectivo
{{GATEWAY_CLASS_NAME}}	Cada palabra con mayúscula inicial, unida con guiones bajos	Pago_Efectivo
{{GATEWAY_FUNCTION_PREFIX}}	Igual que el ID de la pasarela	pago_efectivo

A continuación, se debe cambiar el nombre de wcpos-{{GATEWAY_SLUG}}.php para que coincida con el slug (por ejemplo, wcpos-cash-payment.php).

consejo

El script de configuración deriva GATEWAY_ID, GATEWAY_CLASS_NAME y GATEWAY_FUNCTION_PREFIX automáticamente a partir del nombre y el slug, por lo que solo es necesario tenerlos en cuenta al realizar una configuración manual.

Cómo funciona

El plugin generado registra una clase de pasarela de pago de WooCommerce. Estos son los puntos principales que conviene conocer:

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

Personalizar la pasarela

Añadir campos de pago

Si la pasarela necesita que el cajero introduzca información (por ejemplo, un número de referencia), anule 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,
    ) );
}

Después puede leer el valor enviado en process_payment() mediante $_POST['my_gateway_reference']. Conviene sanear cualquier entrada con sanitize_text_field().

Cambiar el comportamiento del pago

La plantilla predeterminada marca los pedidos como pagados de inmediato. Si el flujo de trabajo requiere el pago más adelante (como una factura), sustituya payment_complete() por 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 ),
    );
}

Realización de cambios y actualización

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

1. Edite wcpos-your-slug.php en la carpeta generada
2. Actualice el número Version: en la cabecera del plugin (por ejemplo, de 0.1.0 a 0.2.0)
3. Comprima la carpeta en un archivo zip y súbala de nuevo desde Plugins > Añadir nuevo > Subir plugin, o sustituya la carpeta directamente en wp-content/plugins/

consejo

WordPress preguntará si desea sustituir el plugin existente cuando suba un archivo zip con el mismo nombre de plugin — haga clic en Reemplazar el actual con el subido para actualizar.

Versiones automatizadas con GitHub

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

1. Actualice el número Version: en la cabecera del plugin
2. Realice un commit y haga push a la rama main
3. GitHub Actions detecta el cambio de versión y crea un nuevo lanzamiento con un archivo ZIP descargable

A continuación, otros usuarios pueden descargar el ZIP desde la página Versiones de su repositorio e instalarlo como cualquier plugin de WordPress.

Solución de problemas

La pasarela no aparece en el POS

• Compruebe que el plugin esté activado en WP Admin > Plugins
• Vaya a WP Admin > WCPOS > Ajustes > Finalizar compra y asegúrese de que la pasarela esté activada
• Verifique que WooCommerce esté instalado y activo

La pasarela aparece en la página de finalizar compra web

• Asegúrese de que $this->enabled = 'no'; esté definido en el constructor de la pasarela
• WCPOS anula este ajuste para las solicitudes del POS, por lo que la pasarela solo debería aparecer en el POS

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

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

Requisitos

WCPOS: Se requiere la versión Pro para el pago en POS

WordPress: WordPress con WooCommerce instalado

PHP: Conocimientos básicos de PHP para personalizar la pasarela

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 crearon con el mismo enfoque y son buenas referencias:

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