Empieza a usar los componentes integrados de Connect

Descubre cómo integrar las funciones del Dashboard en tu sitio web.

Utiliza los componentes integrados de Connect para añadir las funciones del Dashboard de cuentas conectadas a tu sitio web. Estas bibliotecas y su API de soporte te permiten otorgar a tus usuarios acceso a los productos de Stripe directamente en tu Dashboard y aplicaciones móviles.

Web

iOS

Android

Para obtener una versión inmersiva de esta guía, consulta la guía de inicio rápido de la integración de componentes integrados de Connect. También puedes descargar una integración de muestra desde allí. Para personalizar la apariencia de los componentes integrados de Connect, utiliza las opciones de appearance cuando inicialices StripeConnectInstance. Consulta la lista completa de parámetros de apariencia.

Inicia Connect.js
Lado del cliente
Lado del servidor

Stripe utiliza una AccountSession para expresar tu intención de delegar el acceso a la API a tu cuenta conectada.

La API de AccountSessions devuelve un secreto de cliente que permite que un componente integrado acceda a los recursos de una cuenta conectada como si estuvieras haciendo las llamadas a la API para ellos.

Crea una AccountSession Server

En una aplicación de una sola página, tu cliente inicia una solicitud para obtener la sesión de la cuenta en tu servidor. Puedes crear un nuevo punto de conexión en tu servidor que devuelva el secreto de cliente al navegador:

Crear una API Account Session

La API Create Account Session determina el acceso a los componentes y funciones para los componentes integrados de Connect. Stripe aplica estos parámetros para cualquier componente que corresponda a la sesión de la cuenta. Si tu sitio acepta varias funciones de usuario, asegúrate de que los componentes y las funciones que están habilitados para esa sesión de cuenta correspondan a la función del usuario actual. Por ejemplo, puedes habilitar la gestión de reembolsos solo para los administradores de tu sitio, pero no para otros usuarios. Para asegurarse de que se aplica el acceso a la función de usuario, debes asignar la función de usuario de tu sitio a los componentes de la sesión de la cuenta.

Configura Connect.js Client

Recomendamos configurar Connect.js con npm como se muestra en el siguiente ejemplo, aunque también es posible sin npm.

Instala el paquete de npm para usar Connect.js como módulo.

Command Line
npm install --save @stripe/connect-js

Carga e inicializa Connect.js Client

Llama a loadConnectAndInitialize con tu clave publicable y una función que recupera un secreto de cliente llamando al nuevo punto de conexión que creaste en tu servidor. Utiliza la StripeConnectInstance devuelta para crear componentes integrados. Después de inicializar Connect.js, puedes montar o desmontar componentes del DOM en cualquier momento. Eso incluye cualquier elemento renderizado dentro de los portales de React o Vue.

Para crear un componente, llama a create en el StripeConnectInstance que creaste anteriormente y después pasa el nombre del componente. Esto devuelve un elemento personalizado que Connect.js registra y utiliza para conectar automáticamente tu DOM a Stripe. A continuación, puedes utilizar append para adjuntar este elemento a tu DOM.

Llama a create con payments y después añade el resultado a tu DOM para renderizar una interfaz de usuario de usuario de pagos.

Consulta la lista completa de los componentes integrados compatibles →

Configure Connect.js
Lado del cliente

El método loadConnectAndInitialize del cliente utiliza varias opciones diferentes para configurar Connect.js.

Opción	Descripción
`publishableKey`	La clave publicable de tu integración.	obligatorio
`fetchClientSecret`	La función que recupera el secreto de cliente devuelto por `/v1/account_sessions`. Esto le indica a `StripeConnectInstance` a qué cuenta delegar el acceso. Esta función también se utiliza para recuperar una función del secreto de cliente con el fin de actualizar la sesión cuando caduca. `fetchClientSecret` siempre debe crear una nueva sesión de cuenta y devolver un `client_secret` nuevo.	obligatorio
`appearance`	Objeto para personalizar el aspecto de los componentes integrados de Connect.	opcional
`locale`	Parámetro para especificar la configuración regional que utilizan los componentes integrados de Connect. La configuración regional predeterminada es el idioma del navegador. Si la configuración regional especificada no es compatible directamente, utilizamos una alternativa razonable (por ejemplo, `fr-be` podría cambiar a `fr-fr`). Consulta localización para ver la lista de configuraciones regionales aceptadas.	opcional
`fonts`	Una matriz de fuentes personalizadas disponibles para utilizar con cualquier componente integrado creado a partir de una `StripeConnectInstance`. Puedes especificar fuentes como objetos CssFontSource o CustomFontSource.	opcional

