Category: Prestashop

Integrar una pasarela de pago en PrestaShop puede parecer sencillo sobre el papel.

La pasarela de pago proporciona documentación de la API, credenciales de entorno de pruebas, claves de autenticación, URL de devolución de llamada y algunos puntos finales. El módulo de PrestaShop envía la solicitud de pago, recibe la respuesta, crea el pedido y redirige al cliente a la página de confirmación.

Sin embargo, en una tienda PrestaShop real, la pasarela de pago rara vez funciona de forma aislada.

En el momento en que una tienda utiliza un módulo de pago en una sola página (OPC, por sus siglas en inglés), como SuperCheckout, múltiples módulos de pago, flujos de pago personalizados, iframes, métodos de pago basados ​​en JavaScript y personalizaciones adicionales del proceso de pago pueden interactuar entre sí.

Aquí es donde muchas integraciones de pago se complican.

Durante el proceso de compatibilidad de la pasarela de pago, nos hemos encontrado con casos en los que un método de pago funcionaba perfectamente con el proceso de pago predeterminado de PrestaShop, pero se comportaba de forma diferente dentro de OPC. Por ejemplo, un proveedor de pago podía mostrarse correctamente en el proceso de pago estándar, mientras que opciones como BLIK, selección bancaria o BNPL desaparecían en SuperCheckout.

La lección importante fue que integrar una pasarela de pago no se trata solo de hacer que la llamada a la API funcione, sino de lograr que todo el ciclo de pago funcione correctamente dentro del proceso de pago de PrestaShop.

1.0 ¿Qué necesita realmente una pasarela de pago personalizada?

A grandes rasgos, una integración de pago para PrestaShop debe gestionar cinco aspectos:

1. Mostrar el método de pago al finalizar la compra.
2. Envíe los datos del cliente o del pago a la pasarela de pago.
3. Recibir y validar la respuesta de la puerta de enlace.
4. Crea o actualiza correctamente el pedido de PrestaShop.
5. Redirija al cliente a la página de confirmación o de error correspondiente.

Un módulo de pago típico extiende la clase base en lugar de hacerlo.

El módulo de pago normalmente funciona con ganchos como:

El hook es responsable de que el método de pago esté disponible en la página de pago.

El gancho gestiona lo que el cliente ve después de regresar del proceso de pago.

Por ejemplo:

public function hookPaymentOptions($params) { if (!$this->active || !$this->checkCurrency($params['cart'])) { return []; } $paymentOption = new PaymentOption(); $paymentOption ->setCallToActionText($this->l('Pagar con tarjeta')) ->setAction( $this->context->link->getModuleLink( $this->name, 'redirect', [], true ) ); return [$paymentOption]; }

Lo importante es que este gancho no debe simplemente asumir que el método de pago siempre se puede mostrar.

La moneda, el país, el operador, el estado del cliente, el importe del carrito, la configuración del módulo y la disponibilidad de la pasarela de pago pueden influir en si se debe mostrar o no el método de pago.

2.0 La pieza que lo cambia todo: OPC

El proceso de pago predeterminado de PrestaShop y un módulo OPC no necesariamente procesan los métodos de pago exactamente de la misma manera.

Esta fue una de las lecciones más importantes que aprendí al trabajar con múltiples módulos de pago.

Con el proceso de pago predeterminado, un módulo de pago generalmente controla la representación de sus opciones de pago y el flujo de pago.

Con un OPC, el módulo de pago se convierte en otra capa entre el módulo de pago y el cliente. Esto significa que pueden interactuar los siguientes elementos:

El cliente
↓
OPC / SuperCheckout
↓
Opciones de pago
↓
Módulo de pago
↓
API de puerta de enlace
↓
Respuesta de puerta de enlace
↓
Módulo de pago
↓
OPC / PrestaShop
↓
Confirmación del pedido

