WooCommerce

El plugin de Aloha para WooCommerce añade Aloha como método de pago en el checkout de una tienda WordPress. El pagador elige el país donde va a pagar, la tienda crea la Solicitud de Pago desde su propio servidor y lo lleva al checkout de Aloha; cuando el cobro se completa, Aloha avisa a la tienda con un webhook firmado y el pedido queda pagado. No hay que escribir código: todo se configura desde el panel de WooCommerce.

La versión actual es la 2.2.0, y pide WordPress 6.0 o superior, WooCommerce 8.0 o superior y PHP 7.4 o superior.

Cómo cobra el plugin

1. En el checkout, el pagador elige Aloha y selecciona la moneda con la que va a pagar, de entre los países que Aloha sirve.
2. Al confirmar el pedido, el plugin crea la Solicitud de Pago desde el servidor de la tienda y redirige al pagador al checkout de Aloha con sus datos ya precargados.
3. El pedido queda en Pendiente de pago, con el identificador de la Solicitud de Pago anotado en sus notas.
4. Aloha entrega un webhook firmado; el plugin comprueba la firma y marca el pedido como pagado.

La Clave API vive en la base de datos de la tienda y no llega nunca al navegador del pagador: todo lo que habla con Aloha lo habla el servidor de la tienda.

Requisitos

• WordPress, WooCommerce y PHP en las versiones de arriba, y acceso de administrador a WordPress.
• Una cuenta de Aloha con Verificar Identidad y Verificación Comercial hechas las dos, y con una Billetera activa. Sin eso, la creación de cobros se rechaza y el método no llega a funcionar — está en Verificación de la cuenta.
• Una Clave API con cuatro Permisos: payment_links:create, payment_links:read, payment_links:cancel y webhooks:write.

Esos cuatro son exactamente lo que el plugin usa: crea la Solicitud de Pago, consulta su Estado, cancela la anterior cuando un pedido se reanuda, y registra su propio endpoint de webhook. Las llamadas que hace para leer las monedas de la cuenta, los países disponibles y la Tasa de Cambio no exigen ningún Permiso. Una clave con * también funciona, y da mucho más de lo necesario.

1. Descargar el plugin

El plugin se distribuye como un archivo .zip: aloha-pay-for-woocommerce-2.2.0.zip (216 KB). Es el mismo archivo para todas las tiendas y para los dos Ambientes; contra cuál de los dos trabaja se decide después, en los ajustes.

2. Instalarlo en WordPress

1. Entrar al panel de administración de WordPress.
2. Ir a Plugins y elegir Añadir nuevo plugin.
3. Pulsar Subir plugin.
4. Seleccionar el archivo .zip descargado y pulsar Instalar ahora.
5. Cuando termine, pulsar Activar plugin.

En la lista de plugins aparece como Aloha for WooCommerce, y en WooCommerce como Aloha.

3. Crear la Clave API

La clave se crea en el panel de Aloha del Ambiente donde vaya a trabajar la tienda, con los cuatro Permisos de la lista de requisitos. El secreto completo se ve una sola vez, y no queda nada de él una vez cerrado el diálogo que la creó, así que hay que copiarlo en ese momento; si se pierde, se crea otra y se borra la anterior. Cómo se crea y qué lleva una clave está en Autenticación y Claves API.

Esta clave no necesita Orígenes Permitidos y conviene que no los lleve: las llamadas del plugin salen del servidor de la tienda y no llevan cabecera Origin, así que una clave con esa lista configurada las rechazaría todas.

4. Configurar el método de pago

En el panel de WordPress: WooCommerce → Ajustes → Pagos, buscar Aloha en la lista y entrar en Gestionar.

La columna de la izquierda transcribe las etiquetas del plugin tal como se leen en pantalla. Una de ellas no coincide con el vocabulario de esta documentación: donde el plugin rotula Entorno, aquí se dice Ambiente.

Los campos que hay que tocar para empezar a cobrar son tres: activar el método, elegir el Ambiente y pegar la Clave API. El resto tiene valores que sirven tal cual.

Lo que ocurre al guardar

