Hyperswitch Prism

Hyperswitch Prism: Una integración, cualquier procesador de pagos

En el ecosistema financiero actual, la fragmentación de los procesadores de pagos representa uno de los mayores desafíos para los desarrolladores y empresas. Cada proveedor cuenta con sus propias APIs, códigos de error y métodos de autenticación específicos. Para resolver esta complejidad surge Hyperswitch Prism, una librería de conectores unificada y apátrida que permite conectarse con cualquier procesador de pagos y cambiar entre ellos con solo unas pocas líneas de código.

¿Qué es Hyperswitch Prism?

Hyperswitch Prism es una librería de conectores unificada diseñada para ser ligera, amigable para el desarrollador y sin bloqueos (zero lock-in). Esta herramienta ha sido extraída de las integraciones endurecidas de Juspay Hyperswitch, la plataforma de pagos de código abierto que cuenta con más de 40,000 estrellas en GitHub y es utilizada por comercios líderes en todo el mundo.

Prism se define como una solución stateless (sin estado), lo que significa que no utiliza bases de datos ni almacena información de identificación personal (PII). Su función principal es actuar como una capa de transformación universal entre tu aplicación y los diversos servicios de pago.

El origen y la filosofía de Prism

La industria de los pagos no ha llegado a un estándar universal y, según los creadores de esta herramienta, probablemente nunca lo hará. Cada procesador tiene comportamientos diferentes entre sus entornos de prueba y sus especificaciones documentadas. Hyperswitch Prism democratiza el acceso a esta diversidad de pagos, empaquetando años de conocimiento técnico e iteraciones en una librería que simplifica lo que tradicionalmente ha sido una curva de aprendizaje costosa para las empresas.

Características principales de Hyperswitch Prism

Esta librería destaca por varias funcionalidades clave que optimizan la integración de pagos:

• Esquema de solicitud único: Una de las mayores ventajas es que la misma llamada de autorización funciona contra Stripe, Adyen y muchos otros procesadores sin necesidad de escribir líneas de código adicionales para cada uno.
• Arquitectura Apátrida (Stateless): No almacena credenciales ni registros de forma permanente. La información vive únicamente durante el tiempo de vida de tu cliente HTTP.
• Reducción del alcance PCI: Los desarrolladores tienen la libertad de elegir cómo fluyen los datos de las tarjetas. Puedes optar por utilizar el vault (bóveda) de cualquier procesador de pagos o tu propia bóveda certificada PCI. Prism no registra ni almacena nada.
• Soporte Multi-lenguaje: Ofrece SDKs idiomáticos y seguros para lenguajes como Node.js, Python, Java y Rust.
• Integraciones endurecidas: Prism se beneficia de años de pruebas continuas y corrección de errores en entornos reales dentro de Juspay.

¿Por qué la integración de pagos es tan compleja?

Muchos desarrolladores comparan los pagos con los controladores de bases de datos, pero la realidad es más intrincada. Un pequeño error en la gestión de una API de pagos puede tener un impacto financiero masivo. Las empresas suelen enfrentarse a:

1. Diversidad extrema en APIs y códigos de error.
2. Métodos de autenticación variados.
3. Diferencias conductuales entre el sandbox y la producción.
4. Documentación extensa y a veces contradictoria.

"Un pequeño error u omisión puede crear un impacto financiero enorme para los negocios que aceptan pagos. Todo el conocimiento acumulado sobre estas correcciones se libera a través de Prism".

Cómo usar Hyperswitch Prism

La implementación de Hyperswitch Prism está diseñada para ser rápida y directa. A continuación, se detallan los pasos para comenzar.

1. Instalación de la librería

Dependiendo de tu entorno de desarrollo, puedes instalar Prism utilizando los gestores de paquetes estándar:

