@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';<DatafastcheckoutId={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,typeDatafastTheme}from'@insoutt/datafast-react';consttheme: DatafastTheme={background: '#ffffff',text: '#0f172a',border: '#e2e8f0',buttonBackground: '#2563eb',buttonText: '#ffffff',fieldBackground: '#f1f5f9',// Modo oscuro (opcional)dark: {background: '#0f172a',buttonBackground: '#3b82f6',},};<DatafastcheckoutId={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';functionCheckoutExample(){const[checkoutId,setCheckoutId]=useState<string|null>(null);return(<><PaymentButtonurl="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&&(<DatafastcheckoutId={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:

interfacePendingTransactionData{/** 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 cobrarmostrarMensaje(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';<PaymentButtonurl="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 })=>(<buttononClick={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

(back to top)

Publicación

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