Guía técnica de integración seQura con Checkout.com

La integración de opciones de pago flexible con Checkout.com te permite ofrecer pagos fraccionados en tu eCommerce mediante una única pasarela. Tus clientes acceden a opciones de fraccionamiento sin salir del flujo de compra mientras tú mantienes el control total sobre capturas reembolsos y gestión de transacciones.

En seQura conocemos los retos técnicos de implementar nuevas pasarelas de pago. Por eso hemos preparado esta guía técnica paso a paso para que integres nuestras soluciones de pago flexible con Checkout.com de forma ágil y segura.

Checkout.com actúa como pasarela unificada que conecta múltiples métodos de pago incluidas las opciones de pago flexible. Esta integración elimina la necesidad de gestionar APIs separadas para cada proveedor. El resultado es menos código que mantener y una experiencia de checkout más fluida.

La implementación técnica requiere configurar solicitudes de pago mediante la API de Checkout.com gestionar redirecciones al formulario de identificación y procesar webhooks del ciclo de vida del pago. Antes de pasar a producción validarás todo el flujo en el entorno sandbox con datos de prueba específicos.

¿Qué necesitas antes de integrar pago flexible con Checkout.com?

Antes de comenzar la integración técnica necesitas activar las opciones de pago flexible en tu cuenta de Checkout.com y obtener acceso al entorno de pruebas. Este paso inicial garantiza que dispongas de las credenciales y permisos necesarios para realizar la implementación.

Activación en tu cuenta de Checkout.com

El primer requisito es solicitar la activación del método de pago contactando con tu Account Manager de Checkout.com o escribiendo a support@checkout.com.

Checkout.com debe habilitar las opciones de pago flexible como método de pago en tu cuenta merchant. Sin esta activación previa la API rechazará cualquier solicitud de pago que especifique este método. El proceso lo gestiona el equipo de soporte o tu gestor de cuenta y el tiempo de activación depende de su gestión interna.

No podrás avanzar con la implementación técnica hasta completar este paso. Asegúrate de solicitarlo con antelación suficiente respecto a tu fecha prevista de go-live.

Acceso al entorno sandbox para pruebas

Necesitas solicitar acceso al entorno sandbox para validar la integración antes de pasar a producción. Este entorno te permite realizar tests sin procesar transacciones reales ni comprometer datos de clientes.

Contacta con tu Account Manager o Implementation Engineer para activar el sandbox. El entorno de pruebas replica el comportamiento de producción. Esto permite validar el flujo completo desde la solicitud de pago hasta la gestión de webhooks y capturas.

Podrás usar datos de test específicos para simular pagos completos incluyendo la autenticación del cliente y la aprobación del crédito. Es obligatorio validar la integración en sandbox antes del go-live en producción. Este requisito protege tanto tu sistema como la experiencia de tus primeros clientes reales.

Ten en cuenta que las credenciales de API del sandbox son diferentes a las de producción. Deberás actualizar estas credenciales cuando despliegues a producción pero el código de integración permanecerá idéntico.

¿Cómo funcionan las opciones de pago flexible en Checkout.com?

Las opciones de pago flexible ofrecen múltiples modalidades que se diferencian por el número de plazos y el periodo de financiación. Cada opción se configura mediante el parámetro processing.product_type en tu solicitud de pago.

Tipos de pago disponibles

Las opciones de pago varían según dos criterios. El número de cuotas que quieres ofrecer y el plazo temporal de financiación. Debes especificar la opción elegida en el campo processing.product_type de cada solicitud de pago.

Este parámetro es obligatorio en toda request de pago que utilice estas opciones como método. El valor que especifiques determina qué condiciones de financiación se aplicarán al cliente final. Incluye desde fraccionamiento en 3 pagos sin coste hasta financiación extendida en más plazos.

El sistema valida que el product_type sea compatible con el importe del carrito. Si el importe no cumple los requisitos mínimos o máximos para la opción seleccionada, la solicitud será rechazada. Por ejemplo ciertas opciones de financiación solo están disponibles para importes superiores a umbrales específicos.

La estructura básica del parámetro en tu API request incluye el campo processing con el atributo product_type. Consulta la documentación oficial de Checkout.com para conocer los valores exactos disponibles y sus características, ya que pueden variar según tu configuración comercial.

