VibeFox Pin Payments for PrestaShop — Ayuda

Requisitos

PrestaShop: 8.0 a 9.x.

PHP: 8.0 o posterior. El módulo no se deja instalar en versiones anteriores de PHP.

Cuenta de Pin Payments: una cuenta de comerciante de Pin Payments (para empresas de Australia o Nueva Zelanda; los clientes pueden pagar desde cualquier país). Necesitas su clave publicable y su clave secreta, para producción y, para pruebas, para el entorno de prueba. No hace falta ningún secreto de webhook: el módulo no usa webhooks. Pin.js envía los datos de la tarjeta directamente desde el navegador del cliente a Pin Payments, y nunca llegan a tu tienda, así que la tienda entra en PCI SAQ A-EP.

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 más tarde VibeFox Pin Payments Gateway en la lista de módulos y haz clic en Configure.

3. Introduce 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. En el panel de Pin Payments abre Account > API Keys y copia tus claves de prueba en Test publishable key y Test secret key. Deja activado Test mode, activa Enable/Disable y haz clic en Save.

5. Haz un pedido de prueba con una tarjeta de prueba de Pin Payments. Cuando todo funcione, introduce las claves de producción, desactiva Test mode y guarda.

Al instalarse, el módulo crea el estado de pedido Pin Payments payment on hold. PrestaShop ofrece el nuevo módulo de pago para las monedas, los grupos de clientes y los países activos en el momento de la instalación. Puedes cambiarlo en Payment > Preferences; los países que actives más tarde deben marcarse allí.

Configuración

Todos los ajustes están en la página del módulo: Modules > Module Manager > VibeFox Pin Payments Gateway > Configure. Cada sección tiene su propio botón Save, que guarda la página completa. Encima de los campos, la página muestra un aviso mientras el modo de prueba está activado, un error si la clave publicable o la clave secreta del modo actual está vacía, y un error si Pin Payments no admite la moneda predeterminada de la tienda (con la lista de monedas admitidas). Sin las dos claves del modo actual, el método de pago no se muestra en la finalización de compra. Un Title vacío no se guarda: la página muestra Enter a title for the payment method.

Pin Payments

Enable/Disable: Enable Pin Payments 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 que se guarda en el pedido. Por defecto: Credit card (Pin Payments). Obligatorio.

Description: el texto que se muestra debajo del método de pago en la finalización de compra. Por defecto: Pay with your credit card via Pin Payments.

Claves de API

Encontrarás tus claves en el panel de Pin Payments, en Account > API Keys. Las claves de prueba solo funcionan con la API de prueba, y las de producción solo con la API de producción. La clave publicable la usa Pin.js en el navegador del cliente. La clave secreta nunca sale de tu servidor.

Test mode: usa el entorno de prueba de Pin Payments (test-api.pinpayments.com) y las claves de prueba. No se hace ningún cargo real, y los clientes ven TEST MODE — no real charges will be made. debajo del método de pago. Cuando está desactivado, se usan la API de producción y las claves de producción. Por defecto: activado.

Test publishable key: la clave publicable de tu cuenta de prueba de Pin Payments.

Test secret key: la clave secreta de tu cuenta de prueba de Pin Payments.

Live publishable key: la clave publicable de tu cuenta de producción de Pin Payments.

Live secret key: la clave secreta de tu cuenta de producción de Pin Payments.

Los espacios alrededor de las claves se eliminan. Las claves secretas guardadas no 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 secrets: marca una clave secreta y haz clic en Save para eliminarla. Un campo vacío conserva el valor guardado.

Avanzado

Debug log: escribe en logs/wc_ppg_debug.log.php, en la carpeta del módulo. El archivo no se puede abrir desde la web. Los errores siempre se registran; actívalo para registrar también cada llamada a la API. Nunca se registran datos de tarjeta, claves de API ni datos personales de clientes. 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 (cargos y reembolsos) y el estado de pedido Pin Payments payment on hold siempre se conservan. Por defecto: desactivado.