Personaliza el aspecto de los componentes integrados de Connect

El conjunto de herramientas de interfaz de usuario Figma para componentes incorporados contiene todos los componentes, patrones comunes y una aplicación de ejemplo. Puedes usarlo para visualizar y diseñar interfaces de usuario integradas en tu sitio web.

Ofrecemos un conjunto de opciones para personalizar el aspecto y el estilo de los componentes integrados de Connect. Estas personalizaciones afectan los botones, los iconos y otros acentos de nuestro sistema de diseño.

Ventanas emergentes necesarias

Algunos comportamientos de los componentes integrados, como la autenticación de usuarios, se deben presentar en una ventana emergente. No se puede personalizar el componente integrado para eliminar estas ventanas emergentes.

Puedes configurar estas opciones al inicializar StripeConnectInstance pasando una apariencia al objeto appearance. Solo puedes usar las opciones Connect.js para modificar estilos en los componentes integrados de Connect. La familia tipográfica y el color de fondo de los componentes integrados de Connect se pueden anular con los selectores CSS, pero Stripe no acepta la anulación de ningún otro estilo.

index.js
const stripeConnectInstance = loadConnectAndInitialize({
  publishableKey: "pk_test_TYooMQauvdEDq54NiTphI7jx"
,
  fetchClientSecret: fetchClientSecret,
  fonts: [
    {
      cssSrc: "https://myfonts.example.com/mycssfile.css",
    },
    {
      src: `url(https://my-domain.com/assets/my-font-2.woff)`,
      family: 'My Font'
    }
  ],
  appearance: {
    // See all possible variables below
    overlays: "dialog",
    variables: {
      fontFamily: 'My Font',
      colorPrimary: "#FF0000",
    },
  },
});

El objeto Fonts

El objeto fonts en stripeConnect.initialize toma una matriz de objetos CssFontSource o CustomFontSource.

Si utilizas fuentes personalizadas en tu página (por ejemplo, archivos .woff o .tff), debes especificar los archivos de fuentes cuando inicialices los componentes integrados de Connect. Si lo haces, permitirás que los componentes integrados de Connect rendericen correctamente las fuentes. Puede especificar los archivos de la siguiente manera:

CssFontSource

Utiliza este objeto para pasar una URL de hoja de estilo que defina tus fuentes personalizadas al crear un StripeConnectInstance. Con un objeto CssFontSource, tu configuración CSP debe permitir obtener los dominios asociados a las URL del archivo CSS especificadas como CssFontSource.

Nombre	Tipo	Valor de ejemplo
`cssSrc`	cadena `required`	`https://fonts.googleapis.com/css?family=Open+Sans`
Una URL relativa o absoluta que señala a un archivo CSS con definiciones de @font-face. El archivo debe estar alojado en https. Si usas una directiva de seguridad de contenido (CSP), es posible que el archivo requiera más directivas.

CustomFontSource

Utiliza este objeto para pasar fuentes personalizadas al crear un StripeConnectInstance.

Nombre	Tipo	Valor de ejemplo
`family`	cadena `required`	`Avenir`
El nombre que se dará a la fuente.
`src`	cadena `required`	`url(https://my-domain.com/assets/avenir.woff)`
Un valor src válido que señala a tu archivo de fuentes personalizado. Suele ser un enlace a un archivo con sufijo `.woff` `.otf` o `.svg`, pero no siempre. El archivo debe estar alojado en https.
`display`	cadena `optional`	`auto`
Un valor válido de font-display.
`style`	cadena `optional`	`normal`
Uno de los siguientes: `normal`, `italic` u `oblique`.
`unicodeRange`	cadena `optional`	`U+0-7F`
Un valor válido de unicode-range.
`weight`	cadena `optional`	`400`
Un font-weight válido. Se trata de una cadena, no de un número.

El objeto Appearance

El objeto appearance en loadConnectAndInitialize adopta las siguientes propiedades opcionales:

Nombre	Tipo	Valor de ejemplo
`overlays`	‘dialog’ (predeterminado) \| ‘drawer’	`dialog`
El tipo de superposición utilizado en todo el sistema de diseño Connect.js. Configúralo para que sea un Dialog o un Drawer.
`variables`	objeto	`{colorPrimary: "#0074D4"}`
Consulta la lista completa de variables de apariencia.

Actualiza los componentes integrados de Connect después de la inicialización

El método update acepta la actualización de los componentes integrados de Connect después de la inicialización. Puede usarlo para cambiar las opciones de apariencia en tiempo de ejecución (sin actualizar la página). Para hacerlo, usa el mismo objeto stripeConnectInstance que creaste con initialize y llama al método update:

index.js
stripeConnectInstance.update({
  appearance: {
    variables: {
      colorPrimary: "#FF0000",
    },
  },
  locale: 'en-US',
});

Nota

No todas las opciones son actualizables (por ejemplo, fonts). Las opciones aceptadas para este método son un subconjunto de las opciones ofrecidas en initialize. Esto permite actualizar appearance y locale.

Ancho y altura

Los componentes integrados de Connect se comportan como elementos HTML block normales. De forma predeterminada, toman el 100 % de width de su elemento HTML principal y crecen en altura de acuerdo con el contenido renderizado en su interior. Puedes controlar el width de los componentes integrados de Connect especificando el width del HTML principal. No puedes controlar directamente el height, ya que depende del contenido renderizado; sin embargo, puedes limitar la altura con maxHeight y overflow: scroll, de la misma manera que puedes hacerlo con otros elementos HTML block.

Autenticación

Ofrecemos un conjunto de API para gestionar las sesiones de la cuenta y las credenciales de usuario en los componentes integrados de Connect.

Actualizar el secreto de cliente

En sesiones de larga duración, podría caducar la sesión del secreto de cliente que se proporcionó inicialmente. Cuando caduca, usamos automáticamente fetchClientSecret para recuperar un nuevo secreto de cliente y actualizar la sesión. No es necesario que especifiques ningún otro parámetro.

index.js
import { loadConnectAndInitialize } from "@stripe/connect-js";
// Example method to retrieve the client secret from your server
const fetchClientSecret = async () => {
  const response = await fetch('/account_session', { method: "POST" });
  const {client_secret: clientSecret} = await response.json();
  return clientSecret;
}

const stripeConnectInstance = loadConnectAndInitialize({
  publishableKey: "{{PUBLISHABLE_KEY}}",
  fetchClientSecret: fetchClientSecret,
});

Salir de la sesión

Te recomendamos que llames a logout en stripeConnectInstance para destruir el objeto de sesión de la cuenta asociada después de que un usuario salga de la sesión de tu aplicación. Esto deshabilita todos los componentes integrados de Connect que se vinculan a esa stripeConnectInstance.

index.js
// Call this when your user logs out
stripeConnectInstance.logout();

Requisitos de encabezado CSP y HTTP

Si tu sitio web implementa una Política de seguridad de contenidos, debes actualizarla añadiendo las siguientes reglas:

frame-src https://connect-js.stripe.com https://js.stripe.com
img-src https://*.stripe.com
script-src https://connect-js.stripe.com https://js.stripe.com
style-src sha256-0hAheEzaMe6uXIKV4EehS9pu1am1lj/KnnzrOYqckXk= (SHA del elemento de estilo vacío)

Si utilizas un archivo CSS para cargar fuentes web con el fin de utilizarlas con componentes integrados de Connect, tu directiva CSP connect-src debe autorizar su URL.

La configuración de ciertos encabezados de respuesta HTTP permite utilizar todas las funciones de los componentes integrados de Connect:

Política de apertura de origen cruzado, unsafe-none. Este (unsafe-none) es el valor predeterminado del encabezado, por lo que funciona no configurar este encabezado. Otros valores como same-origin rompen la autenticación de usuario en los componentes integrados de Connect.

Navegadores compatibles

Aceptamos el mismo conjunto de navegadores que el Dashboard de Stripe actualmente:

Las 20 versiones más recientes de Chrome y Firefox
Las dos versiones principales más recientes de Safari y Edge
Las dos versiones principales más recientes de Safari para dispositivos móviles en iOS

Los componentes integrados de Connect solo son compatibles con navegadores web y no se pueden usar en vistas web integradas dentro de aplicaciones móviles o de ordenador.

Localización

Al inicializar Connect.js, puedes pasar un parámetro locale. Para que la configuración regional de un componente integrado coincida con la configuración regional de tu sitio web, pasa el parámetro locale con la configuración regional de la interfaz de usuario que representa tu sitio web.

El valor predeterminado del parámetro locale está determinado por la configuración regional configurada por el navegador. Si la configuración regional especificada no es compatible directamente, se utiliza una alternativa razonable (por ejemplo, fr-be podría cambiar a fr-fr).

Los componentes integrados de Connect aceptan las siguientes configuraciones regionales:

Idioma	Código de configuración regional
Búlgaro (Bulgaria)	`bg-BG`
Chino (simplificado)	`zh-Hans`
Chino (tradicional de Hong Kong)	`zh-Hant-HK`
Chino (tradicional de Taiwán)	`zh-Hant-TW`
Croata (Croacia)	`hr-HR`
Checo (República Checa)	`cs-CZ`
Danés (Dinamarca)	`da-DK`
Neerlandés (Países Bajos)	`nl-NL`
Inglés (Australia)	`en-AU`
Inglés (India)	`en-IN`
Inglés (Irlanda)	`en-IE`
Inglés (Nueva Zelanda)	`en-NZ`
Inglés (Singapur)	`en-SG`
Inglés (Reino Unido)	`en-GB`
Inglés (Estados Unidos)	`en-US`
Estonio (Estonia)	`et-EE`
Filipino (Filipinas)	`fil-PH`
Finlandés (Finlandia)	`fi-FI`
Francés (Canadá)	`fr-CA`
Francés (Francia)	`fr-FR`
Alemán (Alemania)	`de-DE`
Griego (Grecia)	`el-GR`
Húngaro (Hungría)	`hu-HU`
Indonesio (Indonesia)	`id-ID`
Italiano (Italia)	`it-IT`
Japonés (Japón)	`ja-JP`
Coreano (Corea del Sur)	`ko-KR`
Letón (Letonia)	`lv-LV`
Lituano (Lituania)	`lt-LT`
Malayo (Malasia)	`ms-MY`
Maltés (Malta)	`mt-MT`
Noruego bokmål (Noruega)	`nb-NO`
Polaco (Polonia)	`pl-PL`
Portugués (Brasil)	`pt-BR`
Portugués (Portugal)	`pt-PT`
Rumano (Rumania)	`ro-RO`
Eslovaco (Eslovaquia)	`sk-SK`
Esloveno (Eslovenia)	`sl-SI`
Español (Argentina)	`es-AR`
Español (Brasil)	`es-BR`
Español (Latinoamérica)	`es-419`
Español (México)	`es-MX`
Español (España)	`es-ES`
Sueco (Suecia)	`sv-SE`
Tailandés (Tailandia)	`th-TH`
Turco (Turquía)	`tr-TR`
Vietnamita (Vietnam)	`vi-VN`

Gestiona los errores de carga

Si un componente no se carga, puedes reaccionar al error proporcionando un controlador de errores de carga a cualquier componente integrado. En función de la causa del fallo, se puede llamar varias veces al controlador de errores de carga. Cualquier lógica activada por un controlador de errores de carga debe ser idempotente.

Método	Descripción	Variables
`setOnLoadError`	El componente ejecuta esta función de devolución de llamada cuando se produce un error de carga.	`loadError.error`: Ver el objeto de error de carga `loadError.elementTagName`: El nombre de la etiqueta HTML utilizada para representar el componente en el navegador

El objeto de carga `error`

Cada vez que hay un error en la carga, se pasa un objeto error al controlador de errores de carga con las siguientes propiedades.

Nombre	Tipo	Valor de ejemplo
`type`	Consulta tipos de errores de carga	`authentication_error`
El tipo de error
`message`	cadena \| indefinido	`Failed to fetch account session`
Más información sobre el error

Tipos de fallos de carga

Cuando un componente no se carga, detectamos el tipo de error y lo asignamos a uno de los siguientes tipos. Si no se puede determinar el tipo de error de carga, se marca como api_error.

Tipo	Descripción
`api_connection_error`	Error al establecer la conexión con la API de Stripe
`authentication_error`	Error al realizar el flujo de autenticación dentro de los componentes integrados de Connect
`account_session_create_error`	Error al crear la sesión de la cuenta
`invalid_request_error`	La solicitud ha fallado con un código de estado 4xx, generalmente debido a problemas de configuración de la plataforma
`rate_limit_error`	La petición ha fallado porque se ha detectado una tasa de peticiones anormal
`api_error`	Errores de API que abarcan cualquier otro tipo de problema, como un problema temporal en los servidores de Stripe.

Detecta la visualización de los componentes integrados

Después de crear un componente, no se muestra ninguna interfaz de usuario a los usuarios hasta que el javascript del componente se carga y analiza en el navegador. Esto puede hacer que los componentes aparezcan después de completar la carga. Para evitarlo, muestra tu propia interfaz de usuario de carga antes de crear el componente y ocúltala después de que se muestre el componente. Todos los componentes integrados pueden aceptar una función de devolución de llamada a la que se llama inmediatamente cuando se muestra al usuario cualquier interfaz de usuario (incluidos los indicadores de carga).