Guardar no es solo guardar. Con la clave recién escrita, el plugin hace tres cosas contra la API, y en este orden:

• Lee la moneda de la Billetera y se la queda. Es la moneda en la que va a pedir los cobros. Se queda con la primera que devuelve la cuenta, y esa lista no viene ordenada: una cuenta que acredita en más de una moneda puede acabar con una distinta de la esperada, y eso cambia tanto las conversiones como que el método llegue a ofrecerse.
• Refresca la lista de países que se le ofrecen al pagador en el checkout.
• Registra su endpoint de webhook, en https://<la-tienda>/wc-api/aloha_pay, suscrito a payment.completed, payment.failed, payment_link.cancelled y payment_link.expired, y guarda el secreto de firma que Aloha devuelve. Ese secreto se entrega una sola vez, igual que el de la clave. Qué entrega Aloha de verdad por cada uno de esos eventos está en Webhooks.

Las tres pasan enteras la primera vez que se guarda una clave que funciona, y no se repiten sin motivo: si la lectura de la Billetera falla, el plugin se detiene ahí y las otras dos ni se intentan; y si el secreto, la dirección y el Ambiente siguen siendo los mismos, el registro del webhook no se rehace.

Si algo de eso falla, WooCommerce lo dice con un aviso en la misma pantalla. Vale la pena leerlo: un «no se pudo leer la billetera» casi siempre es la clave pegada a medias o creada en el otro Ambiente, y un «no se pudo registrar el webhook» deja la tienda cobrando pero sin enterarse de los pagos hasta que pase la revisión periódica.

Sobre el botón Conexión y webhook: comprueba la clave leyendo la Billetera y después vuelve a registrar el webhook desde cero. Aloha no admite dos veces la misma dirección en una misma cuenta, así que si la tienda ya lo tenía registrado en ese Ambiente, el botón informa de que no pudo registrarlo aunque no haya nada roto — la parte que confirma que la clave funciona es la que nombra la Billetera. Para volver a registrarlo de verdad, por ejemplo si se perdió el secreto, primero hay que borrar el endpoint existente con las operaciones de webhook de la API —listarlos exige además el Permiso webhooks:read, que el plugin no usa— y guardar de nuevo los ajustes.

5. Comprobar el checkout

1. Añadir un producto al carrito y llegar al checkout.
2. Comprobar que Aloha aparece entre los métodos de pago y que el selector ofrece monedas.
3. Con el Ambiente en Sandbox, completar un pedido de prueba de punta a punta y ver que queda pagado.
4. Cambiar a Producción solo después, y repetir la prueba con un importe pequeño y real: los precios de Sandbox no son los de Producción, como explica Ambientes y Sandbox.

Lo que el pagador ve en el selector son nombres de moneda —«Pesos chilenos», «Reales brasileños»—, con la bandera del país al lado. Esos nombres los pone el plugin y no se configuran: en la versión 1.x había un ajuste para reescribir la etiqueta de cada moneda, y la 2.0 lo retiró.

Si el método no aparece en el checkout

El plugin se esconde cuando no podría cobrar de verdad, y no explica por qué. Se comprueba en este orden:

• El método está activado y tiene una API Key guardada.
• La cuenta tiene una Billetera cuya moneda el plugin pudo leer al guardar. Si la lectura falló, no hay moneda guardada y el método no se ofrece.
• La moneda de la tienda se puede convertir a la de la Billetera — la sección siguiente.
• Hay al menos un país disponible en la respuesta de Aloha.

Lo más habitual es lo segundo: se pegó la clave, la lectura falló por un dedazo, el aviso pasó desapercibido y el método desaparece del checkout sin más señal. Volver a guardar los ajustes, o pulsar Conexión y webhook, lo resuelve o dice qué pasa.

Las monedas: la de la tienda, la de la Billetera y la del pagador

Son tres y no tienen por qué coincidir.