Configuración de múltiples opciones en el checkout

Puedes ofrecer varias opciones de pago flexible de forma simultánea en tu página de checkout. Cada opción requiere un botón independiente vinculado a una solicitud de pago con su correspondiente processing.product_type.

Cada botón de pago representa una modalidad diferente de financiación. Por ejemplo, podrías mostrar "Paga en 3 meses sin intereses" junto a "Fracciona en más plazos" como opciones separadas. El cliente elige la modalidad que mejor se adapte a sus necesidades antes de confirmar la compra.

Necesitas crear una payment request separada para cada opción que quieras ofrecer. Esto significa que si presentas tres modalidades diferentes, tu checkout realizará una llamada a la API por cada una para obtener las URLs de redirección correspondientes. Esta arquitectura te da flexibilidad para mostrar u ocultar opciones según reglas de negocio, como importe del carrito, tipo de producto o perfil del cliente.

Esta configuración mejora de forma significativa la experiencia de usuario al ofrecer transparencia y capacidad de elección. Los clientes valoran poder comparar opciones de financiación y seleccionar la que mejor encaja con su situación financiera personal. Además, ofrecer múltiples plazos puede incrementar tu tasa de conversión al captar perfiles de cliente con diferentes preferencias de pago.

¿Cuál es el flujo completo de integración de pagos?

El proceso de integración sigue un flujo en dos pasos principales. Solicitar el pago mediante la API de Checkout.com y redirigir al cliente al formulario de identificación. Una vez completado recibes la confirmación del pago para proceder con el pedido.

Solicitar un pago (request a payment)

El primer paso técnico consiste en enviar una solicitud de pago a la API de Checkout.com incluyendo los datos del carrito, información del cliente y el processing.product_type que quieres utilizar.

Tu request debe incluir información completa del pedido. Artículos del carrito con sus importes individuales, datos de envío y facturación del cliente y la configuración del método de pago. Especificas el método de pago flexible junto con el product_type correspondiente a la modalidad de financiación elegida.

Define si quieres captura automática (capture=true) o captura manual (capture=false). La captura automática autoriza y cobra el pago de inmediato tras la aprobación. La captura manual solo autoriza el pago, dejándote cobrar más tarde cuando envíes el producto físico. Esta decisión depende de tu modelo de negocio y gestión de stock.

La API de Checkout.com valida la request y devuelve un objeto con el payment_id (identificador único de la transacción) y la URL de redirección en el campo _links.redirect.href. Este payment_id es fundamental. Lo necesitarás para todas las operaciones posteriores sobre este pago como consultas de estado, capturas o reembolsos.

Los campos obligatorios incluyen el importe total, la moneda, información básica del cliente y la configuración del método de pago. Los campos opcionales te permiten añadir metadatos personalizados referencias de pedido internas o configuraciones avanzadas de captura. Valida que todos los importes estén bien formateados según los requisitos de la API antes de enviar la request.

Redirigir al cliente al formulario de identificación

Una vez creada la solicitud de pago obtienes una URL en el campo _links.redirect.href que debes usar para redirigir al cliente al formulario de identificación.

El cliente completa sus datos personales en el formulario alojado en el dominio del proveedor de pago. Este formulario solicita información básica para la identificación. DNI o NIE fecha de nacimiento y número de teléfono móvil. Son solo cuatro datos. Un proceso diseñado para maximizar la conversión sin fricciones innecesarias.

El sistema valida la identidad del cliente y evalúa la aprobación del crédito en tiempo real. El algoritmo de riesgo analiza múltiples factores y ofrece altas tasas de aceptación. La respuesta es prácticamente instantánea. El cliente conoce la decisión en segundos.

El proceso es transparente y ocurre en el dominio del proveedor de pago, no en tu tienda. Esto elimina responsabilidades de cumplimiento normativo de tu lado y ofrece al cliente la tranquilidad de que sus datos financieros se gestionan por una entidad especializada. Durante este paso el cliente también acepta las condiciones del servicio de financiación.