Método	Descripción	Variables
`setOnLoaderStart`	El componente ejecuta esta función de devolución de llamada cuando se muestra al usuario cualquier interfaz de usuario (incluidos los indicadores de carga).	`event.elementTagName`: El nombre de la etiqueta HTML utilizada para representar el componente en el navegador

Utiliza Connect.js sin npm

Recomendamos la integración con nuestros contenedores de componentes de javascript y de React, que simplifican la carga de los componentes integrados de Connect y proporcionan definiciones de TypeScript para nuestras interfaces compatibles. Si tu sistema de compilación actualmente no admite la dependencia de paquetes, puedes realizar la integración sin estos paquetes.

Añade manualmente la etiqueta de script Connect.js al <head> de cada página de tu sitio.

<!-- Somewhere in your site's <head> -->
<script src="https://connect-js.stripe.com/v1.0/connect.js" async></script>

Una vez Connect.js completa la carga, inicializa la variable StripeConnect de ventana global y llama a StripeConnect.onLoad, si se define. Puedes inicializar Connect.js de forma segura configurando una función onload y llamando a StripeConnect.init con las mismas opciones de Connect.js que loadConnectAndInitialize. Puedes utilizar la instancia de Connect devuelta por init de la misma manera que utilizas la instancia devuelta por loadConnectAndInitialize para crear componentes integrados en una integración HTML + JS.

index.js
window.StripeConnect = window.StripeConnect || {};
StripeConnect.onLoad = () => {
  const stripeConnectInstance = StripeConnect.init({
      // This is a placeholder - it should be replaced with your publishable API key.
      // Sign in to see your own test API key embedded in code samples.
      // Don’t submit any personally identifiable information in requests made with this key.
      publishableKey: "pk_test_TYooMQauvdEDq54NiTphI7jx"
,
      fetchClientSecret: fetchClientSecret,
    });

  const payments = stripeConnectInstance.create('payments');
  document.body.appendChild(payments);
};

Autenticación de usuarios en los componentes integrados de Connect

Por lo general, los componentes integrados de Connect no necesitan la autenticación de usuario. En algunas situaciones, los componentes integrados de Connect requieren que la cuenta conectada inicie sesión con su cuenta de Stripe antes de acceder al componente para proporcionar las funciones necesarias (por ejemplo, escribir información a la entidad jurídica de la cuenta en el caso del componente account onboarding). Es posible que otros componentes requieran autenticación dentro del componente después de que se rendericen inicialmente.

La autenticación es obligatoria para las cuentas conectadas en las que Stripe es responsable de recopilar información actualizada cuando cambian los requisitos. Para las cuentas conectadas en las que eres responsable de recopilar información actualizada cuando los requisitos vencen o cambian, como las cuentas Custom, la autenticación de Stripe se controla mediante la función de sesión de cuenta de disable_stripe_user_authentication. Recomendamos implementar 2FA o medidas de seguridad equivalentes como una práctica recomendada. Para las configuraciones de cuenta que admiten esta función, como Custom, asumes la responsabilidad de las cuentas conectadas si no pueden devolver los saldos negativos.

Componentes que requieren autenticación

La autenticación incluye una ventana emergente propiedad de Stripe. La cuenta conectada debe autenticarse antes de poder continuar con su flujo de trabajo.

Los siguientes componentes requieren que las cuentas conectadas se autentiquen en determinadas situaciones:

Prácticas recomendadas de rendimiento

Para asegurarte de que el tiempo de carga de los componentes integrados de Connect sea lo más corto posible, sigue estas recomendaciones:

Llama a loadConnectAndInitialize lo antes posible en tu flujo.
Crea una única instancia de conexión: Para crear una única instancia de conexión, llama a loadConnectAndInitialize solo una vez por sesión. A continuación, reutiliza esa instancia para crear y gestionar varios componentes. Un error frecuente es crear una instancia de conexión por componente o varias instancias de conexión por sesión. Esto provoca un consumo adicional de recursos y solicitudes de API. Si estás usando React, puedes usar una biblioteca de gestión de estado o un contexto de React para gestionar esta instancia.
Usa la última versión de los SDK adecuados: Utiliza la última versión de los SDK de los paquetes de npm connect-js o react-connect-js. Estos SDK inician los componentes integrados de una manera que maximiza el rendimiento. Se han añadido mejoras de rendimiento a los SDK, por lo que te recomendamos que actualices si estás usando una versión antigua.
Carga el script connect.js lo antes posible en tu flujo: El primer lugar posible para cargar el script es con la inclusión de este script en tu head HTML. También puedes usar el comportamiento predeterminado de nuestros SDK de paquetes de npm, que lo cargan cuando el JavaScript de tu página se carga por primera vez.