Finalización de compra

El método de pago se muestra cuando está activado, se han introducido las dos claves del modo actual, la moneda del carrito es una de las 14 monedas admitidas (AUD, USD, NZD, SGD, EUR, GBP, CAD, HKD, JPY, MYR, THB, PHP, ZAR, IDR) y el módulo está permitido para el carrito en Payment > Preferences.

En el paso de pago, el cliente elige el método de pago (por defecto Credit card (Pin Payments), con los iconos de Visa, Mastercard y American Express) y rellena Card number, Expiry (MM / YY), CVC y Name on card. Antes de enviar, el formulario comprueba la longitud del número de tarjeta, el mes y el año de caducidad, un CVC de 3 o 4 dígitos y el nombre.

Cuando el cliente realiza el pedido, Pin.js envía los datos de la tarjeta y la dirección de facturación del carrito desde el navegador directamente a Pin Payments y obtiene un token de tarjeta de un solo uso. Solo este token se envía a tu tienda. Después, el módulo crea un cargo capturado por el total del carrito en la moneda del carrito, con el correo electrónico del cliente y la descripción <shop name> - Cart <cart number>. Pin Payments responde en la misma solicitud. Antes de esta respuesta no existe ningún pedido.

Tras un cargo correcto se crea el pedido y el cliente ve la página estándar de confirmación del pedido con Your card payment has been received. Si el pedido pasó a Pin Payments payment on hold, la página muestra Your card payment has been received and is being reviewed. We will update your order as soon as the review is complete.

Si Pin Payments no responde (tiempo de espera agotado, error del servidor, respuesta ilegible), es posible que el cargo se haya creado igualmente. En ese caso, el pedido se crea en Pin Payments payment on hold sin pago, y la página de confirmación muestra We could not confirm your payment with Pin Payments. Please check your e-mail and card statement before paying again, or contact us. Volver a enviar el mismo carrito nunca crea un segundo cargo.

Solo se ejecuta un intento de pago por carrito a la vez. Si se envía por segunda vez, el cliente recibe This order is already being paid. Please wait a moment and check your e-mail before trying again. Un carrito que ya tiene un pedido, o un intento anterior que cobró o pudo haber cobrado dinero, no se vuelve a cobrar; en su lugar, el pedido se crea a partir de ese intento. Un token de tarjeta solo se puede usar una vez: después de un intento fallido, o cuando el cliente cambia los datos de la tarjeta, se crea un token nuevo.

Cuando el pago falla, no se crea ningún pedido. El cliente permanece en el paso de pago, el carrito se conserva y se muestra uno de estos mensajes: Your card was declined. Please use another card or contact your bank.; Your card has insufficient funds. Please use another card.; Your card has expired. Please use another card.; The card security code (CVC) is incorrect.; This card type is not accepted. Please use Visa, Mastercard or American Express.; Payment failed: seguido del motivo de Pin Payments por los datos rechazados; Your card details have expired. Please enter them again and retry. cuando no se puede usar el token; The secure card form could not be loaded. Please reload the page or choose another payment method. cuando Pin.js no se carga; Card payments are temporarily unavailable. Please try again later or choose another payment method. cuando Pin Payments rechaza la clave secreta; Your payment could not be processed. Please try again or choose another payment method. para otros errores. El motivo técnico se escribe en el registro.

El módulo no tiene flujo de 3-D Secure. Si tu cuenta de Pin Payments exige 3-D Secure, el cargo queda pendiente, no se crea ningún pedido y el cliente ve Your card payment could not be completed (additional verification is required). Please try another card or another payment method. No hay modo de solo autorización con captura posterior, ni tarjetas guardadas, ni suscripciones, ni Apple Pay ni Google Pay, ni webhooks.

Pedidos y reembolsos

Estados del pedido

