Back to guides INTEGRATIONS

Integración de Pasarela de Pago: Guía Completa para Desarrolladores y Empresas

Integrar una pasarela de pago es una de las decisiones técnicas más importantes que toma un negocio de comercio electrónico o un equipo de desarrollo. El método elegido determina el alcance PCI DSS, la tasa de conversión del proceso de pago, la capacidad de gestionar la autenticación 3D Secure y la rapidez con que se pueden incorporar nuevos métodos de pago. Esta guía cubre todas las vías de integración disponibles, desde una página alojada sin código hasta una API REST completa de servidor a servidor, y describe los pasos exactos necesarios para activar RoxPay. Tanto si eres desarrollador como si eres propietario de un negocio evaluando opciones, esta guía ofrece una visión completa.

Integración de Pasarela de Pago | RoxPay

Qué Significa la Integración de Pasarela de Pago para tu Negocio

Una integración de pasarela de pago es la conexión técnica entre tu sitio web o aplicación y la red de procesamiento de pagos que autoriza, captura y liquida transacciones con tarjeta. Sin ella, tus clientes no pueden pagar. Con una integración deficiente, pierdes ingresos por transacciones fallidas, flujos de pago con fricción y una mala experiencia en móvil.

La integración afecta a algo más que a los desarrolladores. Los propietarios de negocios deben entender que el método elegido determina su responsabilidad bajo PCI DSS, su capacidad para admitir métodos de pago locales y la velocidad a la que se pueden activar nuevas funciones como Apple Pay o transferencias de banca abierta. Una integración con página alojada traslada toda la gestión de datos de tarjeta fuera de tus servidores y minimiza la carga de cumplimiento. Una integración directa con API ofrece máximo control, pero coloca la gestión de datos de tarjeta en tu infraestructura, requiriendo un nivel mayor de certificación PCI.

Por qué la calidad de la integración importa para la conversión: La fricción en el proceso de pago es una de las principales causas de abandono del carrito. Una pasarela que requiere múltiples redirecciones y visitar un portal bancario separado convertirá peor que una experiencia de pago nativa e integrada. Las integraciones modernas con API REST permiten renderizar los campos de entrada de tarjeta directamente en tu página de pago sin que el cliente abandone el sitio, lo que mejora notablemente las tasas de finalización.

Para los comerciantes en verticales de alto riesgo que también necesitan una pasarela de pago de alto riesgo, la capa de integración es aún más importante porque las verificaciones adicionales, la aplicación de 3D Secure y los filtros antifraude interactúan con la forma en que se construye el formulario de pago y cómo se gestionan los eventos en el proceso.

Métodos de Integración: Página Alojada vs API vs SDK

Existen tres formas principales de integrar una pasarela de pago, cada una con diferentes equilibrios entre velocidad de implementación, alcance PCI DSS y flexibilidad de personalización.

Página de Pago Alojada: La opción más sencilla. Rediriges al cliente desde tu proceso de pago a una página alojada y gestionada por la pasarela. El cliente introduce los datos de la tarjeta en el dominio de la pasarela, no en el tuyo. Esto elimina casi todos los requisitos PCI DSS de tu parte porque nunca manejas datos de tarjeta. La desventaja es la personalización limitada y la experiencia de abandonar tu sitio a mitad del proceso de pago. Ideal para negocios que quieren empezar a aceptar pagos rápidamente con un esfuerzo de desarrollo mínimo.

IU Drop-in Integrada (iFrame o JS Elements): Un camino intermedio práctico. La pasarela proporciona un fragmento de JavaScript que inyecta campos seguros de entrada de tarjeta directamente en tu página de pago. Los campos se renderizan dentro de iframes alojados en el dominio de la pasarela, por lo que los datos de tarjeta nunca tocan tu servidor. Desde la perspectiva del cliente, el proceso de pago parece nativo de tu sitio. El alcance PCI es mínimo (SAQ A). Este es el enfoque recomendado para la mayoría de los negocios de comercio electrónico. RoxPay lo admite a través de su API REST y SDK frontend.

API Servidor a Servidor: Máximo control. Tu frontend recopila datos de tarjeta y tu servidor los envía directamente a la API de la pasarela. Esto requiere cumplimiento PCI DSS SAQ D, que implica auditorías de seguridad rigurosas y controles continuos. Es apropiado para plataformas que construyen productos de infraestructura de pagos, no para la mayoría de los comerciantes que procesan sus propias transacciones.

