Saltar al contenido

API Reference

API v0.1.0
En esta página

Referencia completa del API del widget. Todos los símbolos están tipados en TypeScript (@rutiva/widget incluye .d.ts).

Rutiva(options) — factory

typescript
type RutivaOptions = {
  publishableKey: string;          // "pk_test_..." o "pk_live_..."
  apiBaseUrl?: string;             // default "https://rutiva-api.onrender.com"
  locale?: "es-VE" | "es" | "en";  // default "es-VE"
};

Devuelve { elements, banks }.

rutiva.elements(config) — crear widget

typescript
type ElementsConfig = {
  clientSecret: string;
  appearance?: {
    theme?: "light" | "dark" | "auto";   // "auto" sigue prefers-color-scheme
    primaryColor?: string;                // default "#0F172A"
    borderRadius?: string;                // default "8px"
    fontFamily?: string;                  // default system font stack
  };
  locale?: "es-VE" | "es" | "en";
};

Devuelve un RutivaWidget.

rutiva.banks() — listar bancos

typescript
const banks = await rutiva.banks();
// [{ code: "0114", name: "Banco habilitado" }, ...]

Útil si quieres renderizar el dropdown de bancos en tu UI (el widget ya lo hace internamente). Ver /docs/bancos.

RutivaWidget

typescript
type RutivaWidget = {
  mount: (target: string | HTMLElement) => void;   // CSS selector o nodo
  unmount: () => void;                             // remueve UI, conserva listeners
  on: (event, handler) => () => void;              // retorna off()
  off: (event, handler) => void;
  destroy: () => void;                             // unmount + clear listeners
};

Eventos

EventoPayloadCuándo se emite
ready—Widget montado + bancos cargados.
loading—Submit en curso.
successPaymentIntentPago aprobado.
declinedPaymentIntentBanco rechazó (failure_code).
expired{ code, message }payment_intent expiró (>15 min).
error{ code, message }Red, validación o respuesta inesperada.

on() devuelve una función off() para desuscribir.

Types

typescript
type PaymentIntent = {
  id: string;
  status: "created" | "succeeded" | "failed" | "canceled";
  bank_reference?: string;
  succeeded_at?: string;
  failure_code?: string;
  failure_message?: string;
  amount_cents?: number;
  currency?: "VES" | "USD";
};

type WidgetEventPayload = {
  ready: void;
  loading: void;
  success: PaymentIntent;
  error: { code: string; message: string };
  expired: { code: "payment_expired"; message: string };
  declined: PaymentIntent;
};