MevvPos Documentation

Instalación

MevvPos necesita WordPress 6.0+, PHP 8.1+ y WooCommerce 9.0 o superior. WooCommerce es una dependencia estricta, declarada en la cabecera del plugin: sin él, WordPress rechaza la activación, y en versiones antiguas de WordPress el plugin simplemente no hace nada.

Suba el plugin en Plugins → Añadir nuevo → Subir plugin y actívelo.
Abra MevvPos en el menú lateral de administración. También hay un acceso directo bajo WooCommerce, donde los comerciantes suelen buscar los ajustes de pago.
En la pestaña General, active el método de pago y ponga el título que el cliente verá al finalizar la compra.
En API del banco, elija su banco e introduzca las credenciales que le dio.
En Plazos y comisiones, introduzca sus tasas de plazos.
Pruebe con las credenciales de test de su banco antes de pasar a producción.

La edición gratuita no crea tablas en la base de datos ni registra ninguna tarea programada. Todo vive en las opciones de WordPress y en los metadatos del pedido.

Pro es un plugin aparte, que se instala junto al gratuito — no lo sustituye. El plugin gratuito se publica en WordPress.org, donde todo lo publicado puede redistribuirse bajo la GPL; mantener el código de pago en el mismo paquete lo habría hecho legalmente redistribuible por cualquiera que borrase las comprobaciones de licencia. La clave de licencia se introduce en la pestaña Licencia.

Abrir WooCommerce → Ajustes → Pagos → MevvPos le redirige a la pantalla de MevvPos. Es deliberado: hay un solo lugar para estos ajustes, no dos que puedan contradecirse.

Cómo funciona

Usted define uno o más registros de POS. Un registro de POS es el POS virtual de un banco: sus credenciales, su dirección de pasarela, sus tasas de cuotas.
En el proceso de pago, el cliente teclea su tarjeta. Los primeros seis dígitos — el BIN — identifican al banco que la emitió.
MevvPos busca el BIN y envía el pago a su POS en ese banco, si tiene uno. Si no, recae en su POS predeterminado.
Las cuotas se ofrecen solo cuando la tarjeta pertenece al propio banco de ese POS, porque los bancos no conceden cuotas con tarjetas de otro banco.
El cliente pasa por 3-D Secure en el banco, y el banco vuelve a una única dirección de retorno en su sitio.
La firma del retorno se verifica con la clave del POS que el pedido realmente usó, el pedido se completa y el resultado queda registrado.

El número de tarjeta, la fecha de caducidad y el CVV nunca se escriben en su base de datos ni en la sesión de WooCommerce. Los únicos datos de tarjeta que se conservan son los primeros seis dígitos y el nombre del banco reconocido.

Registros de POS

La barra de POS está encima de las pestañas y se ve en todas ellas. Cada tarjeta muestra el banco, el número de comercio y un distintivo cuando algo requiere su atención.

Predeterminado: El POS que cobra cuando no se encuentra una coincidencia mejor. Siempre hay exactamente uno.
Inactivo: Se conserva pero no cobra. Use esto en lugar de borrar cuando un POS está configurado pero aún no está activo en el banco — de otro modo, un cliente con una tarjeta de ese banco no podría pagar.
A la espera de licencia: El registro existe pero está inactivo porque la licencia no está activa. No se ha borrado nada; se retoma donde lo dejó cuando se renueva la licencia.
No se han introducido los datos de la API: El registro todavía no tiene número de comercio.

Los bancos se muestran con una franja de color en lugar de un logotipo. Los logotipos de banco son marcas registradas, y quince de ellos son a la vez exposición legal y mantenimiento permanente — usted ya sabe cuál es su banco.

El último POS no se puede eliminar y el último habilitado no se puede desactivar. Para dejar de aceptar pagos con tarjeta por completo, desactive el método de pago en la pestaña General.

La edición gratuita permite un POS. Los registros adicionales son una capacidad de Pro — y por tanto, como consecuencia, también el enrutamiento por BIN: con un solo POS no hay nada entre lo que enrutar.