La de la tienda es la que WooCommerce usa para los precios. La de la Billetera es en la que acredita Aloha. Si son distintas, el plugin convierte el total del pedido a la moneda de la Billetera antes de crear la Solicitud de Pago, con la Tasa de Cambio que le pide a Aloha en cada intento. El monto va como amount_type: receive, es decir, anclado al importe de destino y no a lo que paga el pagador; cuando la Billetera es CLP, ARS o COP, que no manejan decimales, el monto se redondea a entero. El plugin tampoco manda customer_paid_fee, así que la Comisión se descuenta de ese importe en vez de sumarse a lo que paga el pagador: lo acreditado no es el total del pedido convertido, sino ese total menos la Comisión, que sale de la configuración de la cuenta y no del plugin.

La del pagador la elige él en el checkout, y es la del país que escoja: hoy, Argentina, Bolivia, Brasil, Chile, Colombia o México. La lista la sirve Aloha y el plugin la refresca al guardar, así que puede crecer sin tocar la tienda. Sobre esa conversión el plugin no decide nada — la hace Aloha al cobrar.

Para que el método se ofrezca, el par tiene que ser convertible. Si la moneda de la tienda y la de la Billetera son la misma, siempre lo es. Si no, las dos tienen que estar entre las que el plugin convierte: USD, ARS, BRL, COP, CLP, MXN y BOB. El plugin no convierte desde ni hacia PEN, así que una Billetera en PEN solo funciona con una tienda que venda también en PEN.

Los pedidos que quedan sin pagar

Un pedido cuyo pagador abandona el checkout se queda en Pendiente de pago, y ahí hay dinero y existencias en juego, así que el plugin no lo deja indefinidamente.

El camino normal es el webhook: llega firmado, el plugin comprueba la firma y mueve el pedido. Una entrega sin firma válida se rechaza sin tocar nada, que es justamente lo que protege a la tienda de que cualquiera le marque pedidos como pagados.

Por debajo hay una revisión periódica, la del ajuste Revisar pedidos sin pagar: pasados esos minutos, el plugin le pregunta a Aloha por cada pedido que siga sin pagar. Solo pregunta. El pedido se cancela únicamente si Aloha confirma que la Solicitud de Pago se canceló o caducó, y si resulta que estaba pagada, se marca pagada. Es lo que cubre el caso de un webhook que no llegó.

Un detalle que conviene conocer antes de ver una nota extraña en un pedido: si el pagador vuelve con el carrito intacto, WooCommerce reanuda el mismo pedido. El plugin reutiliza la Solicitud de Pago anterior cuando sigue activa y cobra exactamente lo mismo; cuando no sirve, la cancela antes de crear la nueva. Si esa cancelación no llega a Aloha, el pedido queda con dos direcciones cobrables: el plugin lo anota en el pedido y avisa ahí mismo si llegan dos pagos.

El log de depuración

El ajuste Log de depuración escribe las peticiones y las respuestas de la API en WooCommerce → Estado → Logs. Sirve para una integración que no arranca y para pasarle algo concreto a soporte.

Se deja apagado en Producción. No es solo por el tamaño de los archivos: esos registros guardan en el disco de la tienda el detalle de lo que se manda y se recibe por cada pedido.

Actualizar desde la 1.x

La 1.x tenía dos modos, External y Embeded. La 2.0 eliminó el modo Embeded, que cargaba código de Aloha en el navegador, dejaba la Clave API a la vista en el HTML del checkout y daba los pedidos por pagados sin comprobar nada en el servidor. Por eso ya no hay un ajuste donde elegir modo: la versión actual solo hace lo que antes era External, y lo hace entero desde el servidor.

Al actualizar, la Clave API se migra sola desde el esquema antiguo y los ajustes que dejaron de existir —el del modo y las etiquetas por moneda— se borran. Hay que volver a guardar los ajustes una vez: es lo que registra el webhook y detecta la moneda de la Billetera.

Quien quiera un formulario de pago dentro de su propia página tiene hoy otra herramienta, que no es este plugin: Checkout embebido.

Seguir por aquí

• Autenticación y Claves API — qué Permisos lleva la clave del plugin y qué contesta cuando falla.
• Webhooks — qué eventos entrega Aloha y cómo se firman las entregas.
• Ambientes y Sandbox — los dos Ambientes y qué no se puede comprobar en Sandbox.
• Checkout embebido — la otra integración sin escribir contra la API.