No order yet: la tarjeta fue rechazada, el cargo necesitaba 3-D Secure o el cliente no ha pagado. Solo existe el carrito.

Payment accepted: Pin Payments informó de un cargo correcto y capturado por exactamente el importe y la moneda del carrito. El pago se registra con el token de cargo de Pin Payments como ID de transacción, y una nota muestra el importe y el token de cargo (y TEST MODE en los pagos de prueba).

Pin Payments payment on hold: el cargo necesita tu revisión. La nota explica el motivo: Pin Payments cobró un importe o una moneda distintos de los del carrito (se registra el pago del importe cobrado), el carrito cambió durante el pago, el cargo está autorizado pero no capturado (captúralo en el panel de Pin Payments y luego cambia el pedido a Pago aceptado), o Pin Payments no dio una respuesta clara (no se registra ningún pago; busca la descripción del cargo en el panel de Pin Payments antes de enviar el pedido).

Refunded: el cargo se reembolsó por completo a través del módulo.

Si se realiza un segundo cargo para un carrito que ya tiene un pedido, el pedido no cambia. Una nota te pide que lo compruebes y lo reembolses en el panel de Pin Payments.

Bloque de Pin Payments

La página del pedido muestra un bloque Pin Payments con una insignia Test mode para los pagos de prueba, el token de cargo, el estado, la marca de la tarjeta y los últimos cuatro dígitos, el importe cobrado, el total del pedido y el importe reembolsado, la Description at Pin Payments, el historial de reembolsos y las Pin Payments notes del pedido.

Reembolsos

En el bloque Pin Payments introduce el importe (se rellena el importe que aún no se ha reembolsado), opcionalmente un motivo, y haz clic en Refund via Pin Payments. Confirma la pregunta Refund this amount through Pin Payments? This cannot be undone. Se admiten reembolsos totales y parciales. Necesitas el permiso para editar pedidos. Los reembolsos se limitan al importe y a la moneda que Pin Payments cobró realmente, así que tras una diferencia de importe o de moneda puedes reembolsar hasta lo que pagó el cliente, no el total del pedido. El reembolso se envía al entorno (prueba o producción) en el que se pagó el pedido, así que la clave secreta de ese modo debe estar introducida. Pin Payments procesa los reembolsos de forma asíncrona, por lo que el estado suele ser pendiente. Una solicitud correcta se añade al historial de reembolsos y a las notas, con el token de reembolso de Pin Payments y su estado. Un reembolso total cambia el pedido a Refunded. Un reembolso parcial no cambia el estado. Si Pin Payments rechaza el reembolso o no responde, el bloque muestra el error y no se registra ningún reembolso.

Cuando no hay ningún cargo registrado para el pedido (Pin Payments no dio una respuesta clara), el bloque no muestra el formulario de reembolso e indica qué descripción buscar en el panel de Pin Payments.

El módulo no crea facturas de abono (credit slips). Los botones de reembolso estándar de PrestaShop en la página del pedido no devuelven dinero a través de Pin Payments. Los reembolsos hechos en el panel de Pin Payments no se sincronizan con PrestaShop, así que hazlos desde la página del pedido.

Clave de licencia

El módulo funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia License — VibeFox Pin Payments Gateway es el primer bloque de Modules > Module Manager > VibeFox Pin Payments Gateway > Configure, por encima de los ajustes. Introduce la clave en License key y haz clic en Activate. Después, el bloque muestra la clave enmascarada, 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-pinpayments 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 no se puede contactar con el servidor de licencias, 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, Pin Payments 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. 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 reembolsos de pedidos pagados antes siguen funcionando.

Cuando una licencia caduca, el módulo sigue funcionando, pero las actualizaciones y el soporte necesitan una renovación. El estado se vuelve a comprobar 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 por semana. No se necesita ninguna tarea cron. Desinstalar o restablecer el módulo elimina siempre la clave de licencia y el estado de la licencia.