Por lo tanto, un módulo de pago puede ser completamente correcto desde la perspectiva de la API y aun así no comportarse correctamente dentro de un OPC.

Por eso, las pruebas de compatibilidad de pagos siempre deben incluir ambos:

• Pago predeterminado de PrestaShop
• El OPC real utilizado por la tienda

Probar únicamente el proceso de pago predeterminado puede dar la falsa impresión de que la integración está completa.

3.0 Un ejemplo real: Faltan opciones de PayU en OPC

Uno de los problemas prácticos con los que nos encontramos estaba relacionado con las opciones de pago de PayU.

En el proceso de pago estándar de PrestaShop, PayU mostraba correctamente los métodos de pago disponibles. Sin embargo, en SuperCheckout faltaban algunas opciones de pago.

Por ejemplo, dependiendo de la configuración y del carrito:

• BLIK no era visible de forma constante.
• La lista de selección de bancos no se expandió correctamente.
• Faltaban algunas filas de pago/BNPL.
• En algunos casos, BLIK aparecía y luego desaparecía.

A primera vista, parecía un problema de la API de PayU. Pero no lo era.

El paso diagnóstico clave consistió en comparar el flujo de pago entre el proceso de pago predeterminado y SuperCheckout.

Cuando el mismo módulo de pago funciona en el proceso de pago predeterminado pero falla dentro de OPC, la investigación debe ir más allá de la API de la pasarela de pago.

Necesitamos comprobar cómo la OPC construye los métodos de pago y qué información transmite a los módulos de pago.

4.0 El importe del pago puede afectar a la visibilidad del método de pago.

Una parte particularmente importante de esta investigación fue el monto del carrito. Las pasarelas de pago suelen tener límites mínimos y máximos de transacción. Por ejemplo:

Método de Pago
↓
Comprobar el importe del carrito
↓
¿Cantidad mínima? ¿Cantidad máxima?
↓
Elegible / No elegible

Durante la investigación de compatibilidad de PayU, rastreamos la lógica de filtrado del método de pago hasta el importe del carrito que se procesaba mediante las comprobaciones del método de pago.

El flujo relevante implicaba el cálculo del carrito de PrestaShop y el filtrado de métodos de pago, incluyendo la lógica relacionada con:

Carrito::AMBOS

y:

PayMethodsCache::checkMinMax

Esto es importante porque una opción de pago puede desaparecer del proceso de compra sin que la propia API devuelva un error.

Es posible que la pasarela simplemente se considere no apta para el importe recibido por el módulo de pago. Esto nos proporciona una regla de depuración importante:

Si una opción de pago desaparece de un OPC, no asuma de inmediato que la API de pago está fallando. Primero verifique el monto del carrito, la moneda, los límites mínimo y máximo, y los valores que cumplen con los requisitos de elegibilidad del método de pago.

Esto cobra aún más importancia cuando intervienen descuentos, gastos de envío, impuestos, cupones o cálculos de pago personalizados.

5.0 Por qué los métodos de pago pueden funcionar en el proceso de pago predeterminado pero fallar en SuperCheckout

Una forma útil de investigar estos problemas es comparar los dos entornos de pago.

5.1 Proceso de pago predeterminado de PrestaShop

Carrito
↓
Buscador de opciones de pago
↓
Ganchos de opciones de pago
↓
Módulos de pago
↓
Opciones de pago

5.2 Pago OPC

Carrito
↓
SuperCheckout
↓
Métodos de pago
↓
Módulos de pago
↓
Procesamiento OPC adicional
↓
Interfaz de usuario de pago renderizada

El segundo flujo tiene partes móviles adicionales.

Por lo tanto, al depurar un problema de pago, no solo comprobamos: “¿Funciona el módulo de pago?”.

Verificamos: “¿Funciona el módulo de pago cuando su salida es consumida y renderizada por esta implementación de pago en particular?”

Esa distinción ahorró una cantidad considerable de tiempo de depuración.

