VibeFox dLocal for PrestaShop — Ayuda
Requisitos
PrestaShop: 8.0 a 9.x.
PHP: 8.0 o posterior. El módulo se niega a instalarse en versiones anteriores de PHP.
Acceso a la tienda: tu tienda debe ser accesible desde Internet, y usar HTTPS en producción, para que dLocal Go pueda enviar las notificaciones de pago.
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 de dLocal Payments (credenciales X-Login / X-Trans-Key) es un producto distinto y no es compatible.
Países y monedas: el módulo no los limita. dLocal Go decide qué métodos de pago se ofrecen para el país del cliente y la moneda del carrito. Solo se aplican las restricciones de pago de PrestaShop.
Clave de licencia de VibeFox: se compra en vibefox.net. Una clave funciona en un solo dominio.
Instalación
1. En el back office ve a Modules > Module Manager y haz clic en Upload a module. Elige el archivo ZIP del módulo.
2. Cuando termine la subida, haz clic en Configure, o busca VibeFox dLocal Payment más tarde en la lista de módulos y haz clic en Configure.
3. Pega tu clave de licencia de VibeFox en License key, en el bloque de licencia de la parte superior de la página Configure, y haz clic en Activate (ver Clave de licencia).
4. Elige el Environment e introduce la clave API y el secreto API de ese entorno (ver Configuración).
5. Activa Enable/Disable y haz clic en Save. Prueba un pago en sandbox y luego cambia Environment a Production.
Al instalar, el módulo crea el estado de pedido dLocal payment on hold. PrestaShop ofrece el nuevo módulo de pago para todas las monedas, países y grupos de clientes. Puedes limitarlos en Payment > Preferences.
Configuración
Todos los ajustes están en la página del módulo: Modules > Module Manager > VibeFox dLocal Payment > Configure. Cada sección tiene su propio botón Save, que guarda toda la página. El título de la primera sección muestra SANDBOX o PRODUCTION. Hasta que no introduzcas 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, por ejemplo Enter the sandbox API key and secret: until then the payment method is hidden at checkout. Mientras esté seleccionado sandbox y el método de pago esté activado, se muestra Sandbox mode is active: payments are simulated, no money is charged.
dLocal Go
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. También es el nombre del método de pago guardado en el pedido. Por defecto: dLocal Go. Obligatorio.
Description: el texto que se muestra debajo del 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 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). La sección enlaza ambos paneles.
Environment: qué credenciales y qué servidores de dLocal Go se usan para los pagos nuevos.
Los reembolsos y las notificaciones de un pago siempre usan las credenciales del entorno en el que se hizo, así que conserva las credenciales del otro entorno mientras sus pagos sigan abiertos o puedan reembolsarse.
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.
Las claves y los secretos guardados nunca se vuelven a mostrar. El campo queda vacío y muestra Saved — leave empty to keep it. Escribe un valor nuevo solo si quieres cambiarlo.
Clear saved credentials: marca una clave o un secreto y haz clic en Save para eliminarlo. Un campo vacío mantiene el valor guardado.
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 existe, de la de envío. Este país se usa cuando el carrito no tiene ninguna de las dos. Por defecto: Uruguay.
Auto-complete orders: pone los pedidos pagados en Delivered en lugar de Payment accepted. El estado se establece de una vez, con un único cambio de estado. Por defecto: desactivado.
Notifications (IPN): las notificaciones informan a tu tienda de que un pago o un reembolso ha cambiado. El módulo envía las URL de notificación a dLocal Go con cada pago y cada reembolso, así que no hay que configurar nada en el panel de dLocal Go. Este campo muestra ambas URL:
Las notificaciones se verifican con tu secreto API (HMAC-SHA256). Las notificaciones sin firma válida se rechazan. Una notificación debe estar firmada con las credenciales del entorno en el que se hizo el pago. Después, el estado, el importe y la moneda del pago siempre se vuelven a leer de la API de dLocal Go; el contenido de la notificación no se considera fiable. Sin notificaciones, el pedido se crea solo cuando el cliente vuelve a la tienda.
Avanzado
Debug log: escribe las peticiones y notificaciones de dLocal Go en logs/dlocal_p_debug.log.php, en la carpeta del módulo. El archivo no se puede abrir desde la web. Las credenciales de API y los datos personales no se registran. Los errores y las advertencias siempre se escriben; las demás entradas solo mientras esta opción esté activada. Por defecto: desactivado.
Log: muestra el tamaño y las entradas más recientes del registro. Haz clic en Clear log para vaciarlo.
Delete data on uninstall: si está activado, al desinstalar el módulo se eliminan los ajustes de la pasarela y el registro. Los datos de pago de los pedidos (pagos y reembolsos de dLocal) y el estado de pedido dLocal payment on hold siempre se conservan, para que los pedidos existentes sigan funcionando. Por defecto: desactivado.
Finalización de compra
En el paso de pago, el cliente elige el método de pago (por defecto dLocal Go). En modo sandbox, la finalización de compra muestra Sandbox mode: no real payment is made. debajo del método de pago. Al confirmar, el módulo crea un pago en dLocal Go por el total del carrito en la moneda del carrito, 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 del carrito. En este momento todavía no existe ningún pedido.
Después de pagar, el cliente vuelve a tu tienda. El pedido se marca como pagado solo cuando dLocal Go lo confirma: mediante la notificación firmada o mediante una consulta del servidor a la API de dLocal Go cuando el cliente vuelve. Entonces se crea el pedido y el cliente ve la página estándar de confirmación del pedido con Your payment with dLocal Go has been received. Si el pedido se puso en espera, la página muestra Your dLocal Go payment has been received and is being reviewed by the store. You will be informed when your order is confirmed. Si dLocal Go todavía no ha confirmado el pago (por ejemplo, un vale de efectivo sin pagar, o si no se pudo contactar con dLocal Go), una página Payment confirmation pide al cliente que no pague otra vez y ofrece Check again y Back to checkout. El pedido se crea en cuanto dLocal Go confirma el pago.
Si el cliente sale de la página de dLocal Go sin pagar, vuelve a la finalización de compra 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. El carrito se conserva. Cada nuevo intento crea un nuevo pago en dLocal Go; un enlace de pago anterior del mismo carrito todavía se puede pagar y crea el pedido.
Si dLocal Go no puede iniciar el pago, el cliente se queda en la finalización de compra con un mensaje breve, por ejemplo dLocal could not start the payment: seguido del motivo indicado por dLocal. Esto también ocurre cuando el país del cliente y la moneda del carrito no están habilitados en tu cuenta de dLocal Go. Si dLocal Go rechaza tus credenciales, el cliente ve This payment method is temporarily unavailable. Please choose another payment method or contact us. El motivo técnico se escribe en el registro.
Las notificaciones funcionan mientras la tienda está en modo de mantenimiento y no las bloquea la restricción de país de tu tienda.
El módulo acepta solo 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
Todavía sin pedido: el cliente fue enviado a dLocal Go y no ha pagado, o el pago sigue pendiente en dLocal Go. Solo existe el carrito.
Payment accepted or Delivered: se confirmó el pago. El pedido queda en «Pago aceptado», o en «Entregado» con Auto-complete orders activado. El pago se registra con el ID de pago de dLocal como ID de transacción, y una nota muestra el entorno y el ID de pago.
dLocal payment on hold: dLocal Go informó de un importe o una moneda distintos al total del carrito (por ejemplo, si el carrito se cambió en otra pestaña después de iniciar el pago), o el pago llegó después de que el pedido se hubiera cancelado. La nota lo explica. Compara con el panel de dLocal Go y completa el pedido o reembolsa el pago.
Refunded: el pago fue reembolsado por completo a través del módulo.
Un pago rechazado, caducado o cancelado nunca cambia un pedido existente. Si llega un segundo pago para un pedido que ya está pagado, el pedido no se modifica. Una nota te pide que reembolses el pago duplicado en el panel de dLocal Go.
Bloque de pago de dLocal Go
La página del pedido muestra un bloque dLocal Go payment con el ID de pago de dLocal, el entorno (con una etiqueta Sandbox para los pagos de prueba), el estado del pago, el importe cobrado por dLocal Go y el importe reembolsado, el formulario de reembolso, el historial de reembolsos y las dLocal Go notes del pedido.
Reembolsos
En el bloque dLocal Go payment, introduce el importe (se rellena el importe aún no reembolsado), opcionalmente un motivo, y haz clic en Refund via dLocal Go. Confirma la pregunta Refund this amount through dLocal Go? This cannot be undone. Se admiten reembolsos totales y parciales. Necesitas el permiso para editar pedidos; no hace falta acceso a las páginas de Módulos. Los reembolsos se hacen por el importe y en la moneda que cobró dLocal Go, así que después de una diferencia de importe o de moneda puedes reembolsar hasta lo que el cliente pagó realmente, no el total del pedido. 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, el bloque muestra el error y no se registra ningún reembolso. Un reembolso aceptado se añade al historial de reembolsos y a las notas con el ID del reembolso, el estado y el motivo. Un reembolso total pone el pedido en Refunded. Un reembolso parcial no cambia el estado.
Después, dLocal Go informa del estado final del reembolso mediante la notificación de reembolso, y se añade a las notas. Si dLocal Go rechaza o cancela más tarde un reembolso que había aceptado, la nota avisa de que el dinero no se devolvió al cliente. Reembolsa de nuevo al cliente o por otra vía.
El módulo no crea facturas de abono. Los botones de reembolso estándar de PrestaShop en la página del pedido no devuelven dinero a través de dLocal Go. Los reembolsos hechos en el panel de dLocal Go no se registran como reembolsos en PrestaShop y normalmente no añaden ninguna nota. Actualiza el pedido manualmente si hace falta.
Clave de licencia
El módulo funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia License — VibeFox dLocal Payment es el primer bloque de Modules > Module Manager > VibeFox dLocal Payment > Configure, encima de los ajustes. Pega la clave en License key y haz clic en Activate. Después, el bloque muestra la clave oculta, el estado (por ejemplo, la fecha hasta la que la licencia está activa y tu dominio) y los botones Check now para volver a comprobar el estado, Change key para introducir otra clave y Remove key para quitar la clave de esta tienda. Debajo aparecen la línea Product: presta-payment-dlocal y el enlace Manage licenses and domains in your account, que abre tu cuenta de vibefox.net. Solo los empleados con el permiso Configure del módulo pueden cambiar la clave. Los textos del bloque siguen el idioma del back office (se incluyen inglés y ruso).
Si la clave no se acepta, el bloque indica el motivo, por ejemplo Key not found, This key belongs to another product, Domain limit reached o License expired on seguido de una fecha. Después de cambiar la dirección de la tienda, o después de liberar un hueco de dominio en tu cuenta, haz clic en Check now. Si el servidor de licencias no responde, el módulo sigue funcionando con el último estado conocido.
Una clave funciona en un solo dominio: el dominio de la tienda principal, también en una configuración multitienda. Quitar la clave de la tienda no libera su hueco de dominio. Libera el hueco 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 de todos modos se inicia un pago, el cliente ve This payment method is not available. Please choose another one. La tienda de PrestaShop no sabe que has iniciado sesión en el back office, así que el método de pago también se oculta para ti: puedes configurar el módulo antes de comprar una clave, pero no probarlo en la finalización de compra. Aparece un recordatorio en Modules > Module Manager, en la pestaña Alerts. Los pedidos existentes no se ven afectados: los pagos ya iniciados siguen confirmándose y los reembolsos funcionan.
Cuando una licencia caduca, el módulo sigue funcionando, pero las actualizaciones y el soporte necesitan una renovación. El estado se comprueba de nuevo automáticamente mientras trabajas en el back office: una vez al día durante los primeros 14 días después de introducir la clave, y después una vez a la semana. No hace falta ningún cron job. Desinstalar o restablecer el módulo elimina siempre la clave de licencia y el estado de la licencia.
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 introducidos. La página de ajustes muestra una advertencia si faltan. En Payment > Preferences comprueba que el módulo esté permitido para la moneda del carrito, el país del cliente y el grupo del cliente.
El pago se realizó, pero no se creó ningún pedido: dLocal Go no pudo llegar a la URL de notificación (cortafuegos, autenticación básica, sin dirección pública) y el cliente no volvió a la tienda. Activa Debug log, revisa el campo Log y comprueba el pago en el panel de dLocal Go. En cuanto llegue una notificación o el cliente pulse Check again, el pedido se crea.
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 del entorno del pago, así que los pagos iniciados antes de cambiar el Environment siguen confirmándose, siempre que las credenciales de su entorno sigan en los ajustes.
La notificación responde Gateway not configured: faltan las credenciales del entorno del pago. Introdúcelas; dLocal Go reintentará la notificación.
La notificación responde API verification failed: no se pudo contactar con la API de dLocal Go para leer el pago. dLocal Go reintentará la notificación.
La notificación responde Temporarily unavailable: otra petición estaba confirmando el pedido en ese mismo momento, o no se pudo crear el pedido (por ejemplo, el módulo está desactivado). dLocal Go reintentará la notificación. El motivo está en el registro.
La notificación responde Order not found: el pago no pertenece a un carrito de esta tienda, por ejemplo porque 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. Revisa las credenciales del entorno seleccionado.
El cliente ve Payment gateway is not properly configured: faltan las credenciales del entorno seleccionado.
El pedido está en dLocal payment on hold después del pago: lee las notas del bloque dLocal Go payment. El importe o la moneda pagados no coincidían con el carrito, o el pago llegó después de que se cancelara el pedido. Completa el pedido o reembolsa el pago.
El reembolso falla con un mensaje sobre credenciales ausentes: el pago se hizo en el otro entorno y sus credenciales no están configuradas. Introdúcelas y vuelve a intentarlo.
Para desarrolladores, la documentación del módulo describe los hooks actionWcpDlocalPaymentData y actionWcpDlocalCurrencyDecimals.
Desinstalación
Ve a Modules > Module Manager, abre el menú junto a VibeFox dLocal Payment y elige Uninstall. La clave de licencia y el estado de la licencia de este módulo siempre se eliminan. Si Delete data on uninstall está activado, se eliminan los ajustes de la pasarela y el registro. Si está desactivado, todos los ajustes se conservan para una reinstalación posterior. Los pagos y reembolsos de dLocal de los pedidos y el estado de pedido dLocal payment on hold siempre se conservan, así que los pedidos pagados antes se pueden reembolsar después de reinstalar. Los pedidos existentes conservan sus notas de pago y sus ID de transacción.
dLocal es una marca comercial de su respectivo titular. Este módulo no está afiliado a dLocal ni cuenta con su respaldo.