Solución de problemas

Pin Payments no aparece en la finalización de compra: comprueba que la licencia está activa, que Enable/Disable está activado, que las dos claves del modo actual están rellenas (Test publishable key y Test secret key en modo de prueba, las claves de producción en caso contrario) y que la moneda del carrito es una de las 14 monedas admitidas. 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. La página de ajustes muestra un error si faltan claves y si la moneda de la tienda no es compatible.

El pago se realizó, pero el pedido está en Pin Payments payment on hold: lee las notas del bloque Pin Payments (véase Estados del pedido). Si Pin Payments no dio una respuesta clara, busca en el panel de Pin Payments un cargo con la descripción <shop name> - Cart <cart number> y, después, prepara y envía el pedido o reembolsa el cargo desde el panel.

El cliente ve Your payment was received, but the order could not be completed automatically: la tarjeta se cobró, pero PrestaShop no pudo crear el pedido (por ejemplo, porque el módulo se desactivó entretanto). El motivo está en el registro. Se pide al cliente que no vuelva a pagar; si vuelve a enviar el mismo carrito, se crea el pedido sin un nuevo cargo.

Los clientes ven Card payments are temporarily unavailable: Pin Payments rechazó la clave secreta, o falta la clave del modo actual. Las claves de prueba solo funcionan en modo de prueba, y las de producción solo en modo de producción. El registro muestra el motivo.

Los pedidos fallan con additional verification is required: tu cuenta de Pin Payments exige 3-D Secure, que el módulo no admite. Pide a Pin Payments que desactive el 3-D Secure obligatorio.

No se pudo cargar el formulario seguro de tarjeta: Pin.js desde la CDN de Pin Payments no se cargó en el navegador, por ejemplo por un bloqueador de scripts o por un módulo que combina o modifica scripts. Excluye la finalización de compra de este tipo de optimizaciones.

Pin Payments no respondió: el token de tarjeta no se creó en 30 segundos en el navegador. El cliente puede comprobar la conexión e intentarlo de nuevo; no se cobró nada.

El pago falló con un motivo de Pin Payments: Pin Payments rechazó los datos del cargo, por ejemplo un importe inferior a su cargo mínimo para la moneda. El cliente ve el motivo, y el registro contiene el código de error.

El reembolso falla: lee el mensaje del bloque. Un mensaje sobre el modo TEST o LIVE significa que la clave secreta del modo en el que se pagó el pedido está vacía. Pin Payments did not confirm the refund significa que no llegó ninguna respuesta; comprueba el cargo en el panel de Pin Payments antes de volver a intentarlo. at most muestra el importe que aún se puede reembolsar del cargo.

Pagos de prueba: el modo de prueba usa el entorno de prueba y las claves de prueba. Usa las tarjetas de prueba de la documentación para desarrolladores de Pin Payments, por ejemplo 4200 0000 0000 0000 (correcta) o 4100 0000 0000 0001 (rechazada), con cualquier fecha de caducidad futura y cualquier CVC. Los pedidos conservan el modo en el que se pagaron, así que los reembolsos van al entorno correcto aunque cambies de modo.

Dónde encontrar los errores: los errores siempre se escriben en el registro; consulta el campo Log en la página del módulo. Activa Debug log para ver cada llamada a la API.

Desinstalación

Ve a Modules > Module Manager, abre el menú junto a VibeFox Pin Payments Gateway y elige Uninstall. La clave de licencia y el estado de 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 cargos y reembolsos de Pin Payments y el estado de pedido Pin Payments payment on hold siempre se conservan, así que los pedidos pagados antes pueden reembolsarse después de una reinstalación. Los pedidos existentes conservan sus notas de pago y sus ID de transacción.

Pin Payments es una marca comercial de su respectivo titular. Este módulo no está afiliado a Pin Payments ni cuenta con su respaldo.