VibeFox dLocal for WooCommerce — Ayuda
Requisitos
WordPress: 5.8 o posterior.
WooCommerce: 7.0 o posterior, instalado y activo.
PHP: 8.0 o posterior. El plugin no se activa con una versión anterior de PHP o WordPress.
Acceso al sitio: tu sitio debe ser accesible desde Internet y usar HTTPS en producción, para que dLocal Go pueda entregar las notificaciones de pago. Un cortafuegos, el modo de mantenimiento o la autenticación básica pueden bloquearlas.
Cuenta de dLocal Go: necesitas la clave API y el secreto API del panel de dLocal Go, sección Payment integration: dashboard-sbx.dlocalgo.com para sandbox, dashboard.dlocalgo.com para producción. Sandbox y producción usan credenciales diferentes. La API empresarial dLocal Payments (credenciales X-Login / X-Trans-Key) es un producto diferente y no es compatible.
Países y monedas: el plugin no los limita. dLocal Go decide qué métodos de pago se ofrecen para el país del cliente y la moneda de la tienda.
Clave de licencia de VibeFox: se compra en vibefox.net. Una clave funciona en un dominio.
Instalación
1. En WordPress ve a Plugins > Add New > Upload Plugin, elige el archivo ZIP del plugin y haz clic en Install Now. También puedes subir la carpeta wcp_dlocal_payment a /wp-content/plugins/ por FTP.
2. Haz clic en Activate. WooCommerce debe estar activo.
3. Abre los ajustes: WooCommerce > Settings > Payments > dLocal Go > Manage, o haz clic en Settings bajo el nombre del plugin en la página Plugins.
4. Introduce tu clave de licencia de VibeFox en el bloque de licencia de la parte superior de la página y haz clic en Activate.
5. Elige el Environment y pega la clave API y el secreto API de ese entorno (consulta Configuración).
6. Activa Enable/Disable y guarda. Prueba un pago en sandbox y después cambia Environment a Production.
Configuración
Todos los ajustes están en una página: WooCommerce > Settings > Payments > dLocal Go. El título de la página muestra SANDBOX o PRODUCTION. Hasta que se introduzcan la clave API y el secreto del entorno seleccionado, la página te avisa de que el método de pago está oculto en la finalización de compra. Mientras sandbox está seleccionado y la pasarela está activada, muestra Sandbox mode is active: payments are simulated, no money is charged. En la lista de métodos de pago, dLocal Go aparece marcado como pendiente de configurar hasta que se establecen las credenciales, y muestra Test mode en sandbox.
General
Enable/Disable: Enable dLocal Go activa o desactiva el método de pago. Por defecto: desactivado.
Title: el nombre del método de pago que ven los clientes en la finalización de compra. Por defecto: dLocal Go.
Description: el texto que se muestra bajo el método de pago en la finalización de compra. Por defecto: Pay with local cards, bank transfer or cash via dLocal Go.
Credenciales de la API
Copia la clave API y el secreto API del panel de dLocal Go, Payment integration: dashboard-sbx.dlocalgo.com (sandbox) o dashboard.dlocalgo.com (producción). Todos los campos de credenciales son campos de contraseña.
Environment: qué credenciales y qué servidores de dLocal Go se usan.
Sandbox API Key: tu clave API de sandbox de dLocal Go.
Sandbox API Secret: tu secreto API de sandbox de dLocal Go.
Production API Key: tu clave API de producción de dLocal Go.
Production API Secret: tu secreto API de producción de dLocal Go.
Pago
Default country: dLocal Go muestra los métodos de pago del país del cliente, tomado de la dirección de facturación y, si no, de la dirección de envío. Este país se usa cuando el pedido no tiene ninguna de las dos. Por defecto: Uruguay.
Auto-complete orders: Set paid orders to "Completed" instead of "Processing". El estado se establece de una vez, con un solo conjunto de correos electrónicos. Por defecto: desactivado.
Notificaciones (IPN)
Las notificaciones informan a tu tienda de que un pago o un reembolso ha cambiado. El plugin envía las URL de notificación a dLocal Go con cada pago y reembolso, así que no hay que configurar nada en el panel de dLocal Go. Esta sección de los ajustes muestra ambas URL:
Las notificaciones se verifican con tu secreto API (HMAC-SHA256). Las notificaciones sin una firma válida se rechazan. Después, el estado, el importe y la moneda del pago siempre se vuelven a leer desde la API de dLocal Go; no se confía en el contenido de la notificación. Sin notificaciones, un pedido solo se actualiza cuando el cliente vuelve a la tienda.
Avanzado
Debug log: Log API requests and notifications escribe los detalles en WooCommerce > Status > Logs, origen wcp_dlocal_payment, sin credenciales de la API ni datos personales. Los errores siempre se registran. Por defecto: desactivado.
Delete data on uninstall: Delete the gateway settings and logs when the plugin is deleted (order payment data is kept). Por defecto: desactivado.
Finalización de compra
El cliente elige el método de pago (por defecto dLocal Go) y realiza el pedido. El plugin crea un pago de dLocal Go por el total del pedido en la moneda del pedido, con el país, el nombre, el correo electrónico y el teléfono del cliente, y envía al cliente a la página de pago de dLocal Go. Allí el cliente paga con un método de su país. El pago aparece en la página de dLocal Go como Order # y el número de pedido. En modo sandbox, la finalización de compra muestra Sandbox mode: no real payment is made. bajo el método de pago.
Después de pagar, el cliente vuelve a la página de pedido recibido de tu tienda. El pedido solo se marca como pagado después de que dLocal Go lo confirme: mediante la notificación firmada o mediante una solicitud del servidor a la API de dLocal Go cuando el cliente llega a esa página.
Si el cliente sale de la página de dLocal Go sin pagar, vuelve a la finalización de compra (o a la página Pay for order) y ve The payment at dLocal Go was not completed. You can try again or choose another payment method. Si el pago fue rechazado o caducó, el mensaje es Your dLocal payment was not completed: it was declined or it expired. Please try again or choose another payment method. Si resulta que el pago ya se realizó, el cliente es enviado a la página de pedido recibido. Un enlace de pago anterior del mismo pedido todavía se puede pagar después de un reintento.
Si dLocal Go no puede iniciar el pago, el cliente ve un mensaje breve sin detalles técnicos, por ejemplo dLocal could not start the payment: seguido del motivo indicado por dLocal, y puede elegir otro método. Esto también ocurre cuando el país del cliente y la moneda de la tienda no están habilitados en tu cuenta de dLocal Go. El motivo técnico se escribe en el registro.
El método de pago funciona en la finalización de compra clásica, en el bloque de Finalizar compra y en la página Pay for order. Es compatible con el almacenamiento de pedidos de alto rendimiento (HPOS) de WooCommerce.
El plugin solo acepta pagos únicos en la página de dLocal Go. No tiene formulario de tarjeta en tu sitio, ni tarjetas guardadas, ni suscripciones, ni autorización y captura por separado.
Pedidos y reembolsos
Estados del pedido
Pending payment: el cliente fue enviado a dLocal Go y aún no ha pagado, o el pago está pendiente en dLocal Go (por ejemplo, un vale de pago en efectivo aún no pagado). Cada nuevo intento de pago se anota en el pedido con su ID de pago de dLocal, el importe y el entorno.
Processing or Completed: el pago se confirmó. El pedido queda en Procesando (lo predeterminado en WooCommerce), o en Completado con Auto-complete orders activado. El ID de transacción es el ID de pago de dLocal.
On hold: dLocal Go informó de un importe o una moneda diferentes del total del pedido, o el pago llegó después de que el pedido se cancelara. La nota del pedido lo explica. Compáralo con el panel de dLocal Go y completa el pedido o reembolsa el pago.
Failed: el último intento de pago fue rechazado o caducó. El cliente puede intentarlo de nuevo.
Cancelled: dLocal Go informó de que el último intento de pago fue cancelado.
Solo el último intento de pago puede hacer fallar o cancelar un pedido no pagado. Una notificación antigua nunca reabre un pedido pagado. Si llega un segundo pago de un pedido que ya está pagado, el pedido no se cambia. Una nota te pide que reembolses el pago duplicado en el panel de dLocal Go.
Reembolsos
Abre el pedido, haz clic en Refund, introduce el importe y haz clic en Refund via dLocal Go. Se admiten reembolsos totales y parciales de los pedidos pagados a través de dLocal Go. El reembolso se envía al entorno en el que se hizo el pago, con las credenciales de ese entorno. Si dLocal Go no acepta el reembolso, WooCommerce muestra el error y no se registra ningún reembolso. Un reembolso aceptado se añade a las notas del pedido con el ID y el estado del reembolso.
Después, dLocal Go informa del estado final del reembolso mediante la notificación de reembolso, y este se añade a las notas del pedido. Si más tarde dLocal Go rechaza o cancela un reembolso que había aceptado, la nota avisa de que el dinero no se devolvió al cliente. Revisa el reembolso de WooCommerce registrado para él: elimínalo y reembolsa de nuevo, o reembolsa al cliente de otra forma.
Los reembolsos hechos en el panel de dLocal Go no se registran como reembolsos de WooCommerce y normalmente no añaden ninguna nota al pedido. Si es necesario, crea un reembolso manual en WooCommerce sin Refund via dLocal Go.
Clave de licencia
El plugin funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia está en la parte superior de WooCommerce > Settings > Payments > dLocal Go. Pega la clave en License key y haz clic en Activate. El bloque muestra el estado, por ejemplo la fecha hasta la que la licencia está activa y tu dominio. Usa Check now para volver a comprobar el estado, Change key para introducir otra clave y Remove key para quitarla de este sitio. El enlace Manage licenses and domains in your account abre tu cuenta de vibefox.net.
Una clave funciona en un dominio. Quitar la clave de un sitio no libera la plaza de su dominio. Libera la plaza en tu cuenta de vibefox.net.
Sin una clave activa, dLocal Go no se muestra a los clientes en la finalización de compra. Si aun así se inicia un pago, el cliente ve This payment method is not available. Please choose another one. Los gestores de la tienda que han iniciado sesión siguen viendo el método de pago, marcado (unlicensed — visible to admins only), para que puedas configurar y probar el plugin antes de comprar una clave. Aparece un recordatorio en la página Plugins y en las páginas de WooCommerce. Los pedidos existentes no se ven afectados: los pagos ya iniciados se siguen confirmando y los reembolsos funcionan.
Cuando una licencia caduca, el plugin sigue funcionando, pero las actualizaciones y el soporte requieren una renovación. El estado se vuelve a comprobar automáticamente en segundo plano.
Solución de problemas
dLocal Go no aparece en la finalización de compra: comprueba que la licencia esté activa, que Enable/Disable esté activado y que la clave API y el secreto API del Environment seleccionado estén configurados. La página de ajustes muestra un aviso cuando faltan.
El pago se realizó, pero el pedido sigue en Pendiente de pago: dLocal Go no pudo acceder a la URL de notificación (cortafuegos, modo de mantenimiento, autenticación básica) y el cliente no volvió a la página de pedido recibido. Revisa WooCommerce > Status > Logs, origen wcp_dlocal_payment, y el pago en el panel de dLocal Go. En cuanto llega una notificación o el cliente abre la página de pedido recibido, el pedido se actualiza.
La notificación responde Missing signature o Invalid signature: la clave API y el secreto de los ajustes no pertenecen a la cuenta que envió la notificación. Las notificaciones se comprueban con las credenciales de ambos entornos, así que los pagos iniciados antes de cambiar Environment se siguen confirmando, siempre que las credenciales de su entorno permanezcan en los ajustes.
La notificación responde Gateway not configured: faltan las credenciales del entorno seleccionado. dLocal Go reintenta la notificación.
La notificación responde API verification failed: no se pudo acceder a la API de dLocal Go para leer el pago. dLocal Go reintenta la notificación.
La notificación responde Order not found: el pago no pertenece a un pedido de esta tienda; por ejemplo, lo creó otro sitio con la misma cuenta de dLocal Go.
El cliente ve This payment method is temporarily unavailable: dLocal Go rechazó la clave API o el secreto. Comprueba las credenciales del entorno seleccionado.
El pedido está En espera después del pago: lee la nota del pedido. El importe o la moneda pagados no coincidían con el pedido, o el pago llegó después de que el pedido se cancelara. Completa el pedido o reembolsa el pago.
El reembolso falla con un mensaje sobre credenciales que faltan: el pago se hizo en el otro entorno y sus credenciales no están configuradas. Introdúcelas e inténtalo de nuevo.
El bloque de licencia muestra un error: sigue el mensaje del bloque. Por ejemplo, si la clave ya se usa en otro dominio, libera una plaza en tu cuenta de vibefox.net y haz clic en Check now. Si la dirección del sitio cambió, haz clic en Check now para activar la clave para el nuevo dominio. Si no se puede acceder al servidor de licencias, el plugin sigue funcionando con el último estado conocido.
Para desarrolladores, la documentación del plugin enumera los filtros dlocal_p_payment_data, dlocal_p_currency_decimals y dlocal_p_icon.
Desinstalación
Al desactivar el plugin se conservan todos los datos. Para eliminarlo, desactívalo y bórralo en la página Plugins. La clave de licencia y el estado de la licencia de este plugin siempre se eliminan. Los ajustes de la pasarela y los registros solo se eliminan si Delete data on uninstall estaba activado. Si no, se conservan para una reinstalación posterior. Los pedidos existentes conservan sus notas de pago y los ID de transacción.
dLocal es una marca comercial de su respectivo propietario. Este plugin no está afiliado a dLocal ni cuenta con su respaldo.