Plugins y Módulos de Plataforma: Para comerciantes que usan plataformas de comercio electrónico como Magento, PrestaShop o WooCommerce, los módulos prediseñados gestionan los detalles de integración dentro de la arquitectura de la plataforma. El método subyacente es típicamente una página alojada o IU drop-in, por lo que el alcance PCI se mantiene mínimo y el tiempo de implementación se mide en horas en lugar de días.

Paso a Paso: Cómo Integrar RoxPay mediante API REST

RoxPay proporciona una API REST con cuerpos de solicitud y respuesta en JSON. La documentación completa está disponible en app.roxpay.eu/api/v4/docs. La integración sigue un patrón estándar de intención de pago familiar para cualquier desarrollador que haya trabajado con APIs modernas de pasarelas.

Paso 1: Crea tu cuenta sandbox. Para iniciar tu solicitud en RoxPay, navega a la página de incorporación. Las credenciales de sandbox se emiten automáticamente al registrarse, sin necesidad de información de pago para comenzar las pruebas.

Paso 2: Autenticación. Todas las llamadas a la API usan tu clave API en el encabezado de autorización. Las claves están vinculadas a tu cuenta de comerciante y se pueden rotar desde el panel de control. Nunca expongas tu clave API en JavaScript del lado del cliente ni la incluyas en el control de versiones.

Paso 3: Crea una intención de pago. Envía un POST al endpoint de intención de pago con el importe, la moneda, los métodos de pago aceptados y una referencia de pedido única de tu sistema. La API devuelve un ID de intención de pago y un secreto de cliente para usar en el frontend.

Paso 4: Monta la IU drop-in. Pasa el secreto de cliente a la biblioteca RoxPay.js, que renderiza los campos de entrada de tarjeta en tu página. La biblioteca gestiona el formato del número de tarjeta, la validación, las redirecciones 3D Secure y los botones de Apple Pay o Google Pay según el soporte del navegador.

Paso 5: Gestiona el resultado. Al completarse el pago con éxito, la biblioteca activa una devolución de llamada de éxito. Tu frontend notifica a tu backend, que verifica de forma independiente el estado del pago mediante webhook antes de procesar el pedido. Nunca te bases únicamente en la confirmación del frontend para ejecutar pedidos.

Paso 6: Concilia mediante el panel de control. Todas las transacciones son visibles en tu panel de comerciante con detalle completo sobre el importe, las comisiones, el tipo de tarjeta y el estado de liquidación. Exporta a CSV o usa la API para la integración con sistemas de contabilidad.

Webhooks, Gestión de Errores y Pruebas en Sandbox

Los webhooks son la columna vertebral de una integración de pago confiable. Permiten a RoxPay notificar a tu servidor los eventos de pago de forma asíncrona, sin depender de que el navegador del cliente permanezca abierto o de que la conexión de red permanezca estable durante toda la transacción.

Configuración de webhooks: Registra un endpoint HTTPS en tu servidor en el panel de control. RoxPay enviará un payload JSON firmado a este endpoint para cada evento significativo: payment.completed, payment.failed, payment.refunded, chargeback.created y otros. Verifica la firma en cada webhook entrante usando la clave secreta que aparece en tu panel de control. Rechaza cualquier solicitud que no supere la validación de firma para prevenir ataques de repetición.

Idempotencia: Los webhooks pueden entregarse más de una vez debido a las condiciones de red. Tu endpoint debe procesar cada evento de forma idempotente, lo que significa que procesar el mismo evento dos veces produce el mismo resultado. Almacena el ID del evento y omite el procesamiento si ya lo has gestionado.

Gestión de errores en la API: RoxPay devuelve códigos de estado HTTP estándar. 200 para éxito, 400 para solicitudes incorrectas con parámetros inválidos, 401 para fallos de autenticación, 422 para errores de procesamiento como el rechazo de una tarjeta o fondos insuficientes. Inspecciona siempre el código de error en el cuerpo de la respuesta, no solo el estado HTTP, para distinguir entre un error técnico y un rechazo de lógica de negocio.

Pruebas en sandbox: El entorno sandbox refleja exactamente la producción. Usa los números de tarjeta de prueba proporcionados para simular transacciones aprobadas, rechazos, desafíos 3DS, fondos insuficientes, tarjetas caducadas y respuestas de tarjeta robada. Prueba tu gestión de webhooks activando cada tipo de evento en el sandbox antes de tocar producción. Confirma que tu IU de error funciona correctamente para cada escenario de rechazo que tus clientes puedan encontrar, no solo el camino feliz.

Lógica de reintento: Implementa retroceso exponencial en tu consumidor de webhooks. RoxPay reintenta los webhooks no entregados durante un período definido. Tu endpoint debe ser idempotente antes de depender del comportamiento de reintento.

