Guía técnica: Integración del SDK de Youfunatt paso a paso

Introducción

La integración de un sistema de pagos robusto y seguro es un componente crítico para cualquier sitio web o aplicación de e-commerce. El SDK de Youfunatt ha sido diseñado para simplificar este proceso, proporcionando una solución flexible que se adapta a diferentes casos de uso y requisitos técnicos.

En esta guía, le mostraremos paso a paso cómo integrar nuestro SDK en su plataforma, desde la configuración inicial hasta la implementación de flujos de pago avanzados. Cubriremos tanto la integración frontend (JavaScript SDK) como las consideraciones para backend, con ejemplos de código prácticos y recomendaciones de arquitectura.

Arquitectura general

Antes de comenzar con la implementación técnica, es importante entender la arquitectura general del sistema de pagos de Youfunatt:

1. Cliente (Browser/App): Donde se ejecuta nuestro JavaScript SDK, recopilando de forma segura los datos de pago.
2. Servidor de su aplicación: Responsable de crear la intención de pago, procesar webhooks y gestionar el estado de los pedidos.
3. Servidores de Youfunatt: Procesan las transacciones, se comunican con los proveedores de pago y envían notificaciones mediante webhooks.

Esta arquitectura está diseñada para maximizar la seguridad, minimizando la exposición de datos sensibles en su servidor y simplificando el cumplimiento de PCI DSS.

Requisitos previos

Antes de comenzar la integración, asegúrese de tener lo siguiente:

• Una cuenta de Youfunatt (puede solicitar acceso aquí)
• Claves de API (disponibles en su panel de control)
• Conocimientos básicos de JavaScript y la plataforma backend que utilice

Paso 1: Configuración del proyecto

Lo primero es añadir el SDK de Youfunatt a su proyecto. Puede hacerlo de varias formas:

Mediante CDN (recomendado para la mayoría de casos)

<script src="https://cdn.Youfunatt.com/sdk/v2/Youfunatt.js"></script>

Mediante npm (para proyectos basados en Node.js)

npm install @Youfunatt/sdk-js

Y luego importarlo en su código:

import Youfunatt from '@Youfunatt/sdk-js';

Paso 2: Inicialización del SDK

Una vez añadido el SDK a su proyecto, debe inicializarlo con su clave pública:

const Youfunatt = Youfunatt.initialize({
  publicKey: 'pk_test_xxxxxxxxxxxxxxxx',
  environment: 'sandbox',
  locale: 'es-ES',       
});

Paso 3: Crear un formulario de pago

Existen dos enfoques principales para integrar el formulario de pago:

Opción A: Formulario preconfigurado (recomendado para la mayoría de casos)

El SDK de Youfunatt incluye componentes preconstruidos que manejan automáticamente la validación, formateo y seguridad:

<div id="payment-form-container"></div>

<script>
 
  const paymentForm = Youfunatt.elements.create('paymentForm', {
    style: {
      base: {
        fontSize: '16px',
        fontFamily: 'Karla, sans-serif',
        color: '#343A40',
        '::placeholder': {
          color: '#6C757D',
        },
      },
      invalid: {
        color: '#DC3545',
      },
    },
   
    paymentMethods: ['card', 'sepa', 'bizum', 'applepay', 'googlepay'],
  });
  
  paymentForm.mount('#payment-form-container');
</script>

Opción B: Formulario personalizado

Si necesita un mayor control sobre el diseño y la experiencia, puede crear su propio formulario e integrar componentes individuales:

<form id="custom-payment-form">
  <div class="form-group">
    <label>Número de tarjeta</label>
    <div id="card-number-element"></div>
  </div>
  
  <div class="row">
    <div class="col-6">
      <div class="form-group">
        <label>Fecha de expiración</label>
        <div id="card-expiry-element"></div>
      </div>
    </div>
    <div class="col-6">
      <div class="form-group">
        <label>CVC</label>
        <div id="card-cvc-element"></div>
      </div>
    </div>
  </div>
  
  <button type="submit">Pagar</button>
</form>

<script>
 
  const cardNumber = Youfunatt.elements.create('cardNumber');
  const cardExpiry = Youfunatt.elements.create('cardExpiry');
  const cardCvc = Youfunatt.elements.create('cardCvc');
  
 
  cardNumber.mount('#card-number-element');
  cardExpiry.mount('#card-expiry-element');
  cardCvc.mount('#card-cvc-element');
</script>

Paso 4: Crear una intención de pago (backend)

Antes de procesar un pago, debe crear una "intención de pago" desde su servidor backend utilizando su clave secreta:

Ejemplo en Node.js

// Instalar primero: npm install @Youfunatt/sdk-server
const YoufunattServer = require('@Youfunatt/sdk-server');

const Youfunatt = new YoufunattServer('sk_test_xxxxxxxxxxxxxxxx');

