@insoutt/datafast-react

@insoutt/datafast-react es una librería de React que permite integrar Datafast y facilita la interacción con el flujo de pago. Permite implementar una interfaz personalizada y robusta sobre el widget de Datafast de manera rápida.

Instalación

Para instalar ejecuta el siguiente comando en el proyecto: yarn add @insoutt/datafast-react o npm i @insoutt/datafast-react

Luego debes importar los estilos en la raíz del proyecto, por lo general suele ser en App.tsx.

import '@insoutt/datafast-react/dist/styles.css';

Listo ya puedes realizar tu integración con Datafast.

Componentes

Datafast

Renderiza el formulario de pago de Datafast y carga el script remoto. Soporta modo redirection e inline (iframe de respuesta) y permite personalizar textos y comportamiento del widget.

Props

| Prop | Tipo | Requerido | Default | Descripción | | ------------------------- | ---------------------------------- | --------- | --------------------------------------- | ------------------------------------------------------------------------------------------------------ | | checkoutId | string | Sí | — | ID de pago generado en el backend. | | callbackUrl | string | Sí | — | URL de retorno del pago. En modo inline se carga dentro del iframe. | | title | string | No | Información de pago | Título del encabezado. | | description | string | No | Ingresa los datos de tu tarjeta | Texto descriptivo del encabezado. | | rememberCard | boolean | No | false | Muestra el checkbox para recordar tarjeta. | | rememberCardLabel | string | No | Recordar tarjeta para futuras compras | Etiqueta del checkbox de recordar tarjeta. | | rememberCardDescription | string | No | '' | Texto de ayuda opcional debajo del checkbox de recordar tarjeta. | | amount | number | No | 0 | Muestra el resumen “Total a pagar” cuando es mayor a 0. | | type | 'redirection' \| 'inline' | No | redirection | Modo de respuesta del pago. inline muestra un iframe. | | availableBrands | string[] | No | ['VISA','MASTER','AMEX'] | Marcas de tarjeta disponibles para el widget. | | theme | DatafastTheme | No | — | Personaliza los colores del componente. Ver Personalización de colores. | | config | Omit<WpwlOptions,'style'> | No | — | Opciones avanzadas de WPWL (labels, callbacks como onReady/onError, etc). | | loadingTitle | string | No | Cargando formulario de pago | Título del estado de carga. | | loadingDescription | string | No | Esto puede tardar unos segundos. | Descripción del estado de carga. | | onResponsePayment | (data: any) => void | No | — | Callback cuando se recibe la respuesta del pago. | | onScriptError | (error: Event \| string) => void | No | — | Callback cuando falla la carga del script remoto de Datafast (red bloqueada, ad blockers, etc). | | action | 'checkout' \| 'registration' | No | checkout | checkout para cobros normales; registration para guardar tarjeta sin cobrar. | | isTest | boolean | No | true | Usa el script de entorno de pruebas. |

Ejemplo mínimo

import { Datafast } from '@insoutt/datafast-react';

<Datafast
  checkoutId={checkoutId}
  callbackUrl="https://mi-sitio.com/pago/resultado"
  amount={19.99}
  availableBrands={['VISA', 'MASTER']}
/>;

Personalización de colores

Datafast acepta la prop theme para personalizar los colores del formulario. Cada token se aplica tanto a la interfaz de React como a los elementos del widget de Datafast (.wpwl-*).

import { Datafast, type DatafastTheme } from '@insoutt/datafast-react';

const theme: DatafastTheme = {
  background: '#ffffff',
  text: '#0f172a',
  border: '#e2e8f0',
  buttonBackground: '#2563eb',
  buttonText: '#ffffff',
  fieldBackground: '#f1f5f9',
  // Modo oscuro (opcional)
  dark: {
    background: '#0f172a',
    buttonBackground: '#3b82f6',
  },
};

<Datafast checkoutId={checkoutId} callbackUrl="..." theme={theme} />;

Todos los tokens son opcionales y aceptan cualquier color CSS (string). Lo que no definas conserva el valor por defecto.

| Token | Descripción | | ------------------------------ | --------------------------------------------------------------------------------- | | background | Fondo de la tarjeta. | | text | Color de texto principal (títulos, montos). | | mutedText | Texto secundario (descripciones, ayudas). | | border | Color de bordes de la tarjeta, separador y formulario. | | buttonBackground | Fondo del botón de pago. | | buttonText | Texto del botón de pago. | | registrationButtonBackground | Fondo del botón “Pagar con otra tarjeta” (visible cuando hay tarjetas guardadas). | | registrationButtonText | Texto del botón “Pagar con otra tarjeta”. | | fieldBackground | Fondo de los campos de entrada. | | fieldText | Color del texto de los campos. | | dark | Objeto con los mismos tokens; se aplica en modo oscuro (ver abajo). |