6.0 PaymentOption es solo una parte de la integración.

A partir de PrestaShop 1.7, los módulos de pago generalmente utilizan la generación de HTML de pago a través del método de gancho de pago anterior.

Una opción de pago puede contener información como:

$opción de pago
->establecerCallToActionText(...)
->establecerAcción(...)
->establecerEntradas(...)
->establecerInformaciónAdicional(...)

objetos en lugar de directamente

Las distintas pasarelas requieren diferentes combinaciones.

6.1 Puerta de enlace basada en redireccionamiento

El cliente hace clic en el método de pago y es redirigido a la pasarela de pago.

Finalizar Compra
↓
Opción de pago
↓
Controlador de módulo
↓
Gateway

6.2 Formulario de pago integrado

Los campos de pago se muestran directamente en la página de pago.

Finalizar Compra
↓
Opción de pago
↓
Tarjeta/formulario de pago
↓
API de puerta de enlace

6.3 Pago basado en iframe

La interfaz de la pasarela de pago está integrada en el proceso de compra.

Finalizar Compra
↓
Opción de pago
↓
Iframe
↓
Gateway

Los dos últimos enfoques requieren atención adicional porque JavaScript, la manipulación del DOM, la carga de iframes y las actualizaciones de OPC pueden afectar la interfaz de pago.

7.0 JavaScript se vuelve fundamental con OPC

Esta es un área que las guías genéricas de integración de pagos suelen pasar por alto.

Un OPC puede actualizar dinámicamente partes del proceso de pago cuando el cliente cambia:

• dirección de entrega
• país
• portador
• método de pago
• Datos de facturación
• Método de envío

Cuando eso sucede, se puede reemplazar el código HTML relacionado con el pago.

Por lo tanto, un evento de JavaScript que funcionaba durante la carga inicial de la página puede dejar de funcionar después de una actualización mediante AJAX.

Por ejemplo:

Carga inicial del proceso de pago
↓
Pago JS inicializado
↓
El cliente modifica la información de pago/envío.
↓
OPC actualiza la sección de pagos
↓
DOM original reemplazado
↓
El pago JS ya no está adjunto

Esto puede producir síntomas confusos.

El método de pago puede aparecer inicialmente, pero al hacer clic en él no sucede nada. El iframe puede desaparecer.

Es posible que la lista de bancos deje de ampliarse.

Una opción de pago puede aparecer y desaparecer después de que cambie otro campo del proceso de compra.

Por lo tanto, el trabajo de compatibilidad a menudo requiere cambios no solo en PHP, sino también en el JavaScript del módulo de pago.

8.0 Un ejemplo real: SimplyLease + SuperCheckout

Otro ejemplo involucró la integración de SimplyLease con SuperCheckout. El problema no se limitaba a la API de la pasarela de pago.

Algunos elementos de la información y la calculadora de SimplyLease formaban parte de la presentación de pago y debían funcionar correctamente dentro del flujo de SuperCheckout.

Los cambios de compatibilidad afectaron tanto a las plantillas de módulos como a la integración de JavaScript del lado de SuperCheckout. Los archivos afectados incluyeron:

módulos/simplylease/views/templates/hook/payment_info.tpl módulos/simplylease/views/templates/hook/product_calculator.tpl

módulos/supercheckout/controladores/front/SupercheckoutCore.php módulos/supercheckout/vistas/js/front/supercheckout.js
módulos/supercheckout/views/js/front/simplylease_supercheckout.js

Este es un buen ejemplo de por qué la compatibilidad de pagos a veces requiere cambios fuera del propio módulo de la pasarela de pago.

El proveedor de pagos puede exponer los datos correctos, pero el proceso de pago aún debe:

1. Renderízalo.
2. Consérvelo durante las actualizaciones del proceso de pago.
3. Inicialice el JavaScript necesario.
4. Mantén la información de pago sincronizada con el carrito actual.

