# 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[​](#features "Enlace directo a 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[​](#getting-started "Enlace directo a 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](https://github.com/wcpos/woocommerce-gateway-template) 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[​](#manual-setup "Enlace directo a 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[​](#how-it-works "Enlace directo a 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[​](#customising-your-gateway "Enlace directo a Personalizar la pasarela")

### Añadir campos de pago[​](#adding-payment-fields "Enlace directo a 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[​](#changing-payment-behaviour "Enlace directo a 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[​](#making-changes-and-updating "Enlace directo a 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[​](#automated-releases-with-github "Enlace directo a 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[​](#troubleshooting "Enlace directo a 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[​](#requirements "Enlace directo a 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[​](#resources "Enlace directo a Recursos")

* **GitHub**: [woocommerce-gateway-template](https://github.com/wcpos/woocommerce-gateway-template)
* **API de pasarela de pago de WooCommerce**: [documentación de WC\_Payment\_Gateway](https://woocommerce.github.io/code-reference/classes/WC-Payment-Gateway.html)

### Pasarelas de ejemplo[​](#example-gateways "Enlace directo a Pasarelas de ejemplo")

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

* **[Factura por correo electrónico](/es/payment/gateways/email-invoice.md)** — Envía un correo electrónico con la factura para que el cliente pueda pagar más tarde
* **[Pago web](/es/payment/gateways/web-checkout.md)** — Redirige a la tienda web para realizar el pago