SDK v1.0.0

Kustodia.js — Embeddable SDK

Integra el checkout de Kustodia en tu marketplace con un solo <script> tag. Sin dependencias externas, compatible con CSP, responsivo y con soporte de branding personalizado.

Zero Dependencies

Vanilla JS, < 4KB gzip

Custom Branding

Colores y logo propios

CSP-Friendly

No eval(), no inline

1Instalación

Agrega el script a tu HTML. El SDK se carga de forma asíncrona y expone el objeto global Kustodia.

<script src="https://app.kustodia.app/sdk/kustodia.js"></script>

2Inicialización

Llama a Kustodia.init() con tu publishable key (la encuentras en Dashboard → API Keys).

<script>
  Kustodia.init({
    publishableKey: 'kust_test_pk_xxx',
    debug: true // Enable console logs (remove in production)
  });
</script>

3Abrir Checkout

Pasa el UUID del pago (obtenido de la API POST /api/v1/payments) y los callbacks:

// Open checkout for a payment
document.getElementById('pay-btn').addEventListener('click', () => {
  Kustodia.openCheckout('PAYMENT_UUID', {
    onSuccess: (data) => {
      console.log('Payment successful!', data.status);
      // Redirect to success page, update UI, etc.
    },
    onClose: () => {
      console.log('User closed the checkout');
    },
    onStatusChange: (data) => {
      console.log('Status changed:', data.status);
    },
    onError: (error) => {
      console.error('Checkout error:', error);
    },

    // Optional branding
    brandColor: '#FF5500',
    logoUrl: 'https://your-site.com/logo.png'
  });
});

API Reference

Método	Descripción
Kustodia.init(opts)	Inicializa el SDK. `publishableKey` requerido.
Kustodia.openCheckout(id, opts)	Abre el modal del checkout con el payment UUID.
Kustodia.close()	Cierra el modal programáticamente.
Kustodia.isOpen()	Devuelve `true` si el modal está abierto.
Kustodia.version	String con la versión actual del SDK.

Eventos (postMessage)

Evento	Callback	Datos
kustodia:payment_status	onStatusChange / onSuccess	{ status, paymentId }
kustodia:close	onClose	—
kustodia:ready	(internal)	Widget loaded
kustodia:error	onError	{ error }

Personalización (Branding)

brandColor

Color hexadecimal para botones y acentos dentro del widget. Ejemplo: '#FF5500'

logoUrl

URL absoluta de tu logo de marketplace. Se muestra en el header del checkout.

Ejemplo Completo

<!DOCTYPE html>
<html lang="es">
<head>
  <meta charset="UTF-8">
  <title>Mi Marketplace — Checkout</title>
</head>
<body>
  <h1>Pagar con Kustodia</h1>
  <button id="pay-btn">Pagar $5,000 MXN</button>

  <script src="https://app.kustodia.app/sdk/kustodia.js"></script>
  <script>
    Kustodia.init({ publishableKey: 'kust_test_pk_xxx' });

    document.getElementById('pay-btn').onclick = function () {
      Kustodia.openCheckout('abc-123-payment-uuid', {
        onSuccess: function (data) {
          alert('¡Pago exitoso! Estado: ' + data.status);
        },
        brandColor: '#10b981'
      });
    };
  </script>
</body>
</html>

¿Necesitas ayuda?

Contáctanos para soporte de integración personalizada.

Contactar soporte