El formulario está optimizado para conversión tanto en desktop como en móvil. La interfaz es clara los campos están prellenados cuando es posible con datos de la request inicial y los mensajes de error son específicos y ayudan al cliente a corregir información incorrecta.

Gestionar la respuesta y confirmación del pago

Tras completar el proceso, el cliente es redirigido de vuelta a tu tienda mediante la URL de éxito que especificaste en la payment request inicial. En paralelo recibes webhooks con el estado del pago.

Define URLs de éxito y error en tu solicitud inicial para controlar a dónde redirigir al cliente según el resultado. La URL de éxito debería mostrar una página de confirmación de pedido. La URL de error debería permitir al cliente reintentar el pago o elegir otro método.

Implementa endpoints en tu servidor para recibir webhooks de Checkout.com. Estos webhooks te notifican eventos del ciclo de vida del pago de forma asíncrona y confiable. No dependas solo de la redirección del navegador ya que el cliente podría cerrar la ventana antes de completarla.

Valida el estado del pago antes de confirmar el pedido al cliente. Puedes consultar el endpoint GET /payments/{id} de Checkout.com para obtener el estado actualizado de la transacción. Verifica que el pago esté en estado "authorized" o "captured" según tu configuración antes de procesar el pedido.

Actualiza el estado del pedido en tu sistema según la respuesta recibida. Si el pago fue exitoso, marca el pedido como confirmado e inicia el proceso de fulfillment. Si fue rechazado, permite al cliente intentar de nuevo o contactar con soporte. Registra toda la información del pago (payment_id importes estados) para auditoría y reconciliación posterior.

¿Cómo gestionar capturas, reembolsos y cancelaciones?

Una vez autorizado el pago puedes gestionar capturas (cobros) reembolsos y cancelaciones según las necesidades operativas de tu negocio. Checkout.com ofrece opciones automáticas y manuales para cada operación.

Captura automática vs. captura manual

Al crear la solicitud de pago decides si la captura será automática o manual mediante el parámetro capture. La captura automática cobra de inmediato tras la autorización, mientras que la manual te permite cobrar después del envío del pedido.

Si capture=true la autorización y el cobro se ejecutan juntos en un único paso. El sistema autoriza el pago y si la aprobación es exitosa lo captura de forma automática. Esta modalidad es recomendada para productos digitales, servicios inmediatos o cualquier escenario donde no necesites validar stock o gestionar envíos físicos.

La captura automática simplifica tu flujo operativo al eliminar pasos manuales. El dinero se transfiere tras la aprobación del cliente, mejorando así tu cashflow y reduciendo la carga administrativa de tu equipo. No necesitas implementar procesos adicionales para ejecutar la captura después.

Si capture=false el sistema solo autoriza el pago sin cobrarlo. Esto "reserva" el importe en la cuenta del cliente, pero no lo cobra hasta que tú ejecutes la captura de forma manual. Debes realizar la captura cuando envíes el producto o confirmes que puedes cumplir con el pedido.

Esta modalidad es ideal para productos físicos con gestión de stock, sobre todo cuando trabajas con dropshipping o necesitas validar disponibilidad antes de comprometerte. También resulta útil en escenarios con procesos de validación interna (verificación antifraude adicional confirmación de identidad para productos restringidos) o cuando el tiempo entre la compra y el envío puede extenderse varios días.

Puedes realizar capturas parciales incluyendo los objetos amount e items en tu request de captura. Esta funcionalidad es útil cuando entregas pedidos en varios envíos, ya que capturas solo el importe correspondiente a los artículos que envías en cada entrega.

Las capturas parciales te permiten hacer múltiples capturas del mismo pago autorizado. Por ejemplo, si un cliente compra tres productos por 300 €, pero solo tienes dos disponibles de inmediato, capturas 200 € al enviar los dos primeros y los 100 € restantes cuando esté disponible el tercero. Esta flexibilidad mejora tu gestión operativa sin comprometer la experiencia del cliente.

Procesar reembolsos completos y parciales

Las opciones de pago flexible permiten reembolsos completos y parciales mediante el Dashboard de Checkout.com o usando la Refund API. Los reembolsos se procesan de vuelta al método de pago original del cliente.