app.post('/create-payment-intent', async (req, res) => {
  try {
    const paymentIntent = await Youfunatt.paymentIntents.create({
      amount: 2500,              
      currency: 'EUR',
      description: 'Pedido #1234',
      metadata: {
        orderId: '1234',
        customer: 'cliente@ejemplo.com'
      },
      receipt_email: 'cliente@ejemplo.com'
    });
    
    res.json({
      clientSecret: paymentIntent.client_secret
    });
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
});

Ejemplo en PHP

// Instalar primero: composer require Youfunatt/sdk-server
require_once 'vendor/autoload.php';

$Youfunatt = new \Youfunatt\YoufunattServer('sk_test_xxxxxxxxxxxxxxxx');


if ($_SERVER['REQUEST_METHOD'] === 'POST' && $_SERVER['REQUEST_URI'] === '/create-payment-intent') {
  try {
    $paymentIntent = $Youfunatt->paymentIntents->create([
      'amount' => 2500,              
      'currency' => 'EUR',
      'description' => 'Pedido #1234',
      'metadata' => [
        'orderId' => '1234',
        'customer' => 'cliente@ejemplo.com'
      ],
      'receipt_email' => 'cliente@ejemplo.com'
    ]);
    
    header('Content-Type: application/json');
    echo json_encode([
      'clientSecret' => $paymentIntent->client_secret
    ]);
  } catch (Exception $e) {
    http_response_code(500);
    header('Content-Type: application/json');
    echo json_encode(['error' => $e->getMessage()]);
  }
  exit;
}

Paso 5: Procesar el pago (frontend)

Una vez que tenga el formulario y haya creado la intención de pago, puede procesar la transacción cuando el usuario envíe el formulario:

// Obtener el clientSecret del backend
fetch('/create-payment-intent', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    amount: 2500,
   
  }),
})
.then(response => response.json())
.then(data => {
  const { clientSecret } = data;
  
 
  const form = document.getElementById('custom-payment-form');
  form.addEventListener('submit', async (event) => {
    event.preventDefault();
    
   
    const button = form.querySelector('button');
    button.disabled = true;
    button.textContent = 'Procesando...';
    
    try {
      const result = await Youfunatt.confirmPayment({
        clientSecret,
        elements: [cardNumber, cardExpiry, cardCvc],
      });
      
      if (result.error) {
       
        showError(result.error.message);
      } else {
       
        window.location.href = '/confirmacion-pedido?id=1234';
      }
    } catch (error) {
      showError('Ha ocurrido un error inesperado. Por favor, inténtelo de nuevo.');
      console.error(error);
    } finally {
      button.disabled = false;
      button.textContent = 'Pagar';
    }
  });
});

Paso 6: Configurar webhooks (backend)

Los webhooks son esenciales para mantener su sistema sincronizado con los eventos de pago, especialmente para transacciones asíncronas o que requieren autenticación adicional:

Ejemplo en Node.js

app.post('/webhooks/Youfunatt', async (req, res) => {
  const signature = req.headers['x-Youfunatt-signature'];
  const webhookSecret = 'whsec_xxxxxxxxxxxxxxxx';
  
  try {
    const event = Youfunatt.webhooks.constructEvent(
      req.rawBody,
      signature,
      webhookSecret
    );
    
   
    switch (event.type) {
      case 'payment_intent.succeeded':
        const paymentIntent = event.data.object;
        await updateOrderStatus(paymentIntent.metadata.orderId, 'paid');
        break;
        
      case 'payment_intent.payment_failed':
        const failedPayment = event.data.object;
        await updateOrderStatus(failedPayment.metadata.orderId, 'failed');
       
        break;
        
     
    }
    
    res.status(200).send({ received: true });
  } catch (error) {
    console.error('Error en webhook:', error.message);
    res.status(400).send(`Webhook Error: ${error.message}`);
  }
});

Mejores prácticas

Para garantizar una integración exitosa y segura, recomendamos seguir estas mejores prácticas:

Seguridad

• Nunca almacene datos completos de tarjetas en sus servidores
• Utilice siempre HTTPS para todas las comunicaciones
• Mantenga sus claves API seguras y nunca las exponga en código cliente
• Valide siempre la firma de los webhooks para prevenir ataques

Experiencia de usuario

• Proporcione feedback claro durante el proceso de pago
• Implemente validación en tiempo real para reducir errores
• Ofrezca múltiples métodos de pago para maximizar conversiones
• Optimice la experiencia móvil (más del 60% de las transacciones ocurren en dispositivos móviles)

Robustez

• Implemente manejo de errores adecuado en todos los puntos de integración
• Utilice idempotency keys para prevenir transacciones duplicadas
• Configure alertas para fallos en webhooks o tasas altas de rechazo
• Pruebe exhaustivamente en el entorno sandbox antes de pasar a producción

Solución de problemas comunes

Aquí hay algunas soluciones para problemas frecuentes durante la integración:

Conclusión

La integración del SDK de Youfunatt le permite ofrecer una experiencia de pago segura, flexible y optimizada para sus clientes. Siguiendo esta guía paso a paso, debería poder implementar rápidamente una solución de pago robusta en su plataforma.

Recuerde que nuestro equipo de soporte está disponible para ayudarle con cualquier duda o problema durante el proceso de integración. No dude en contactarnos si necesita asistencia adicional.