• Node.js: npm install hyperswitch-prism
• Python: pip install hyperswitch-prism
• Java/Kotlin: Debes añadir la dependencia en tu archivo pom.xml:

  <dependency>
      <groupId>io.hyperswitch</groupId>
      <artifactId>prism</artifactId>
      <version>0.0.4</version>
  </dependency>
  

2. Realizar un pago (Ejemplo en Node.js)

El siguiente código muestra cómo configurar un cliente de pago y realizar una llamada de autorización unificada:

import { PaymentClient, types } from 'hyperswitch-prism';

let config = {
    connectorConfig: {
        stripe: {
            apiKey: { value: "sk_test_" }
        }
    }
}

const main = async () => {
    let client = new PaymentClient(config);
    let request = {
        merchantTransactionId: "authorize_123",
        amount: {
            minorAmount: 1000, // $10.00
            currency: types.Currency.USD,
        },
        captureMethod: types.CaptureMethod.AUTOMATIC,
        paymentMethod: {
            card: {
                cardNumber: { value: "4111111111111111" },
                cardExpMonth: { value: "12" },
                cardExpYear: { value: "2050" },
                cardCvc: { value: "123" },
                cardHolderName: { value: "User Test" },
            },
        },
        authType: types.AuthenticationType.NO_THREE_DS,
    };
    let response = await client.authorize(request);
    if (response.status === types.PaymentStatus.CHARGED) {
        console.log("Pago exitoso");
    }
}

Casos de Uso: Enrutamiento entre proveedores

El beneficio principal de Hyperswitch Prism es la capacidad de cambiar de proveedor de pago simplemente modificando la configuración del cliente. Esto es ideal para implementar reglas de negocio dinámicas o lógica de reintentos inteligentes.

• Enrutamiento por moneda: Puedes configurar tu aplicación para que los pagos en EUR se procesen a través de Adyen, mientras que los pagos en USD utilicen Stripe.
• Redundancia: Si un procesador experimenta una caída, puedes cambiar a un proveedor de respaldo de forma inmediata utilizando el mismo esquema de datos.

Arquitectura de Prism

La arquitectura de Prism se sitúa entre tu aplicación y los procesadores. Es una capa de tipo seguro (type-safe) que transforma tus solicitudes en el formato específico que requiere cada procesador (Stripe, Adyen, Braintree, Worldpay, etc.).

1. Tu Aplicación: Realiza una llamada al SDK de Prism.
2. Librería Prism: Procesa la solicitud mediante un esquema unificado.
3. Conector: Realiza la comunicación con el procesador de pagos seleccionado.

Lo que Prism no hace (todavía)

Es importante entender los límites actuales del proyecto:

• No incluye Vault nativo: Prism no es un servicio de tokenización. Puedes traer tu propia bóveda o usar la del procesador.
• Sin lógica de reintento o enrutamiento automático: Estas funciones residen en el sistema completo de Juspay Hyperswitch. Prism es estrictamente la capa de transformación.
• Enfoque inicial en pagos: Actualmente no cubre suscripciones, fraude o impuestos, aunque aspira a convertirse en una librería de comercio apátrida integral.

FAQ: Preguntas Frecuentes

¿En qué plataformas está disponible el SDK? El SDK de Hyperswitch Prism incluye librerías nativas compiladas para macOS (Apple Silicon) en arquitectura arm64 y Linux en arquitectura x86_64.

¿Cómo puedo reportar vulnerabilidades? Cualquier problema de seguridad debe ser reportado directamente al equipo de Juspay a través del correo [email protected].

¿Es compatible con asistentes de IA? Sí, el proyecto ofrece un archivo de referencia optimizado para asistentes de IA que contiene toda la documentación del SDK, operaciones y configuraciones de conectores mediante el comando curl -fsSL https://raw.githubusercontent.com/juspay/hyperswitch-prism/main/llm/llm.txt.

¿Qué licencia utiliza? Hyperswitch Prism se distribuye bajo la Licencia Apache-2.0, lo que permite un uso flexible y abierto para empresas y desarrolladores por igual.