El reembolso completo devuelve el importe total del pago capturado. Úsalo cuando el cliente devuelve todos los productos de un pedido o cuando necesitas cancelar una transacción por cualquier motivo operativo. El reembolso completo es directo y no requiere especificar importes ni artículos detallados.

El reembolso parcial devuelve solo una parte del importe capturado. Esta opción es útil cuando el cliente devuelve algunos artículos, pero mantiene otros o cuando ofreces compensaciones por problemas específicos (producto defectuoso, envío retrasado). Debes especificar el importe exacto a reembolsar en tu solicitud.

Puedes procesar reembolsos desde dos interfaces. Accediendo al panel de Checkout.com para gestiones manuales ocasionales o usando la Refund API para automatizar el proceso desde tu sistema. La opción API es recomendable si gestionas un volumen alto de devoluciones o si quieres integrar el reembolso en tu flujo de gestión de devoluciones.

El reembolso llega al cliente según los plazos de procesamiento de su banco o método de pago. El proveedor de pago gestiona la devolución del importe en las cuotas pendientes del cliente pero el plazo exacto de llegada depende de la entidad bancaria. Comunica a tu cliente que el reembolso puede tardar entre 5 y 10 días laborables en reflejarse en su cuenta.

Qué hacer cuando un cliente cancela el pago

Una vez creado un pago con estas opciones no puedes cancelarlo de forma directa mediante void. Si necesitas anular una transacción, debes esperar a recibir el webhook payment_captured y procesar un reembolso inmediato.

No existe operación de void (anulación) para estos pagos en Checkout.com. Esta limitación técnica es importante. A diferencia de otros métodos de pago donde puedes anular una autorización antes de capturarla, aquí solo puedes reembolsar después de la captura. La alternativa es procesar un reembolso completo de inmediato tras la captura si necesitas cancelar la transacción.

Comunica esta limitación a tu equipo de atención al cliente para que gestionen bien las expectativas. Si un cliente solicita cancelar su pedido después de haber completado el pago pero antes del envío explícale que el proceso requiere un reembolso (no una cancelación directa) y que el dinero le será devuelto en los plazos habituales.

Si el cliente abandona el proceso de pago en el formulario sin completarlo, recibes el webhook payment_expired. Este webhook indica que el cliente no finalizó el proceso de identificación o que no se aprobó el crédito solicitado. En estos casos no se genera ningún cargo por lo que no necesitas procesar ningún reembolso.

Puedes usar la información del webhook payment_expired para tu estrategia de remarketing o seguimiento. Por ejemplo enviar un email al cliente recordándole que tiene un carrito pendiente y ofreciéndole métodos de pago alternativos. Este dato también es valioso para analizar las tasas de abandono en el checkout y optimizar tu flujo de pago.

¿Cómo funcionan los webhooks en el ciclo de vida del pago?

Checkout.com envía webhooks automáticos en cada fase del ciclo de vida del pago. Estos eventos te permiten actualizar el estado de los pedidos en tu sistema de forma asíncrona y confiable.

Los webhooks son notificaciones HTTP POST que Checkout.com envía a tu servidor cuando ocurren eventos relevantes en una transacción. En lugar de consultar de forma constante la API para verificar el estado de un pago, tu sistema recibe actualizaciones automáticas cada vez que cambia algo. Esta arquitectura basada en eventos es más eficiente y reduce la latencia en la actualización de estados.

Los eventos clave del ciclo de vida incluyen payment_captured (el pago ha sido capturado con éxito) y payment_expired (el cliente no completó el proceso de pago). Existen otros eventos relacionados con reembolsos y actualizaciones de estado que recibirás según las operaciones que realices sobre cada transacción.

Cada webhook incluye el payment_id para identificar la transacción específica. Este identificador te permite correlacionar el evento con el pedido correspondiente en tu sistema. El payload del webhook contiene información detallada sobre el evento. 

Configura un endpoint HTTPS en tu servidor para recibir webhooks. Checkout.com requiere que el endpoint use protocolo seguro (no HTTP) y esté accesible de forma pública. Este endpoint debe responder rápido (en menos de 5 segundos) para evitar timeouts y reintentos innecesarios.