API del banco — credenciales y dirección de la pasarela

Banco: Elija el banco con el que está su POS. Tanto la dirección de la pasarela como la lista de BIN usada para las cuotas dependen de esta elección. Las entidades sin implementación todavía aparecen con “— yakında” (próximamente) y no se pueden seleccionar.
Número de comercio (Client ID): El número de comercio que le dio el banco.
Clave de comercio (store key): La clave de seguridad del comercio. Se guarda como campo de contraseña; una vez guardada se muestra enmascarada.
Gate URL: La dirección a la que el formulario de pago envía los datos.
Activar el modo de pruebas: Detiene la redirección automática para que pueda inspeccionar la petición antes de que se envíe.

Dejar la Store Key en blanco al guardar significa “no la cambies”. Escribir el valor en blanco borraría la clave y su tienda dejaría de aceptar pagos sin un solo mensaje de error. La misma regla se aplica a los demás campos secretos.

Algunas familias necesitan credenciales adicionales, y el formulario las muestra solo para el banco que eligió:

Garanti BBVA — Merchant ID, nombre de usuario de autorización, contraseña de autorización.
VakıfBank — Terminal No, y una dirección MPI (déjela vacía para usar la dirección de prueba).
PayTR — Merchant Salt.
iyzico, Craftgate, Sipay — sin campos adicionales: la clave de API va en Número de comercio y el secreto en Clave de comercio.

Estas credenciales adicionales entran en la firma. Si falta una, la firma se calcula con un valor vacío y el banco rechaza el pago en silencio — sin error, sin mensaje, solo una denegación.

Para los siete bancos NestPay, la dirección de la pasarela se rellena a partir de su elección de banco, así que puede dejar Gate URL vacío. Para los demás el campo no viene rellenado: introduzca la dirección que le dio su banco o proveedor, o el formulario de pago no tendrá adónde enviar los datos.

Las trece entidades compatibles

NestPay / Asseco (Payten): İş Bankası, Akbank, Halkbank, QNB, Şekerbank, TEB, Ziraat Bankası
Garanti GT3D: Garanti BBVA
PayFlex V4: VakıfBank
Entidades de pago: iyzico, PayTR, Craftgate, Sipay

Las entidades sin implementación permanecen a propósito en la lista de bancos, marcadas como «— yakında». Quitarlas ocultaría qué familias de protocolo siguen faltando. Si la suya es una de ellas, la pestaña Solicitud de banco es donde decirlo.

Solo la firma NestPay tiene una prueba de vector de referencia frente al propio ejemplo publicado por el banco. Todos los demás proveedores están marcados como beta en su propio código: el flujo está implementado según la documentación, pero todavía no se ha verificado de extremo a extremo con una cuenta de comercio real en esa entidad. Esa etiqueta se mantiene hasta que se haga.

Las entidades de pago no emiten tarjetas, así que no llevan lista de BIN. Se seleccionan como su POS en lugar de enrutar hacia ellas.

Enrutamiento basado en BIN

Los primeros seis dígitos de una tarjeta identifican al banco que la emitió. MevvPos hace coincidir exactamente esos seis dígitos.

Dentro del plugin viaja una instantánea de la tabla de BIN — 1.449 BIN de 36 bancos en la versión actual — de modo que el enrutamiento funciona sin conexión, en la edición gratuita, desde el momento en que lo instala.
Pro la actualiza cada semana desde nuestros servidores. La actualización se fusiona sobre la tabla empaquetada en lugar de sustituirla: una respuesta parcial o vacía no debe dejar nunca a una tienda sin datos de BIN.
Una respuesta que traiga menos de cien BIN se rechaza por inverosímil y no se escribe.
Los conflictos — el mismo BIN reclamado por dos bancos — se resuelven en nuestro lado antes de enviar la lista. Una tienda que los resolviera localmente podría contar una tarjeta como “nuestra” y enrutarla a otro sitio al mismo tiempo.

Un BIN no reconocido nunca se rechaza. Cae en su POS predeterminado. Rechazar una tarjeta que simplemente no tenemos fichada sería perder una venta para proteger una tabla de consulta.