9.0 Otro problema común: El método de pago no aparece.

También nos encontramos con casos en los que un método de pago como Comfino no aparecía en SuperCheckout a pesar de que el módulo de pago estaba instalado y configurado.

Este tipo de problema debe investigarse sistemáticamente.

Comprobar:

9.1 ¿Está activo el módulo?

$this->activo

9.2 ¿Se admite la moneda?

$this->checkCurrency($params['cart'])

9.3 ¿El país cuenta con apoyo?

Algunas pasarelas de pago restringen los métodos de pago en función del país del cliente.

9.4 ¿El total del carrito está dentro de los límites de la pasarela de pago?

Los valores mínimos y máximos de transacción pueden impedir que se muestre un método.

9.5 ¿Es compatible el operador?

Algunos módulos de pago restringen los métodos de pago según el operador.

9.6 ¿El filtrado OPC es el método?

El módulo de pago puede devolver métodos válidos que se recopilan, filtran o muestran. Pero la OPC aún puede modificar la forma de pago

9.7 ¿JavaScript está ocultando o reemplazando el elemento?

Un método de pago puede ser devuelto técnicamente por PHP, pero aun así no ser visible en el proceso de pago final.

Por eso, las herramientas para desarrolladores del navegador son tan importantes como los registros de PHP a la hora de depurar las integraciones de pago.

10.0 Ganchos a los que realmente debemos prestar atención

Una integración de pago personalizada no debe tratarse como una implementación de un solo punto de acceso.

Los puntos de activación exactos dependen de la arquitectura de la pasarela de pago y del proceso de compra, pero algunos son especialmente importantes.

10.1 Opciones de pago

Este es el gancho principal para mostrar el método de pago al proceso de compra.

Es responsable de devolver Opciones de pago objetos.

Las comprobaciones típicas incluyen:

si (!$this->active) { return [];
}
if (!$this->checkCurrency($params['cart'])) { return [];
}

Posteriormente, se pueden aplicar restricciones adicionales específicas para cada puerta de enlace.

10.2 Devoluciones de pago

Esto se utiliza después de que el cliente haya completado o regresado del proceso de pago. Puede mostrar:

• referencia de pedido
• estado de pago
• Instrucciones de pago adicionales
• Información específica de la puerta de enlace

10.3 acciónPresentarOpcionesDePago

Este gancho resulta particularmente interesante cuando intervienen varios módulos de pago y un OPC.

Funciona sobre las opciones de pago recopiladas y puede resultar útil cuando el proceso de pago necesita inspeccionar o modificar la colección completa de opciones de pago.

Esto es diferente a implementar las opciones de pago de una sola pasarela. gancho.

La distinción es importante:

Opciones de pago
↓
Cada módulo de pago aporta su opción
acciónPresentarOpcionesDePago
↓
Las opciones de pago ensambladas se pueden procesar

Al depurar la compatibilidad con OPC, comprender dónde se recopilan las opciones de pago y dónde se presentan finalmente puede marcar la diferencia entre encontrar el problema rápidamente y pasar horas dentro del módulo de la pasarela de pago.

11.0 Creación de pedidos: Nunca confíes en el navegador.

Una vez que el pago llega a la pasarela de pago, el siguiente paso crítico es la creación del pedido. El método más importante de PrestaShop en este caso es:

validarOrden()

Un ejemplo simplificado es:

$this->module->validateOrder(
$cart->id, Configuration::get('PS_OS_PAYMENT'),
$cantidadPagada,
$método de pago,
$mensaje, [],
nulo, falso,
$cliente->clave_segura
);

Hay tres valores que merecen especial atención:

11.1 ID del carrito

El carrito debe pertenecer al cliente/sesión previsto y debe ser válido.

11.2 Importe del pago

No utilice a ciegas:

$cart->getOrderTotal()

como prueba de que la pasarela recibió esa cantidad.

