@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: 'juan@mail.com',
            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

(back to top)