Valida la firma de los webhooks para garantizar autenticidad. Checkout.com firma cada webhook con una clave secreta que solo tú y ellos conocéis. Verificar esta firma evita que actores maliciosos envíen webhooks falsos a tu sistema. La documentación de Checkout.com incluye ejemplos de código para validar firmas en diferentes lenguajes de programación.

Procesa los eventos de forma idempotente para evitar duplicados. Los webhooks pueden llegar más de una vez por problemas de red o reintentos automáticos. Tu sistema debe detectar webhooks duplicados (usando el payment_id y el tipo de evento como clave) y procesarlos solo una vez. Ignorar duplicados evita operaciones erróneas como enviar múltiples confirmaciones de pedido al cliente.

Responde con código 200 para confirmar recepción. Checkout.com espera que tu endpoint responda con HTTP 200 (OK) para considerar que el webhook fue recibido bien. Si respondes con cualquier otro código (4xx 5xx) o si hay timeout el sistema reintentará el envío múltiples veces con intervalos crecientes.

Implementa reintentos en caso de fallos temporales de tu sistema. Si tu servidor está caído o experimenta problemas cuando Checkout.com intenta enviar un webhook necesitas un mecanismo para recuperar esos eventos perdidos. Puedes consultar de forma periódica la API de pagos para verificar estados o implementar un sistema de cola que procese webhooks pendientes cuando tu servicio se recupere.

Registra todos los webhooks recibidos para auditoría. Mantén un log completo de cada webhook. Esto incluye cuándo llegó, qué contenía, cómo lo procesaste y si hubo errores. Esta información es invaluable para debugging para entender discrepancias en estados de pedidos y para cumplir con requisitos de auditoría interna o externa.

No dependas solo de webhooks para operaciones críticas. Aunque los webhooks son confiables, pueden fallar por problemas de red, configuración incorrecta o indisponibilidad temporal de tu servidor. Para operaciones críticas como confirmar un pago antes de enviar un producto de alto valor combina webhooks con consultas activas a la API. Esta estrategia híbrida maximiza confiabilidad.

Combina webhooks con consultas activas al API cuando sea necesario. Por ejemplo, después de redirigir al cliente de vuelta a tu tienda puedes consultar de inmediato el estado del pago mediante GET /payments/{id} en lugar de esperar al webhook. Esto reduce la latencia percibida por el cliente y te permite mostrar confirmación instantánea en pantalla.

¿Cómo realizar un pago de prueba en el entorno sandbox?

El entorno sandbox te permite validar la integración completa usando datos de prueba específicos. Sigue este proceso paso a paso para realizar tu primer test de pago en Checkout.com.

Asegúrate de tener las opciones de pago flexible activadas en tu cuenta sandbox de Checkout.com antes de comenzar. Usa las credenciales de API del entorno de pruebas nunca las de producción. Mezclar credenciales entre entornos es uno de los errores más comunes y puede generar confusión al analizar resultados de test.

Prepara tu implementación del flujo de pago completo antes de lanzar el primer test. Esto incluye la creación de payment requests la gestión de redirecciones, los endpoints para recibir webhooks y la lógica para procesar respuestas. Tener todo el código listo te permite validar el flujo end-to-end en una sola ejecución.

Envía una payment request de prueba con datos válidos a la API de Checkout.com. Incluye un carrito con artículos de ejemplo, información básica del cliente (nombre, email, dirección) y el processing.product_type que quieras testear. Puedes elegir captura automática o manual para el test según lo que necesites validar.

Anota el payment_id devuelto en la respuesta para seguimiento posterior. Este identificador te servirá para consultar el estado del pago, procesar capturas manuales si configuraste capture=false o vincular webhooks recibidos con esta transacción específica.

Abre la URL del campo _links.redirect.href en tu navegador. Esta URL te lleva al formulario de identificación en el entorno de pruebas. Verás una interfaz idéntica a la de producción pero funcionando con el motor de aprobaciones de sandbox.

Datos de prueba para el formulario de identificación

El formulario de identificación solicita tres datos personales en el entorno de pruebas. Usa estos valores específicos para simular una aprobación exitosa del crédito.

Los datos requeridos son:

• Fecha de nacimiento: cualquier fecha válida que indique mayoría de edad (+18 años). Por ejemplo, 01/01/1990 funciona bien.
• DNI/NIE: usa el valor de prueba 66706324E. Este es el único DNI que el sistema de sandbox reconoce como válido.
• Teléfono móvil: introduce +34 666 666 666. Incluye el prefijo internacional para España.

Acepta los términos y condiciones de uso marcando la casilla correspondiente. Aunque estés en entorno de pruebas, el formulario simula el flujo completo incluyendo este paso legal. Selecciona el botón "Siguiente" para avanzar al siguiente paso del proceso.

El sistema procesa la validación de forma instantánea en el entorno de pruebas. A diferencia de producción, donde la aprobación puede tardar unos segundos, mientras el algoritmo analiza múltiples factores en sandbox, la respuesta es inmediata porque usa datos predefinidos.

Aparece un formulario solicitando los últimos 5 dígitos del teléfono como medida de seguridad. Introduce el código de prueba 66666. Este paso simula la verificación por SMS que ocurre en producción, donde se envía un código al móvil del cliente para confirmar su identidad.

Se solicita información de tarjeta para gestionar los pagos fraccionados del cliente. Aunque estés en pruebas, el sistema valida que los datos de tarjeta sean bien formateados. Usa estos datos de prueba para completar el formulario:

• Número de tarjeta: 4716773077339777
• Fecha de expiración: 12/30
• CVV: 123

Estos datos de tarjeta de prueba están configurados para simular una tarjeta válida con fondos suficientes. En producción se validaría la tarjeta real del cliente para garantizar que puede cumplir con los pagos fraccionados.

Completar la autenticación 3D Secure en el test

El último paso del test es la autenticación 3D Secure, un protocolo de seguridad estándar en pagos con tarjeta. En el entorno de pruebas usa una contraseña específica para simular la autenticación exitosa.

Aparece el formulario de 3D Secure tras introducir los datos de tarjeta. Esta pantalla simula el proceso que los bancos usan para verificar que quien realiza el pago es el titular legítimo de la tarjeta. En producción el cliente introduciría su clave personal del banco o confirmaría mediante app móvil.

Introduce la contraseña de prueba: Checkout1! (respeta las mayúsculas y el signo de exclamación). Esta contraseña está predefinida en el entorno sandbox para simular autenticación exitosa. Confirma la autenticación pulsando el botón correspondiente.

Si el test fue exitoso, serás redirigido a la URL de éxito que configuraste en la payment request inicial. Esta redirección confirma que todo el flujo funcionó bien desde el punto de vista del navegador del cliente. La página de éxito debería mostrar confirmación del pedido con el payment_id visible.

Verifica que tu sistema recibió los webhooks correspondientes. Revisa los logs de tu endpoint de webhooks para confirmar que llegó el evento payment_captured (si configuraste capture=true) o payment_authorized (si configuraste capture=false). La ausencia de webhooks indica problemas de configuración en tu endpoint o en la configuración de Checkout.com.

Comprueba el estado del pago usando el endpoint GET /payments/{id} con el payment_id que anotaste al inicio. La respuesta debe mostrar el pago en estado "captured" o "authorized" según tu configuración. Este paso valida que la información se persistió bien en Checkout.com.

Valida que todos los datos del pago se registraron bien. Cualquier discrepancia entre lo que enviaste y lo que recibes indica posibles problemas en la construcción de tu payment request.

Si encuentras errores durante el test revisa los códigos de error devueltos por la API. Checkout.com proporciona mensajes descriptivos que te ayudarán a identificar el problema. 

Realiza múltiples tests con diferentes escenarios. Captura automática vs manual diferentes valores de processing.product_type importes de carrito variados. Cada escenario validado en sandbox es un caso menos propenso a fallar en producción. Dedica tiempo suficiente a esta fase de testing antes de desplegar.

¿Tienes dudas sobre cómo configurar el pago flexible en tu tienda? Más de 5.000 comercios en Europa y Latinoamérica ya cuentan con nuestro equipo para ajustar límites, resolver incidencias y mejorar resultados. Contacta con nuestro equipo para resolver dudas específicas sobre configuración, límites de financiación o estrategias de optimización.