El importe debe validarse con la respuesta de la pasarela de pago.

11.3 Clave segura

El cliente debe estar correctamente asociado con el flujo del carrito/pedido.

12.0 Los webhooks deben ser idempotentes.

Una pasarela de pago puede enviar el mismo webhook más de una vez. Por ejemplo:

Gateway
↓
web hook
↓
Su servidor
↓
200 respuesta

Si se pierde la respuesta:

Gateway
↓
web hook
↓
Su servidor
↓
Respuesta perdida
↓
Reintentos de puerta de enlace

Si la integración crea un pedido cada vez que recibe un webhook, es posible que se produzcan pedidos duplicados. Por lo tanto, la función de devolución de llamada debe verificar si el carrito ya tiene un pedido antes de crear otro. Conceptualmente:

Si ($cart->OrderExists()) {
// Ya procesado
// Devuelve una respuesta exitosa
}

El gestor de webhooks debe diseñarse para procesar de forma segura las notificaciones repetidas.

13.0 Pago síncrono frente a pago asíncrono

No todas las pasarelas de pago confirman el pago de inmediato.

13.1 Sincrónico

La pasarela de pago confirma la transacción de inmediato.

El cliente
↓
Gateway
↓
Pago aprobado
↓
validarOrden()
↓
PAGO DE PS_OS
↓
Confirmación

13.2 Asincrónico

El cliente puede devolver el producto antes de que llegue la confirmación del pago final.

El cliente
↓
Gateway
↓
Volver a la tienda
↓
Orden pendiente
↓
web hook
↓
Verificar pago
↓
Cambiar el estado de la orden
↓
Pago aceptado

Para las pasarelas asíncronas, utilizar un estado de orden pendiente dedicado suele ser más seguro que marcar la orden como pagada inmediatamente.

Una vez que el webhook confirma el pago:

$historial = nuevo historial de pedidos();
$history->id_order = (int) $order->id;
$history->changeIdOrderState( Configuration::get('PS_OS_PAYMENT'),
$orden
);
$history->addWithemail(true);

Esto garantiza que la transición del estado del pedido se realice a través del mecanismo de historial de pedidos de PrestaShop en lugar de simplemente cambiar el valor de la base de datos.

14.0 Una de las técnicas de depuración más útiles: Comparar los flujos de pago

Cuando un método de pago funciona en el proceso de pago predeterminado pero no en OPC, recomendamos comparar el flujo completo.

Paso 1: Comprobar PHP

¿Es hookPaymentOptions()? ¿ejecutado?

Paso 2: Inspeccione las opciones devueltas.

¿El módulo de pago realmente devuelve un opción de pago?

Paso 3: Revisa el carrito

Comparar:

• total
• moneda
• cliente
• país
• portador
• descuentos
• impuestos
• envío

Paso 4: Compruebe el navegador.

Buscar:

• Errores de JavaScript
• Elementos DOM faltantes
• solicitudes AJAX
• solicitudes fallidas
• errores de iframe

Paso 5: Compruebe el OPC

Determina si SuperCheckout es:

• filtrar la opción de pago
• reemplazando su HTML
• Actualizando la sección de pagos
• Modificar el carrito antes de que se ejecute el módulo de pago

Paso 6: Compruebe la puerta de enlace

Solo después de confirmar el flujo de pago local se debe profundizar en la investigación:

• Autenticación API
• carga útil de la solicitud
• firma
• respuesta
• webhook
• registros de la puerta de enlace

Este enfoque por capas es mucho más rápido que comenzar con la API de la puerta de enlace cada vez.

15.0 Problemas comunes de integración de pagos que hemos observado

Las pruebas de compatibilidad en entornos reales suelen revelar problemas que no resultan obvios a partir de la documentación del gateway.

15.1 La opción de pago desaparece

Posibles causas:

• moneda no admitida
• restricción por país
• El importe del carrito supera los límites de la pasarela de pago.
• restricción del transportista
• Filtrado OPC
• Configuración del módulo de pago
• JavaScript ocultando el método

15.2 BLIK u otra opción de pago aparece y desaparece

Posibles causas:

• Actualización AJAX del proceso de pago
• renderizado de la opción de pago
• Inicialización de JavaScript
• Cambio en el total del carrito
• Se está recalculando la elegibilidad para el acceso.

15.3 La lista de bancos no se amplía.

A menudo investigan:

• Errores de JavaScript
• elementos DOM reemplazados dinámicamente
• controladores de eventos adjuntos antes de la actualización de OPC
• Inicialización de JavaScript del proveedor de pagos

15.4 El iframe desaparece

Investigar:

• actualizar el pago
• inicialización de iframe
• reemplazo del DOM
• Ejecución de JavaScript después de las actualizaciones AJAX
  

15.5 El pago se realiza correctamente, pero el pedido sigue pendiente.

Comprobar:

• URL del webhook
• Entrega de webhook
• verificación de firma
• carrito/búsqueda de pedidos
• transición de estado de orden
• autenticación de devolución de llamada

15.6 El método de pago funciona en el proceso de pago predeterminado, pero no en OPC.

Esto indica claramente que el problema podría estar en la interacción entre el módulo de pago y el OPC, en lugar de en la propia API de la pasarela de pago.

16.0 Requisitos de seguridad para un módulo de pago

Los módulos de pago manejan operaciones sensibles, por lo que la seguridad no puede considerarse una mejora opcional. Como mínimo:

• Validar las firmas de las funciones de devolución de llamada.
• Validar la relación entre el carrito y el cliente.
• Utilice HTTPS.
• Validar certificados TLS.
• Nunca confíe en el estado de pago que proporciona únicamente el navegador.
• Nunca almacene información de tarjetas sin procesar a menos que la arquitectura y los requisitos de cumplimiento lo permitan explícitamente.
• No registre información de pago confidencial.
  

• Evite serializar() y unserializar(). / para datos externos no confiables.

• Validar y convertir los valores entrantes.
• Proteja los puntos finales AJAX y de devolución de llamada personalizados.
• Utilice tokens seguros cuando sea apropiado.
• Hacer que el procesamiento de webhooks sea idempotente.

Una página de confirmación de pago no constituye una prueba de pago.

La respuesta verificada del servidor de la pasarela de pago es lo que debería determinar si el pedido se considera pagado.

17.0 ¿Qué cambia al admitir múltiples módulos de pago?

Otra lección aprendida del trabajo de compatibilidad con OPC es que agregar un segundo o tercer módulo de pago puede revelar problemas que no eran visibles cuando solo existía un método de pago.

Por ejemplo:

PayPal PayU
Comfino
SimplyLease
transferencia bancaria

todas pueden aportar opciones de pago al mismo proceso de pago. Por lo tanto, el proceso de pago tiene que lidiar con diferentes:

• Estructuras HTML
• JavaScript
• Requisitos del iframe
• redirecciones
• flujos de API
• reglas de elegibilidad
• cantidades mínimas/máximas
• devoluciones de llamada asíncronas

Un cambio realizado en un método de pago puede afectar accidentalmente a otro. Por eso, las correcciones de compatibilidad de pagos deben tener un alcance limitado.

Por ejemplo, en lugar de cambiar globalmente toda la lógica de procesamiento de opciones de pago, identifique el método de pago específico y aplique el manejo de compatibilidad solo donde sea necesario.

18.0 Las pruebas deben incluir escenarios de carrito de compra reales.

Probar una pasarela de pago con un producto sencillo de 10 € no es suficiente. Una matriz de pruebas adecuada debería incluir:

Escenario	Qué verificar
solo producto	Aparece la opción de pago
Múltiples productos	La cantidad correcta llega a la puerta de enlace
Descuento	El importe final a pagar es correcto.
Costo de envío	Gateway recibe el total correcto
IVA	El importe de la pasarela coincide con el pedido.
Cantidad mínima de la pasarela	El método aparece/desaparece correctamente
Cantidad máxima de puerta de enlace	El método aparece/desaparece correctamente
Moneda no admitida	El método está oculto
País no respaldado	El método está oculto
Pago predeterminado	Trabajos de pago
OPC	Trabajos de pago
Pago móvil	La interfaz de usuario funciona
pago fallido	Estado correcto del pedido/pago
Pago exitoso	El pedido se ha creado correctamente.
Reintento de webhook	No se permite pedido duplicado
Abandono del cliente	No hay ningún pedido pagado incorrectamente.
Tiempo de espera de la puerta de enlace	Gestión correcta de errores/pendientes

Para las integraciones de OPC, pruebe también las actualizaciones del proceso de pago. Cambie lo siguiente:

• de facturación
• portador
• país
• método de pago
• la cantidad
• descuento

y verifique que las opciones de pago sigan siendo correctas después de cada actualización.

19.0 Un enfoque práctico para el desarrollo

En función de los problemas que suelen aparecer en las integraciones reales, un orden de desarrollo más seguro es el siguiente:

19.1 Hacer que la pasarela funcione con el proceso de pago predeterminado de PrestaShop.

Primero, establezca que:

Opción de pago
↓
Solicitud de puerta de enlace
↓
Respuesta de puerta de enlace
↓
validarOrden()
↓
Confirmación

funciona correctamente.

19.2 Agregar procesamiento de devolución de llamada/webhook

No deje la confirmación asíncrona para el final.

19.3 Agregar manejo adecuado del estado del pedido

Prueba:

• comercial
• el fracaso
• pendiente
• tiempo de espera

19.4 Prueba con carros realistas

Utilice descuentos, gastos de envío, impuestos, diferentes monedas y diferentes totales.

19.5 Integración con OPC

Solo después de que el flujo básico de la puerta de enlace sea estable, debería investigar la compatibilidad con SuperCheckout.

19.6 Pruebas de JavaScript y actualizaciones dinámicas

Esto es especialmente importante para los formularios de pago integrados, los iframes, las interfaces BLIK/de selección bancaria y otros componentes de pago interactivos.

19.7 Pruebe todos los métodos de pago juntos

Un sistema de pago que admite cinco métodos de pago debe probarse como un sistema completo, no como cinco módulos aislados.

20.0 ¿Debería crear una puerta de enlace personalizada o utilizar un módulo existente?

No todas las pasarelas justifican una integración personalizada. Un módulo personalizado tiene sentido cuando:

• La puerta de entrada es regional o de nicho.
• No existe ningún módulo de PrestaShop que reciba mantenimiento.
• La puerta de enlace requiere lógica de negocio personalizada.
• Necesitas un flujo de trabajo específico de suscripción o liquidación.
• Necesitas una funcionalidad que los módulos existentes no pueden proporcionar.

Pero integrar un sistema de pago también implica asumir la responsabilidad del mantenimiento. PrestaShop cambia.

PHP cambia. Las API de la puerta de enlace cambian.

Los requisitos de seguridad cambian. Los módulos de pago cambian.

Y, finalmente, el proveedor de pagos cambia algo que rompe una integración que, de otro modo, sería estable.

Por lo tanto, para las pasarelas de pago convencionales, un módulo establecido y mantenido puede resultar significativamente más económico que mantener un código de pago personalizado durante varios años.

21.0 La lección más importante de la integración de pagos de PrestaShop

La mayor lección que se aprende al trabajar con pasarelas de pago es que la API a menudo no es la parte más difícil. Enviando:

Solicitud de API → Respuesta API

Suele ser sencillo.

Lo difícil es todo lo que lo rodea:

┌── Reglas monetarias
├── Reglas del país
├── Cantidad del carrito
├── Restricciones del transportista
├── OPC
├── JavaScript
├── Iframes
├── Actualizaciones AJAX
├── Webhooks
├── Estados de orden
└── Notificaciones duplicadas
↓
El cliente → Finalizar Compra → Módulo de pago → Gateway
↓
Creación de pedidos
↓
Confirmación del pedido

La integración de un sistema de pago solo tiene éxito cuando toda la cadena se comporta de forma coherente.

Esta es también la razón por la que un problema como “BLIK no está disponible” o “la lista de bancos no se abre” no debe tratarse inmediatamente como un problema de la API de la puerta de enlace.

La causa real podría ser un cálculo del total del carrito, una comprobación de la elegibilidad del método de pago, la representación OPC, la inicialización de JavaScript o una actualización AJAX que sustituya la interfaz de pago.

22.0 Lista de verificación final para una pasarela de pago personalizada de PrestaShop

Antes de considerar que la integración está completa, verifique:

• El módulo de pago se extiende Módulo de pago.
• Opciones de pago Se implementa correctamente.
• Devolución de pago Se implementa donde sea necesario.
• Opciones de pago utilizadas Opciones de pago.
• Se comprueban las restricciones cambiarias.
• Se comprueban las restricciones del país y de la compañía aérea cuando corresponde.
• Los totales del carrito se validan.
• Las respuestas de la puerta de enlace se verifican.
• Las firmas de devolución de llamada se validan.
  
• ValidarOrden() Se llama solo después de que se haya verificado el pago correctamente.
• El importe utilizado para el pedido se valida con la respuesta de la pasarela de pago.
• Los webhooks son idempotentes.
• Las notificaciones duplicadas no generan pedidos duplicados.
• Se utilizan los estados de orden correcto.
• Los pagos fallidos y pendientes se gestionan por separado.
• Los datos de pago confidenciales nunca se registran ni se almacenan innecesariamente.
• Se exige el uso de HTTPS.
• Se ha probado el proceso de pago predeterminado de PrestaShop.
• OPC se ha probado por separado.
• Se ha probado JavaScript después de actualizar la página de pago mediante AJAX.
• Se han probado los iframes y los elementos de pago interactivos.
• Se han probado varios módulos de pago conjuntamente.
• Se han probado carritos de compra realistas con descuentos y gastos de envío.

Conclusión

Una pasarela de pago personalizada en PrestaShop es más que una simple integración de API.

La API es solo una parte de la implementación. El verdadero desafío de ingeniería comienza cuando el módulo de pago debe coexistir con el proceso de pago de PrestaShop, un sistema OPC como SuperCheckout, otros módulos de pago, JavaScript dinámico, recálculos del carrito y devoluciones de llamada asíncronas de la pasarela de pago.

Nuestra experiencia con los problemas de compatibilidad de pagos reforzó un enfoque importante: siempre hay que aislar dónde se produce el fallo antes de modificar el código.

Si PHP no devuelve el método de pago, investigue el módulo de pago y sus reglas de elegibilidad. Si PHP lo devuelve, pero el cliente no puede verlo, investigue el OPC y la representación del frontend. Si la interfaz de usuario aparece, pero no responde, investigue JavaScript y las actualizaciones AJAX. Si el pago se realiza correctamente, pero el pedido permanece pendiente, investigue la devolución de llamada y el flujo del estado del pedido.

Este enfoque es mucho más fiable que suponer que cada problema de pago es un problema de API.

Para los desarrolladores que trabajan en integraciones de pago para PrestaShop, el objetivo no debe ser simplemente lograr que una pasarela de pago acepte una transacción. El objetivo es garantizar la fiabilidad de todo el ciclo de pago, desde la primera visualización del proceso de compra hasta la confirmación final del pedido, incluso cuando intervienen varios métodos de pago y un OPC personalizado.