Modo oscuro

El modo oscuro es opt-in y depende de la clave dark:

• Sin dark: el componente permanece siempre en modo claro, aunque el sistema operativo use tema oscuro.
• Con dark: el componente sigue la preferencia del sistema (prefers-color-scheme) y aplica los colores de dark cuando el SO está en modo oscuro.
• Usa dark: {} (objeto vacío) para activar el modo oscuro con la paleta oscura por defecto.

Cualquier token que no definas dentro de dark usa su valor oscuro por defecto.

Limitación

Los campos de número de tarjeta y CVV se renderizan dentro de iframes de origen cruzado, por lo que el color del texto que se escribe en ellos no es personalizable. El fondo sí respeta fieldBackground y el color del placeholder se toma de mutedText.

PaymentButton

Botón que crea el checkout y devuelve checkoutId para renderizar el widget de Datafast. Permite render-prop para personalizar el UI.

Props

| Prop | Tipo | Requerido | Default | Descripción | | -------------- | -------------------------------------------------------------------------- | --------- | ------------------- | ---------------------------------------------------------------------------------------------------------- | | url | string | Sí | — | Endpoint backend que crea el checkout. | | publicToken | string | Sí | — | Token público enviado como Authorization: Bearer al backend al crear el checkout. | | checkoutUrl | string | Sí | — | URL del sandbox de pago a renderizar en el iframe. Debe contener :id, que se reemplaza por checkoutId. | | checkoutData | CheckoutData | Sí | — | Datos del cliente y carrito enviados al backend. En type='registration' se omite cart. | | onSuccess | (data: { checkoutId: string; }) => void | Sí | — | Se ejecuta cuando el backend retorna el checkout. | | onError | (error: Error) => void | Sí | — | Se ejecuta cuando falla la creación del checkout. | | onClose | () => void | No | — | Se ejecuta cuando el usuario cierra el modal del checkout. | | type | 'checkout' \| 'registration' | No | checkout | checkout para cobros; registration para guardar tarjeta sin cobrar (omite cart en checkoutData). | | text | string | No | Pagar con tarjeta | Texto del botón por defecto. | | variant | 'primary' \| 'dark' | No | primary | Estilo visual del botón. | | children | (props: { isLoading: boolean; createCheckout: () => void }) => ReactNode | No | — | Render-prop para UI personalizado. |

CheckoutData incluye customer (datos del cliente) y cart.items (items del carrito).

Para que PaymentButton funcione correctamente, el backend debe responder un JSON usando la siguiente estructura:

{
  "data": {
    "id": "79E1E1EBB41134A257CB8D22280D6BBC.uat01-vm-tx01" // id generado en el backend
  }
}

Uso

import { useState } from 'react';
import { PaymentButton, Datafast } from '@insoutt/datafast-react';

function CheckoutExample() {
  const [checkoutId, setCheckoutId] = useState<string | null>(null);

  return (
    <>
      <PaymentButton
        url="https://mi-backend.com/checkout"
        publicToken="pk_..."
        checkoutUrl="https://mi-sitio.com/pago/sandbox/:id"
        checkoutData={{
          customer: {
            givenName: 'Juan',
            surname: 'Pérez',
            email: '[email protected]',
            phone: '0999999999',
            identificationDocId: '0102030405',
          },
          cart: {
            items: [
              {
                name: 'Producto A',
                description: 'Descripción',
                val_base0: 0,
                val_baseimp: 19.99,
                val_iva: 2.4,
                quantity: 1,
              },
            ],
          },
        }}
        onSuccess={({ checkoutId }) => setCheckoutId(checkoutId)}
        onError={(error) => console.error(error)}
      />

      {checkoutId && (
        <Datafast
          checkoutId={checkoutId}
          callbackUrl="https://mi-sitio.com/pago/resultado"
        />
      )}
    </>
  );
}

Ejemplo botón de pagos personalizado

import { PaymentButton } from '@insoutt/datafast-react';

<PaymentButton
  url="https://mi-backend.com/checkout"
  publicToken="pk_..."
  checkoutUrl="https://mi-sitio.com/pago/sandbox/:id"
  checkoutData={checkoutData}
  onSuccess={({ checkoutId }) => console.log('checkoutId', checkoutId)}
  onError={(error) => console.error(error)}
>
  {({ isLoading, createCheckout }) => (
    <button
      onClick={createCheckout}
      disabled={isLoading}
      className="mi-boton-personalizado"
    >
      {isLoading ? 'Procesando...' : 'Pagar ahora'}
    </button>
  )}
</PaymentButton>;

Contact

• 𝕏 (Twitter): @insoutt
• Sitio Web: elvisfernando.com