La misma tabla responde a una segunda pregunta, distinta, en el proceso de pago: ¿es esta tarjeta del propio banco de este POS? Eso es lo que decide si se ofrecen cuotas — véase más abajo.

La exactitud de los BIN no es una función de pago. Lo que Pro paga es la actualidad, no la corrección: la lista empaquetada es la misma lista, solo congelada en el momento de la compilación.

Cuotas y comisión

Las tasas se fijan por POS, desde el pago único hasta doce plazos, en la pestaña Plazos y comisiones. Son porcentajes: escriba 5.50 para 5,5%.

0: La opción se muestra y no se añade comisión.
Vacío: La opción no se muestra en absoluto. Vacío y cero no son lo mismo.

La comisión aparece en el carrito como una tarifa sujeta a impuestos llamada “N Taksit Komisyonu” (comisión de N cuotas), calculada sobre el total del carrito incluidos envío e impuestos.

Las cuotas se ofrecen solo con tarjetas emitidas por el propio banco de ese POS, y esto se aplica en el servidor — no se limita a ocultarse en la interfaz. Una tarjeta de otro banco se fuerza de vuelta al pago único y la tarifa se elimina.

La edición gratuita muestra al cliente como máximo tres cuotas; Pro sube el techo a doce. El techo se aplica en tres puntos: la lista que ve el cliente, el valor que llega con el formulario y el valor enviado al banco. Este último importa porque un valor elegido cuando la licencia aún era válida puede sobrevivir en la sesión.

El formulario de ajustes siempre muestra los doce campos, sea cual sea su licencia. Si desaparecieran al caducar una licencia, guardar la página borraría en silencio tasas que ya había introducido. Los campos por encima de su límite se marcan como «Se desbloquea en Pro» y sus números se conservan.

No hay ninguna tabla de cuotas suministrada por el banco. Las tasas son las que usted introduce, y la comisión de un pedido pasado se calcula con la tasa que se aplicaba el día de la venta — cambiar una tasa hoy no reescribe el informe de ayer.

El flujo de pago y el tratamiento de la tarjeta

Todas las familias pasan por 3-D Secure. No hay modo sin 3D ni ajuste para desactivarlo.

Flujo por formulario: NestPay, Garanti, PayTR y Sipay: el navegador envía un formulario firmado al banco, el cliente se autentica y el banco vuelve a su sitio.
Flujo por servidor: VakıfBank, iyzico y Craftgate: su servidor habla con el proveedor, obtiene la página 3-D, la muestra y completa la venta de servidor a servidor tras la autenticación.

El banco siempre vuelve a una única dirección de su sitio: ?wc-api=mevvpos_callback. La firma de ese retorno se verifica con la clave del POS que el pedido realmente usó, registrada en el propio pedido — con más de un POS, verificar con la clave equivocada produce un error de hash en absolutamente todos los pagos.

La tarjeta nunca llega a su base de datos. Se mantiene en el navegador durante lo que dura la redirección y se elimina después. Si no está allí cuando se carga la página de pago — una pestaña nueva, una recarga, el almacenamiento deshabilitado, una vuelta atrás desde el banco — se muestra un formulario de tarjeta visible en lugar de enviar campos vacíos al banco. El formulario de tarjeta es visible por defecto, a propósito: un flujo de pago no puede depender de que JavaScript se haya ejecutado.

Cuando el banco aprueba el pago, el pedido se completa aunque el código de estado 3-D fuera inesperado — una nota de pedido registra la anomalía y le pide que la confirme desde la propia pantalla del banco. Si el banco dice aprobado, al cliente ya se le ha cobrado; rechazarlo significaría “se le cobró la tarjeta pero su pedido falló”.

Cada intento registra el POS usado, el banco y el BIN de la tarjeta, el número de cuotas y la tasa, el resultado, el código y el mensaje de respuesta del banco, y las referencias de autorización y de transacción.

Informes

La pestaña Informes muestra los ingresos, las transacciones correctas, la tasa de éxito y el reparto entre pago único y plazos, con un gráfico diario. Las transacciones que aún esperan respuesta del banco se cuentan aparte y quedan fuera de la tasa de éxito.

