@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. Su origen es el único aceptado para los mensajes del checkout. | | 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. | | onSuccessTransaction | (data: SuccessTransactionData) => void | No | — | Pago liquidado. Ver Estados de la transacción. | | onErrorTransaction | (error: ErrorTransactionData) => void | No | — | Rechazo real del emisor. Ver Estados de la transacción. | | onPendingTransaction | (data: PendingTransactionData) => void | No | — | Pago no liquidado: ni éxito ni rechazo. Ver Estados de la transacción. | | 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).

Validación de origen

Sólo se procesan los mensajes cuyo event.origin coincide con el origen de checkoutUrl. El botón puede vivir en un dominio distinto al del checkout: lo que se compara es el origen del iframe, no el de la página que hospeda el botón.

Un checkoutUrl relativo (/pago/sandbox/:id) se resuelve contra la página actual, así que el origen esperado pasa a ser el propio. Si no se puede determinar un origen esperado, no se acepta ningún mensaje.

Si el iframe redirige a otro dominio (3DS del emisor, dominio de la pasarela) y el resultado se publica desde ahí, el mensaje se descarta. useMessage debe ejecutarse en una página servida desde el origen de checkoutUrl.

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"
        />
      )}
    </>
  );
}

Estados de la transacción

El resultado del pago llega al comercio por uno de tres callbacks. Sólo se entrega uno por checkout: los mensajes repetidos se descartan.

| Callback | Estado del pago | Qué debe hacer el comercio | | ---------------------- | ----------------------------------------- | ------------------------------------------------------------------------- | | onSuccessTransaction | Liquidado. | Entregar el pedido. | | onErrorTransaction | Rechazo real del emisor. | Marcar el pedido como rechazado. | | onPendingTransaction | No liquidado: in_review o unresolved. | Retener el pedido. No rechazar, no reembolsar, nunca volver a cobrar. |

onPendingTransaction recibe:

interface PendingTransactionData {
  /** UUID de la transacción. Coincide con `data.id` del webhook que la resuelve. */
  id: string;
  status: 'in_review' | 'unresolved';
  /** Mensaje para el usuario, ya localizado por la pasarela. */
  message: string;
}

• in_review: la tarjeta sí fue cobrada y un operador está revisando el pago.
• unresolved: la pasarela no dio veredicto; la tarjeta puede haber sido cobrada.

En ambos casos la resolución llega después por webhook (transaction.succeeded o transaction.failed), correlacionable por id. Los tres callbacks reciben id, así que conviene guardarlo junto al pedido para conciliar el webhook.

Si llega un pending-transaction y no se definió onPendingTransaction, el paquete emite un console.warn en desarrollo y no dispara ningún callback: el pedido no se retiene, pero tampoco se reporta un falso rechazo. El resultado queda sin consumir, así que un mensaje posterior todavía puede entregarse.

<PaymentButton
  // ...
  onSuccessTransaction={({ id }) => marcarPagado(id)}
  onErrorTransaction={({ id }) => marcarRechazado(id)}
  onPendingTransaction={({ id, status, message }) => {
    retenerPedido(id, status); // esperar el webhook, no volver a cobrar
    mostrarMensaje(message);
  }}
/>

Sin actualizar a 3.0.0

En versiones 2.x estos estados llegaban como onErrorTransaction con code: 'in_review'. Si no se puede actualizar, ese caso debe tratarse como "retener y esperar el webhook", nunca como rechazo.

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>;

Hooks

useMessage

Se usa dentro del iframe de checkout para comunicar el resultado a la página del comercio.

const {
  onSuccessTransaction, // pago liquidado
  onErrorTransaction, // rechazo real del emisor
  onPendingTransaction, // no liquidado: in_review | unresolved
  sendHeight,
  sendClose,
  pingParent,
} = useMessage({ targetOrigin: 'https://mi-sitio.com' });

onPendingTransaction({ id, status: 'in_review', message });

• Los tres callbacks de resultado deben incluir id (UUID de la transacción).
• targetOrigin es opcional (default '*'); fijarlo evita que el payload viaje a cualquier página que embeba el iframe.
• onSucessTransaction (sin la segunda s) fue eliminado: usar onSuccessTransaction.

targetOrigin es el origen del comercio, no el del checkout. Si el checkout se sirve desde https://pagos.test y el botón vive en https://tienda.test, el valor correcto es https://tienda.test — el de la página que embebe el iframe. Apuntarlo al propio origen del checkout hace que el mensaje nunca llegue. Si el mismo checkout atiende a varios comercios, hay que resolverlo por checkout (dominio guardado con el pedido, o document.referrer) en lugar de dejarlo en '*'.

Contact

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

Publicación

El proceso de release está automatizado. Ver docs/releasing.md.