# WooCommerce

> Un método de pago para WooCommerce: bitcoin y USDC/USDT directo a tu billetera, y un webhook firmado marca el pedido como pagado.

El plugin de Perly Pay añade cripto al checkout clásico y al bloque Checkout. Cada pedido se convierte en una factura de Perly Pay; el comprador la paga sobre tu tienda o en una página aparte; un webhook firmado marca el pedido como pagado. WordPress 6.5+, WooCommerce 8.6+, PHP 8.1+. No hay que instalar nada en el servidor: el [SDK de PHP](https://pay.perly.io/docs/sdks.md) ya viene dentro.

> **Nota:** Las facturas son en USD o EUR. En una tienda con otra moneda, el método de pago se oculta y sus ajustes explican por qué.

## Instalación

1. **Consigue el zip** — El plugin está en camino a WordPress.org. Mientras no esté, [escríbenos](https://pay.perly.io/es/contact) para pedir `perly-pay-woocommerce.zip`.
2. **Instálalo** — En WordPress: Plugins → Añadir nuevo → Subir plugin, elige el zip y actívalo. WooCommerce debe estar activo.
3. **Abre los ajustes** — WooCommerce → Ajustes → Pagos → **Perly Pay**.

## Configuración

| Campo | Qué poner |
| --- | --- |
| Clave secreta | Dashboard → Developers → API keys. `sk_test_…` para el [modo de prueba](https://pay.perly.io/docs/test-mode.md), `sk_live_…` para dinero real. Los ajustes muestran en qué modo estás. |
| Secreto de firma del webhook | `whsec_…`. **Configurar webhook** lo rellena solo. |
| Página de pago | **Ventana** abre el pago sobre tu tienda (pay.js). **Redirección** lleva al comprador a su página. En móviles siempre se abre la página. |
| Estado tras el pago | Lo que decida WooCommerce (Procesando; Completado para descargas), siempre Procesando o siempre Completado. |
| Título, Descripción | Lo que ven los compradores en el checkout. |
| Registro de depuración | Eventos y errores en WooCommerce → Estado → Registros. Nunca claves, secretos ni datos de compradores. |

1. **Pega la clave** — Y pulsa **Probar conexión**: verás si la clave funciona, su modo y si Perly Pay tiene el webhook de esta tienda.
2. **Configura el webhook** — Pulsa **Configurar webhook**. Añade la dirección de tu tienda (está encima de los botones, `…/wp-json/perly-pay/v1/webhook`) a Perly Pay y guarda el secreto. O añádela tú en Developers → Webhooks y pega el secreto.
3. **Permite la ventana** — En Dashboard → Settings, añade la dirección de tu tienda en **Sites that may embed the checkout**. Sin esto, la ventana ofrece abrir el pago en una pestaña nueva.
4. **Actívalo** — Marca **Aceptar cripto con Perly Pay** y guarda.

## Pruébalo

Con una clave `sk_test_…`, haz un pedido en tu tienda y elige Perly Pay. El pedido queda en **Pendiente de pago**. Paga la factura con monedas de prueba o por la API; su id está en las notas del pedido:

```bash
curl -X POST https://pay.perly.io/api/v1/invoices/inv_…/simulate \
  -H "Authorization: Bearer $PERLY_PAY_SECRET_KEY" -H "Content-Type: application/json" -d '{}'
```

En unos segundos, el pedido pasa a **Procesando**, con una nota: la red, el importe y un enlace a la transacción. `{"outcome":"short"}` y `{"outcome":"over"}` prueban los otros casos una vez elegida la moneda en la página de la factura.

## Cómo los pedidos siguen los pagos

| En Perly Pay | El pedido |
| --- | --- |
| Pagada, remitente revisado (`invoice.fulfilled`) | Pagado: el estado elegido, stock reducido, correo al comprador. Una nota con cada transferencia y su transacción. |
| Vista, pagada en parte, pagada y aún en revisión | Una nota. Sigue pendiente. |
| Retenida para [revisión](https://pay.perly.io/docs/screening.md) | En espera, con el motivo. Decide en Perly Pay. |
| Caducada o cancelada, sin pagar nada | Cancelado. |
| Caducada, pagada en parte | En espera: reembolsa o acepta en Perly Pay. |
| Reembolsada | Reembolsado por completo, o una nota por la parte. |

Cada evento se aplica una vez, al pedido para el que se creó, y un «caducado» tardío nunca cancela un pago. Si el comprador vuelve a la página de gracias antes que el webhook, el plugin consulta la API y actualiza el pedido al momento.

## Reembolsos

Reembolsa como siempre, desde la página del pedido: el plugin abre un [reembolso](https://pay.perly.io/docs/refunds.md) en Perly Pay en la moneda con que se pagó (una parte si es parcial). Perly Pay pide al comprador una dirección por correo y la revisa; las notas del pedido te dicen qué enviar y adónde. Lo envías desde tu billetera y pegas el id de la transacción en Perly Pay: Perly Pay nunca guarda el dinero.

## Pasar a real

- Activa el modo real en Perly Pay y conecta las claves públicas de tu billetera.
- Pega una clave `sk_live_…`. Las claves y los webhooks reales van aparte de los de prueba: pulsa **Configurar webhook** otra vez.
- Añade la dirección https de tu tienda real en **Sites that may embed the checkout** en modo real.
- Haz un pedido real pequeño y reembólsalo.