La edición gratuita informa sobre una ventana fija de 30 días. Pro añade rangos de 7 / 30 / 90 días y tres desgloses:

Carga de cuotas y comisiones — número, ingresos y carga de comisión por nivel de cuotas.
Desglose por POS y banco — ingresos, éxitos, fallos y tasa de éxito para cada POS y para cada banco emisor.
Distribución de códigos de rechazo — con exportación CSV. Un código de rechazo que se repite señala algo que usted puede arreglar: fondos insuficientes es problema del cliente, pero los errores de verificación 3-D y de configuración del POS son suyos.

Los datos que hay detrás de los informes los recoge el plugin gratuito, así que el historial se sigue acumulando tenga o no Pro. Tiene que ser así: los datos pasados no se pueden generar retroactivamente cuando actualiza.

Una tienda recién instalada no tiene gráfico. El registro empieza con el plugin, y la pantalla se llena tras el primer intento de pago.

Solicitudes de banco y soporte

Solicitud de banco: Enumera todas las entidades que aún no están implementadas, con el motivo: o bien no se ha determinado la familia de protocolo, o bien la familia se conoce y estamos esperando la documentación. Puede abrir una solicitud para una de ellas, o nombrar una entidad que no esté en la lista en absoluto.
Soporte: Un asunto, el POS o el banco en cuestión, qué ocurre cuando hace qué, y el mensaje de error que mostró el banco.

El formulario de soporte le pide que no incluya ningún número de tarjeta ni código de seguridad. Nunca hacen falta para diagnosticar un problema de pago, y con ninguno de los dos formularios se envía dato alguno de pago o de tarjeta.

El plugin gratuito contacta con nuestros servidores solo cuando usted pulsa uno de estos botones. No se envía nada de forma programada y en la edición gratuita no hay ninguna llamada de licencia.

Free y Pro

La separación está en la cantidad, no en la capacidad. Las trece entidades, 3-D Secure, el modo de prueba, un volumen de transacciones ilimitado y el informe básico de ingresos están en la edición gratuita.

Free: Un POS. Hasta tres cuotas mostradas al cliente. Un resumen de ingresos fijo de 30 días. La tabla de BIN empaquetada con el plugin.
Pro: Registros de POS ilimitados — y por tanto enrutamiento por BIN. Hasta doce cuotas. Rangos de informe y desgloses por POS, banco, cuotas y código de rechazo, con exportación CSV. Actualización semanal de los BIN en vivo. Actualizaciones automáticas para el propio plugin Pro.

Cuando una licencia expira o falta:

Su tienda sigue cobrando. No hay ninguna comprobación de licencia en el camino del pago. Cortar los ingresos de una tienda no es una forma aceptable de enviar un recordatorio de renovación.
El POS predeterminado sigue funcionando, incluidos 3-D Secure y el modo de prueba.
Los registros de POS adicionales quedan inactivos pero nunca se borran, credenciales incluidas. Se reanudan al renovar.
El techo de cuotas vuelve a bajar a tres. Las tasas que introdujo por encima de él se conservan, no se borran.
Los informes vuelven al resumen de 30 días. El historial recopilado no se borra.
La actualización de BIN en vivo se detiene; la tabla empaquetada sigue funcionando.

Si nuestros servidores no están accesibles, una licencia activa sigue funcionando durante siete días apoyándose en la última comprobación correcta. Pero una licencia cuya propia fecha de vencimiento ha pasado se lee como caducada de todos modos — de lo contrario, bloquear nuestra dirección sería una manera de alargar una licencia una semana.

Cuando algo no funciona