Ir en Vivo: Lista de Verificación Antes de Procesar Transacciones Reales

Pasar de sandbox a producción requiere completar un conjunto de pasos técnicos, de seguridad y comerciales. Omitir cualquiera de ellos crea riesgos para tu negocio y tus clientes.

Lista técnica:
Reemplaza las claves API de sandbox con claves de producción y guárdalas en variables de entorno, nunca en código fuente ni en control de versiones. Confirma que tu endpoint de webhook esté activo, accesible por HTTPS con un certificado válido y que devuelva respuestas 200 de forma consistente. Prueba el manejo de idempotencia con credenciales de producción antes de cambiar el tráfico de clientes. Confirma que 3D Secure está configurado según los requisitos de tu banco adquirente para tu categoría de comerciante. Valida que tu IU de pago se renderiza correctamente en dispositivos móviles, especialmente para los botones de Apple Pay y Google Pay.

Lista PCI DSS:
Si usas la IU drop-in, completa y presenta un cuestionario de autoevaluación SAQ A. Confirma que no estás registrando ni almacenando datos de tarjeta sin procesar en ningún lugar de tu sistema, incluidos registros de solicitudes, registros de errores o canalizaciones de análisis. Asegúrate de que tu configuración TLS cumple los estándares actuales (TLS 1.2 mínimo, TLS 1.3 preferido). Elimina cualquier integración de pago antigua que pueda seguir activa en tu base de código.

Lista de negocio:
Establece tu descriptor de facturación en el panel de control. Este es el texto que aparece en el extracto bancario del titular de la tarjeta. Un descriptor claro y reconocible reduce significativamente los contracargos por fraude amistoso porque los clientes pueden identificar el cargo. Configura tu IBAN de liquidación. RoxPay liquida en cualquier cuenta bancaria SEPA en 24-48 horas. Activa las notificaciones por correo electrónico para transacciones fallidas y contracargos para que puedas responder dentro de los plazos de disputa. Revisa tu política de reembolso y cancelación y asegúrate de que sea claramente visible durante el proceso de pago. Asegúrate de que la información de contacto de atención al cliente sea fácil de encontrar, ya que los clientes que pueden contactarte directamente son mucho menos propensos a iniciar una disputa bancaria.

Frequently Asked Questions

¿Cuánto tiempo lleva la integración de una pasarela de pago?

Usando el enfoque de IU drop-in con la API REST de RoxPay, un desarrollador con experiencia puede completar una integración lista para producción en uno o dos días. Una redirección a página alojada lleva menos de un día. Una integración completa de API servidor a servidor con una IU de pago personalizada suele llevar una o dos semanas y también requiere un nivel mayor de trabajo de cumplimiento PCI DSS junto con el esfuerzo de desarrollo.

¿Necesito estar certificado en PCI DSS para integrar una pasarela de pago?

No certificado en el sentido formal, pero sí debes cumplir con la normativa. Si usas una página alojada o IU drop-in (basada en iFrame), tu carga de cumplimiento es mínima y completas un cuestionario de autoevaluación simple (SAQ A). Si manejas datos de tarjeta sin procesar en tus propios servidores mediante una API servidor a servidor, necesitas SAQ D, que implica una auditoría rigurosa. La mayoría de los comerciantes eligen la IU drop-in precisamente para evitar este requisito.

¿Qué es una intención de pago y por qué se usa?

Una intención de pago es un objeto del lado del servidor que representa la intención de un cliente de pagar un importe específico. Realiza un seguimiento del estado del pago a través de la autorización, el desafío 3D Secure, la captura y la liquidación. Usar un modelo de intención de pago previene cargos duplicados, permite un seguimiento confiable de webhooks y permite que el pago sobreviva a recargas del navegador o conexiones interrumpidas durante el proceso de pago.

¿Puedo probar la integración sin una cuenta de comerciante activa?

Sí. RoxPay proporciona un entorno sandbox gratuito accesible inmediatamente al registrarse. El sandbox refleja exactamente el comportamiento de producción e incluye tarjetas de prueba para cada escenario: aprobaciones, rechazos, desafíos 3DS, tarjetas caducadas y fondos insuficientes. No se requiere información de pago ni aprobación de cuenta activa para comenzar las pruebas.

Más información

Optimize your payments today

RoxPay proporciona una API REST con acceso sandbox gratuito, documentación completa y liquidación en 24-48 horas a cualquier banco SEPA. Certificación PCI DSS Nivel 1, precios IC++ desde 0,45%.

Get started for free → Talk to an expert

✓ No monthly fixed costs · ✓ Activation in 24 hours · ✓ Dedicated technical support