El banco rechaza todos los pagos sin ningún mensaje útil: Casi siempre es la firma. Una firma incorrecta no genera ningún error en ninguna parte — el banco simplemente deniega. Compruebe el número de comercio, la clave del comercio y las credenciales adicionales de esa familia: todas entran en la firma. Una prueba útil es que los bancos responden de forma distinta a un error de firma y a una tarjeta no válida; recibir un mensaje de “tarjeta no válida” significa que su firma es correcta.
“Error de hash” en el retorno, con más de un POS: El retorno es una petición aparte, sin sesión. MevvPos registra qué POS usó cada pedido y verifica con esa clave. Si borró el registro de POS por el que se pagó un pedido, la verificación recae en el POS predeterminado y puede fallar.
El cliente llega a una página de pago en blanco, o el botón Öde (Pagar) no hace nada: Un plugin de caché o de optimización está aplazando los scripts. En LiteSpeed, excluya mevvpos, jquery y los scripts públicos de WooCommerce de la lista de retardo. El formulario de tarjeta se muestra por defecto para que el flujo siga funcionando, pero la redirección automática no.
El pedido se queda en “pendiente” tras un pago correcto: El banco o el proveedor no llegó a la dirección de retorno. Compruebe que ?wc-api=mevvpos_callback es accesible desde fuera — un modo de mantenimiento, una restricción por IP o un muro de inicio de sesión delante del sitio lo bloquearán.
El formulario de pago se envía a la misma página: El campo Gate URL está vacío para un banco cuya dirección no viene rellenada. Introduzca la dirección que le dio su banco o proveedor.
El modo de prueba está activado pero el pago sigue yendo al banco real: El modo de prueba detiene la redirección automática y le muestra la petición; no reescribe la dirección de la pasarela para los bancos NestPay. Ponga la dirección de prueba de su banco en Gate URL mientras esté probando.
Las cuotas no aparecen: O la tasa de ese número de cuotas está vacía en lugar de a cero, o la tarjeta es de otro banco, o está por encima del techo de tres de la edición gratuita.
Las tarjetas van al POS equivocado tras una actualización: Las versiones antiguas llevaban rangos de BIN escritos a mano que en parte eran incorrectos. Compruebe que cada POS está archivado bajo el banco con el que realmente está.
La pantalla de administración se ve sin estilos, o una corrección no aparece: Una caché del navegador obsoleta. Recargue la página saltándose la caché.

Límites

La lista de abajo es deliberada. Nada de eso es un error.

Sin reembolsos ni cancelaciones desde WordPress. El plugin no implementa la API de reembolsos de WooCommerce y ningún proveedor incluye una llamada de reembolso. Haga el reembolso desde la pantalla de su propio banco.
Solo lira turca. El código de moneda está fijado en todos los proveedores; no hay ningún ajuste multidivisa.
Sin tarjetas guardadas, sin tokenización, sin suscripciones ni pagos recurrentes.
Sin preautorización. Toda transacción es una venta directa.
Sin enrutamiento basado en reglas. El enrutamiento es solo por banco emisor — no por importe, marca de tarjeta o país.
El formulario de pago está escrito para el proceso de pago clásico de WooCommerce. El paquete no incluye ningún componente aparte para el Checkout basado en bloques.
3D Pay Hosting se descartó a propósito. La página alojada elimina el alcance PCI, pero también elimina el BIN y la tabla de cuotas — y todo el valor de este plugin está en el enrutamiento que ambos hacen posible.
Sin editor de BIN. La tabla la gestionamos nosotros y se fusiona con la actualización en vivo; no hay ninguna pantalla para editarla a mano.
Hay veintiséis entidades listadas pero no implementadas. Siguen visibles para que la carencia sea visible.
Todos los proveedores salvo NestPay están declarados beta por nosotros mismos hasta que se hayan verificado de extremo a extremo con una cuenta de comercio real.
Las pestañas están dentro de la página. Las entradas de la barra lateral abren la pantalla de MevvPos; cambie de pestaña en la propia página.

Lo que nunca se almacena, de ninguna forma: el número de tarjeta, la fecha de caducidad y el código de seguridad. Los únicos datos de tarjeta que se conservan son los primeros seis dígitos y el banco que identifican. Guardar el código de seguridad está prohibido en cualquier circunstancia, e incluso enmascarado revela su longitud.

De un solo POS virtual a una tarjeta enrutada al banco que la emitió.