# Gestiona las cuentas de transferencias para las cuentas conectadas Cómo gestionar cuentas bancarias y tarjetas de débito externas para cuentas conectadas Las cuentas de *transferencias* (A payout is the transfer of funds to an external account, usually a bank account, in the form of a deposit) pueden ser cuentas bancarias o tarjetas de débito. Stripe recomienda recopilar detalles de la cuenta externa con el formulario web Connect Onboarding, que te ayuda a: - Ahorra tiempo de diseño y desarrollo. - Elimina la necesidad de almacenar datos confidenciales como números de cuenta y de enrutamiento en tu servidor. - Elimina la necesidad de crear validaciones de formularios cuando las cuentas conectadas ingresen datos de la cuenta. En EE. UU., también recomendamos usar [Stripe Financial Connections](https://docs.stripe.com/financial-connections.md), que permite que las cuentas conectadas vinculen de forma segura las cuentas financieras a tu empresa. Esto te ayuda a hacer lo siguiente: - Aumentar la conversión del onboarding al evitar que tus cuentas tengan que interrumpir el proceso para localizar sus números de cuenta y de enrutamiento. - Reducir la tasa de fallos en las primeras transferencias eliminando los errores derivados del ingreso manual de los números de enrutamiento y de cuenta. - Elimina la necesidad de almacenar datos confidenciales como números de cuenta y de enrutamiento en tu servidor. - Eliminar la necesidad de crear validaciones de formularios cuando las cuentas ingresan los datos de la cuenta en formularios de onboarding personalizados. - (Solo cuentas v1) Permite que tus cuentas se autentiquen en menos pasos reutilizando los datos de la cuenta bancaria que guardaron en [Link](https://support.stripe.com/questions/link-for-financial-connections-support-for-businesses). Las cuentas que guardan su información de cuenta en cualquiera de las empresas de Stripe que utilizan Link pueden compartir los datos de su cuenta con tu plataforma la próxima vez que utilicen Financial Connections. - Acceder a información adicional sobre la cuenta bancaria externa de una cuenta, como [saldos](https://docs.stripe.com/financial-connections/balances.md), [datos de titularidad](https://docs.stripe.com/financial-connections/ownership.md) y [transacciones](https://docs.stripe.com/financial-connections/transactions.md). Para mitigar el fraude durante el onboarding, verifica esa información, como el nombre y la dirección del titular de la cuenta bancaria externa. Cuando [Link está habilitado](https://dashboard.stripe.com/settings/connect/payouts/external_accounts), no se cobran comisiones por las verificaciones de Financial Connections en el onboarding alojado en Stripe e integrado en él. De lo contrario, se aplican las [tarifas de verificación estándar de Financial Connections](https://stripe.com/financial-connections#pricing). Si utilizas el onboarding de API para tus cuentas conectadas, puedes recopilar datos de la cuenta de transferencias con un formulario personalizado en el flujo de onboarding de tu cuenta. ### Desactivación de la recopilación de cuentas externas En el caso de las cuentas en las que la plataforma es responsable de recopilar los requisitos, como las cuentas Custom, puedes optar por no recopilar información de las cuentas externas en el onboarding. Puedes hacerlo si, por ejemplo, creas tu propio flujo de onboarding en el que quieres recopilar información de cuentas externas. En el onboarding integrado, puede [desactivar el cobro de cuentas externas](https://docs.stripe.com/connect/supported-embedded-components/account-onboarding.md?#external-account-collection) configurando la funcionalidad `external_account_collection` de la sesión de cuenta como falsa. Como alternativa, en hosted onboarding puede ir a su [Configuración de cuentas externas de Connect](https://dashboard.stripe.com/settings/connect/payouts/external_accounts) y, a continuación, en **Cuentas en las que la plataforma es responsable de recopilar los requisitos** habilitar o deshabilitar la recopilación de información de cuentas externas. Tenga en cuenta que esto está desactivado por defecto. ## Recopilación de cuentas externas #### Onboarding alojado o integrado en Stripe El [onboarding alojado e integrado en Stripe](https://docs.stripe.com/connect/onboarding.md) utiliza formularios web que se pueden personalizar por tema al momento de recopilar la información necesaria para incorporar las cuentas conectadas. Pueden recopilar información tanto de cuentas bancarias como de tarjetas de débito. Puedes usar Financial Connections para recopilar datos de la cuenta bancaria, pero no de las tarjetas de débito. En el caso de las cuentas conectadas en las que tu plataforma es responsable de los saldos negativos, puedes personalizar el flujo de recopilación de las cuentas externas en la configuración de [cuentas externas](https://dashboard.stripe.com/settings/connect/payouts/external_accounts). En la configuración de tu **Cuenta externa**, puedes hacer lo siguiente: - Habilitar o deshabilitar el cobro de tarjetas de débito. Para eso, selecciona la opción correspondiente en **¿Permitir tarjetas de débito?**. - Exigir que las cuentas conectadas agreguen al menos una cuenta bancaria antes de poder agregar cualquier otro tipo de cuenta externa, como una tarjeta de débito. Puedes acceder a esta configuración en **¿Solicitar al menos una cuenta bancaria?**. Esto es útil para garantizar la compatibilidad con el [débito automático](https://docs.stripe.com/connect/account-balances.md#automatically-debit-connected-accounts). - Controlar si las cuentas conectadas agregan o no más de una cuenta externa en una moneda determinada. Hay un límite de cinco cuentas externas por moneda. Puedes acceder a esta configuración en **Recopilar varias cuentas externas por cada moneda**. #### Usar Financial Connections de Stripe ### Disponible en - US Las plataformas de Stripe en EE. UU. pueden habilitar [Stripe Financial Connections](https://docs.stripe.com/financial-connections.md) dentro del formulario de onboarding alojado e integrado en Stripe. Para ello, deben seguir estos pasos: 1. Ve a la [configuración de tu cuenta externa](https://dashboard.stripe.com/settings/connect/payouts/external_accounts), donde gestionas las funciones opcionales del onboarding de Connect. 1. En el caso de las cuentas conectadas en las que tu plataforma recopila información de la cuenta cuando cambian los requisitos, debes permitir que el onboarding alojado e integrado en Stripe recopile los datos de la cuenta externa. En **Onboarding alojado en Stripe para cuentas Custom**, permite que Stripe recopile información de las cuentas externas; para ello, activa el botón de alternancia. 1. En **¿Cómo se recopilarán los datos de la cuenta bancaria?**, selecciona **Conexiones financieras **. 1. (Opcional) Solicita permiso para acceder a datos adicionales de las cuentas verificadas al instante con Financial Connections, como saldos, datos de titularidad y transacciones. Si solicitas este acceso adicional, deberás crear una cuenta para Financial Connections de Stripe. Cuando se habilita la recopilación de datos de cuenta externas, el flujo de onboarding solicita que todas las cuentas conectadas autentiquen la cuenta bancaria. ![Imagen que muestra el flujo de Onboarding de Connect que utiliza Financial Connections de Stripe para recopilar una cuenta para transferencias.](https://b.stripecdn.com/docs-statics-srv/assets/connect-custom-onboarding-financial-connections-onboarding.8937a023f6682c90bab8c0b39873909a.png) Un flujo de onboarding de Connect que utiliza Financial Connections de Stripe para recopilar una cuenta para transferencias. Si una cuenta conectada no puede verificar instantáneamente su cuenta bancaria mediante Financial Connections, el proceso de verificación vuelve automáticamente a la entrada manual: ![Imagen en la que se muestra el flujo de onboarding de Connect mediante el cuadro de diálogo de Financial Connections de Stripe para recopilar datos de una cuenta de transferencias con ingreso manual.](https://b.stripecdn.com/docs-statics-srv/assets/connect-custom-onboarding-financial-connections-manual-entry.930da1e01c9026b9014008d75958bc8c.png) Un flujo de onboarding de Connect mediante el cuadro de diálogo de Financial Connections de Stripe para recopilar datos de una cuenta para transferencias con ingreso manual. Después del onboarding, la cuenta bancaria especificada se adjunta automáticamente a la cuenta conectada. ## Recupera los datos de una cuenta de Financial Connections (Server-side) Puedes determinar si una cuenta conectada vinculó una cuenta de Financial Connections mediante su ID de `cuenta` para recuperar cualquier cuenta de Financial Connections vinculada. Especifica el ID de `cuenta` como `account_holder.account` y en el encabezado `Stripe-Account`. ```curl curl -G https://api.stripe.com/v1/financial_connections/accounts \ -u "<>:" \ -H "Stripe-Account: {{CONNECTEDACCOUNT_ID}}" \ -d "account_holder[account]={{CONNECTEDACCOUNT_ID}}" ``` Esto devuelve una respuesta API similar a la siguiente: ```json { "object": "list", "data": [ { "id": "fca_zbyrdjTrwcYZJZc6WBs6GPid", "object": "financial_connections.account", "account_holder": { "account": "{{CONNECTED_ACCOUNT_ID}}", "type": "account" }, ... "supported_payment_method_types": [ "us_bank_account" ] } ... ] } ``` Si aparece alguna cuenta de Financial Connections, indica que la cuenta conectada la vinculó durante el proceso de onboarding. Puedes usar el valor `id` para acceder o actualizar los datos que especificaste en la [configuración de tu cuenta externa](https://dashboard.stripe.com/settings/connect/payouts/external_accounts). Para proteger la privacidad de los datos de tu cuenta conectada, solo puedes acceder a los datos que especificaste. Para comenzar a recuperar los datos de la cuenta, sigue las guías de [saldos](https://docs.stripe.com/financial-connections/balances.md), [titularidad](https://docs.stripe.com/financial-connections/ownership.md) y [transacciones](https://docs.stripe.com/financial-connections/transactions.md). En todas las solicitudes posteriores de recuperación y actualización de cuentas, asegúrate de incluir el encabezado `Stripe-Account` con la ID de la cuenta conectada: ```curl curl https://api.stripe.com/v1/financial_connections/accounts/fca_zbyrdjTrwcYZJZc6WBs6GPid/refresh \ -u "<>:" \ -H "Stripe-Account: {{CONNECTEDACCOUNT_ID}}" \ -d "features[]=balance" ``` #### Habilitar el ingreso manual de los datos de la cuenta bancaria Para permitir que Stripe recopile manualmente los datos de la cuenta bancaria de las cuentas conectadas dentro del formulario de onboarding, sigue estos pasos: 1. Abra los ajustes de Connect y vaya a Transferencias > Cuentas Externas, donde podrá gestionar las opciones de onboarding de Connect. 1. En **¿Cómo se recopilarán los datos de las cuentas bancarias?**, selecciona la opción para recopilar manualmente la información de las cuentas bancarias. 1. En el caso de las cuentas conectadas en las que tu plataforma recopila información de la cuenta cuando cambian los requisitos, debes permitir que el onboarding alojado e integrado en Stripe recopile los datos de la cuenta externa. En **Cuentas en las que la plataforma es responsable de recopilar requisitos**, permite que Stripe recopile información de cuentas externas; para ello, activa el botón de alternancia. ![Imagen que muestra el flujo de Onboarding de Connect a través de un formulario para recopilar una cuenta para transferencias con ingreso manual.](https://b.stripecdn.com/docs-statics-srv/assets/connect-custom-onboarding-payout-manual-entry-form.6764993258659b2ad6517e0825181e49.png) Flujo de onboarding de Connect a través de un formulario para recopilar una cuenta para transferencias con ingreso manual. Cada país tiene un formato ligeramente diferente para los datos de la cuenta bancaria, y el formulario muestra automáticamente los campos apropiados para su país de operación. #### Llamadas directas a la API desde un formulario personalizado Para las cuentas conectadas en las que tu plataforma recopila información de la cuenta cuando cambian los requisitos, puedes recopilar información de la cuenta externa al realizar llamadas directas a la API desde un formulario personalizado. #### Habilitar Financial Connections de Stripe ### Disponible en - US Las plataformas de Stripe en los EE. UU. pueden habilitar [Financial Connections de Stripe](https://stripe.com/financial-connections) en su formulario de onboarding personalizado. Una vez que habilitas Financial Connections en tu formulario, las cuentas conectadas autentican al instante su cuenta bancaria dentro del [flujo de autenticación](https://docs.stripe.com/financial-connections/fundamentals.md#authentication-flow). [Regístrate en Financial Connections](https://dashboard.stripe.com/financial-connections/application) a fin de recibir la aprobación para el acceso en modo activo. ### Crea un SetupIntent (Server-side) Inserta un botón o enlace en tu formulario de onboarding que llame a un punto de conexión del lado del servidor para crear un [SetupIntent](https://docs.stripe.com/api/setup_intents.md). El SetupIntent representa tu intención de recopilar la información de la cuenta bancaria de una cuenta conectada. Por ejemplo, tu botón podría decir **Vincula tu cuenta bancaria**. Te recomendamos que crees un *Customer* (Customer objects represent customers of your business. They let you reuse payment methods and give you the ability to track multiple payments) con una dirección de correo electrónico que corresponda a cada cuenta conectada. Adjuntar un Customer Object permite [consultar las cuentas externas previamente vinculadas](https://docs.stripe.com/api/financial_connections/accounts/list.md) más adelante. Proporciona una dirección de correo electrónico al crear el cliente para que pueda autenticarse en sus cuentas en menos pasos. Esta acción se logra al guardar y reutilizar sus datos bancarios con [Link](https://support.stripe.com/questions/link-for-financial-connections-support-for-businesses) a través del [flujo de autenticación de Financial Connections](https://docs.stripe.com/financial-connections/fundamentals.md#authentication-flow) en distintas empresas que utilizan Stripe. Cuando crees un SetupIntent para recopilar los datos de la cuenta bancaria de una cuenta conectada, establece los siguientes parámetros: 1. Establece el tipo de `customer` en el [ID del cliente](https://docs.stripe.com/api/customers/object.md#customer_object-id) 1. Establece `payment_method_types` en `["us_bank_account"]` 1. Establece `flow_directions` en `["outbound"]` 1. (Opcional) Considera los datos adicionales necesarios para completar tu caso de uso y solicita permiso para acceder a él. Por ejemplo, establece `payment_method_options[us_bank_account][financial_connections][permissions]` en `["payment_method", "ownership"]` para solicitar acceso a los datos de propiedad de la cuenta Financial Connections después de que el usuario vincule su cuenta bancaria mediante Financial Connections. Veamos un ejemplo de los requisitos mínimos para crear un SetupIntent para recopilar datos de la cuenta bancaria: ```curl curl https://api.stripe.com/v1/setup_intents \ -u "<>:" \ -d "customer={{CUSTOMER_ID}}" \ -d "flow_directions[]=outbound" \ -d "payment_method_types[]=us_bank_account" ``` SetupIntent en la respuesta incluye un `client_secret`, que permite iniciar la interfaz de usuario modal en página de Stripe.js que se encarga de la recopilación y verificación de los datos de la cuenta bancaria. Gestiona `client_secret` con cuidado porque proporciona acceso a SetupIntent con solo una clave publicable. No lo registres, no lo insertes en direcciones URL ni lo expongas a nadie excepto a tus cuentas conectadas. #### Web ## Recopila los datos del método de pago (Client-side) Agrega el script de Stripe.js al encabezado del archivo HTML para incluirlo en la página de recopilación de la cuenta bancaria. ```html Payout ``` Crea una instancia de Stripe.js con el siguiente JavaScript en tu página de recopilación de cuentas bancarias. ```javascript // Set your publishable key. Remember to change this to your live publishable key in production! // See your keys here: https://dashboard.stripe.com/apikeys var stripe = Stripe('<>', { apiVersion: "{{DATE_VERSION}}" }); ``` Pasa el `client_secret` del `SetupIntent` y el nombre completo de tu usuario de cuenta conectada a `stripe.collectBankAccountForSetup` para recopilar datos sobre el método de pago. ```javascript // Assume you have a form to collect payout accounts var form = document.getElementById('payout-form'); form.addEventListener('submit', (event) => { event.preventDefault(); // clientSecret is the SetupIntent's client_secret property stripe.collectBankAccountForSetup({ clientSecret, params: { payment_method_type: 'us_bank_account', payment_method_data: { billing_details: { // name is required name: 'Jenny Rosen', email: 'jenny@example.com' }, }, }, // Optional, helpful for client-side logic expand: ['payment_method'] }).then(({setupIntent, error}) => { if (error) { // Inform your connected account user that there was an error. console.log(error.message); } else { if (setupIntent.status === "requires_confirmation") { // Your connected account user provided bank account details // When you pass `expand: ['payment_method']` to `collectBankAccountForSetup`, // `setupIntent.payment_method` has data about the Payment Method, including // the Financial Connections Account ID, if your connected account user used // Financial Connections to provide their bank account details. const usedFinancialConnections = typeof setupIntent.payment_method.financial_connections_account === 'string'; console.log(setupIntent.payment_method.id); // => 'pm_1Mb4UkJGNKiWrCEmJ1PS72Cd' return stripe.confirmUsBankAccountSetup(clientSecret).then(({setupIntent, error}) => { if (error) { // Inform your connected account user that there was an error, and check your request logs for errors console.log(error.message); } else { if (setupIntent.status === 'succeeded') { // SetupIntent confirmed, Payment Method attached to the Customer // Your logic to create a payout account could go here } else { // Unable to confirm the SetupIntent, re-fetch the SetupIntent for details } } }); } else { // Your connected account user didn't provide bank account details. You // can re-prompt them using `collectBankAccountForSetup` return null; } } }); }); ``` `collectBankAccountForSetup` devuelve una `Promise`. Cuando la cuenta conectada completa el cuadro de diálogo de Stripe.js, la `Promise` se resuelve con un objeto `result` que incluye una de las siguientes claves: - `setupIntent`, cuando la cuenta conectada sale del cuadro de diálogo - `error` si hay un error irrecuperable al momento de mostrar el cuadro de diálogo Si la `Promise` se resuelve con una clave `setupIntent` y `result.setupIntent.status` es `"requires_confirmation"`, para confirmar el `SetupIntent`, llama a `confirmUsBankAccountSetup` con el `client_secret` del `SetupIntent`. `confirmUsBankAccountSetup` también devuelve una `Promise` que se resuelve con el mismo tipo de objeto `result` que `collectBankAccountForSetup`. Si se confirma correctamente, `result.setupIntent.status` será `"succeeded"`. Esto significa que puedes usar el `payment_method` del `SetupIntent` para crear un token de cuenta bancaria en tu servidor. Cuando llamas a `stripe.collectBankAccountForSetup`, Stripe.js carga el [flujo de autenticación](https://docs.stripe.com/financial-connections/fundamentals.md#authentication-flow), un cuadro de diálogo en la página que brinda a las cuentas conectadas información acerca de los datos que compartirán. También les permite buscar y seleccionar su institución financiera e iniciar sesión de forma segura en su cuenta para verificar el acceso. De forma predeterminada, tus cuentas conectadas solo pueden agregar una cuenta corriente o de ahorros en el flujo de autenticación porque Stripe solo puede facilitar transferencias a una cuenta habilitada para ACH. También puedes ingresar de forma manual la cuenta y el número de enrutamiento si tu cuenta conectada no puede encontrar la institución o autenticar la cuenta. El flujo de entrada manual podría verse de la siguiente forma: ![Flujo de autenticación con alternativa de entrada manual](https://b.stripecdn.com/docs-statics-srv/assets/manual_fallback.c910f590ec792b6133bb88947332604c.png) Si deseas evitar que los usuarios de la cuenta conectada ingresen los datos de la cuenta bancaria manualmente, especifica `payment_method_options[us_bank_account][verification_method]=instant` cuando crees el `SetupIntent`. ### Crea una cuenta externa que puedas usar para las transferencias (Server-side) Después de confirmar el SetupIntent, usa el Método de pago adjunto para crear un Token de cuenta bancaria y, a continuación, usa el Token para crear una cuenta de pago externa. En primer lugar, crea un token de cuenta bancaria. ```curl curl https://api.stripe.com/v1/tokens \ -u "<>:" \ -H "Stripe-Account: {{CONNECTEDACCOUNT_ID}}" \ -d "bank_account[payment_method]={{PAYMENTMETHOD_ID}}" \ -d "customer={{CUSTOMER_ID}}" ``` A continuación, usa el ID del token para crear una cuenta de transferencia externa. ```curl curl https://api.stripe.com/v1/accounts/{{ACCOUNT_ID}} \ -u "<>:" \ -H "Stripe-Account: {{CONNECTEDACCOUNT_ID}}" \ -d "external_account={{TOKEN_ID}}" ``` De forma predeterminada, proporcionar una cuenta externa la establece como la nueva cuenta externa predeterminada para su moneda y elimina la cuenta predeterminada anterior, si existiera. Ya puedes enviar transferencias a tu cuenta conectada. Para obtener más información sobre cómo crear y administrar una cuenta externa para transferencias, consulta [Crea una cuenta bancaria externa](https://docs.stripe.com/api/external_account_bank_accounts/create.md). ### Recuperar datos en una cuenta de Financial Connections (Server-side) Puedes determinar si tu usuario vinculó una cuenta de conexiones financieras recuperando el SetupIntent con la propiedad `payment_method` expandida. ```curl curl -G https://api.stripe.com/v1/setup_intents/{{SETUP_INTENT_ID}} \ -u "<>:" \ -d "expand[]=payment_method" ``` Esto devolverá una respuesta API similar a la siguiente: ```javascript { "id": "{{SETUP_INTENT_ID}}", "object": "setup_intent", // ... "payment_method": { "id": "{{PAYMENT_METHOD_ID}}", "object": "payment_method", // ... "type": "us_bank_account", "us_bank_account": { // ... // the value of "financial_connections_account" may be null "financial_connections_account": "{{FINANCIAL_CONNECTIONS_ACCOUNT_ID}}", // ... } }, // ... } ``` Si el objeto `payment_method` `us_bank_account` del SetupIntent incluye una propiedad `financial_connections_account`, el usuario vinculó una cuenta de conexiones financieras. Puedes usar el valor `financial_connections_account` para acceder o actualizar los datos que especificaste en el parámetro `payment_method_options[us_bank_account][financial_connections][permissions]` del SetupIntent. Para proteger la privacidad de los datos de tus usuarios, los datos de cuenta accesibles para ti se limitan a los datos que especificaste en este parámetro. Sigue las guías sobre datos de [saldos](https://docs.stripe.com/financial-connections/balances.md), [propiedad](https://docs.stripe.com/financial-connections/ownership.md) y [transacciones](https://docs.stripe.com/financial-connections/transactions.md) para empezar a recuperar datos de la cuenta. ### (Opcional) Usar el método de pago para procesar pagos No podrás usar un PaymentMethod recopilado mediante la integración anterior para procesar pagos con PaymentIntents, porque el SetupIntent solo solicita el permiso `"outbound"` y no has obtenido la autorización de tu usuario al mostrar una [orden](https://docs.stripe.com/payments/ach-direct-debit/set-up-payment.md#web-collect-mandate-and-submit). Si quieres permitir que tu usuario use la misma cuenta para realizar pagos y recibir cobros, 1. elimina el parámetro `flow_directions` de la llamada a la API Create Setup Intent. 1. Recopila una [orden](https://docs.stripe.com/payments/ach-direct-debit/set-up-payment.md#web-collect-mandate-and-submit) de tu usuario. Consulta la [guía de ACH Direct Debit](https://docs.stripe.com/payments/ach-direct-debit/set-up-payment.md) para obtener más información. Este patrón de integración activa la verificación de microdepósitos si el usuario proporciona los datos de su cuenta bancaria mediante el formulario de entrada manual. #### iOS ## Incluye una dependencia adicional para Financial Connections(Client-side) El [SDK para iOS de Stripe](https://github.com/stripe/stripe-ios) es de código abierto, está [plenamente documentado](https://stripe.dev/stripe-ios/index.html) y es compatible con aplicaciones que admiten iOS 13 o posterior. #### Swift Package Manager Para instalar el SDK, sigue estos pasos: 1. En Xcode, selecciona **Archivo** > **Agregar dependencias de paquetes…** e introduce `https://github.com/stripe/stripe-ios-spm` como URL del repositorio. 1. Selecciona el número de versión más reciente en nuestra [página de versiones](https://github.com/stripe/stripe-ios/releases). 1. Agrega el producto **StripeFinancialConnections** al [objetivo de tu aplicación](https://developer.apple.com/documentation/swift_packages/adding_package_dependencies_to_your_app). #### CocoaPods 1. Si aún no lo has hecho, instala la última versión de [CocoaPods](https://guides.cocoapods.org/using/getting-started.html). 1. Si no tienes un [Podfile](https://guides.cocoapods.org/syntax/podfile.html), crea uno al ejecutar el siguiente comando: ```bash pod init ``` 1. Agrega esta línea a tu `Podfile`: ```podfile pod 'StripeFinancialConnections' ``` 1. Ejecuta el siguiente comando: ```bash pod install ``` 1. De ahora en adelante, no olvides usar el archivo `.xcworkspace` en lugar del archivo `.xcodeproj` para abrir tu proyecto en Xcode. 1. En el futuro, para actualizar a la última versión del SDK, ejecuta lo siguiente: ```bash pod update StripeFinancialConnections ``` #### Carthage 1. Si aún no lo has hecho, instala la última versión de [Carthage](https://github.com/Carthage/Carthage#installing-carthage). 1. Agrega esta línea a tu `Cartfile`: ```cartfile github "stripe/stripe-ios" ``` 1. Sigue las [instrucciones de instalación de Carthage](https://github.com/Carthage/Carthage#if-youre-building-for-ios-tvos-or-watchos). Asegúrate de incrustar todos los frameworks obligatorios enumerados [aquí](https://github.com/stripe/stripe-ios/tree/master/StripeFinancialConnections/README.md#manual-linking). 1. En el futuro, para actualizar a la última versión del SDK, ejecuta el siguiente comando: ```bash carthage update stripe-ios --platform ios ``` #### Framework manual 1. Ve a nuestra [página de versiones de GitHub](https://github.com/stripe/stripe-ios/releases/latest) y descarga y descomprime **Stripe.xcframework.zip**. 1. Arrastra **StripeFinancialConnections.xcframework** a la sección **Binarios incrustados** de la configuración **General** de tu proyecto en Xcode. Asegúrate de seleccionar **Copiar elementos si es necesario**. 1. Repite el paso 2 para todos los frameworks obligatorios enumerados [aquí](https://github.com/stripe/stripe-ios/tree/master/StripeFinancialConnections/README.md#manual-linking). 1. En el futuro, para actualizar a la última versión de nuestro SDK, repite los pasos 1 a 3. > Para obtener más detalles sobre la última versión del SDK y las versiones anteriores, consulta la página [Versiones](https://github.com/stripe/stripe-ios/releases) en GitHub. Para recibir notificaciones cuando se publique una nueva versión, [mira las versiones](https://help.github.com/en/articles/watching-and-unwatching-releases-for-a-repository#watching-releases-for-a-repository) del repositorio. ## Configurar una URL de retorno (Client-side) El cliente puede salir de tu aplicación para autenticarse (por ejemplo, en Safari o en su aplicación bancaria). Para permitirles que regresen automáticamente a tu aplicación después de autenticarse, [configura un esquema de URL personalizado](https://developer.apple.com/documentation/xcode/defining-a-custom-url-scheme-for-your-app) y define el delegado de la aplicación para que envíe la URL al SDK. Stripe no admite [enlaces universales](https://developer.apple.com/documentation/xcode/allowing-apps-and-websites-to-link-to-your-content). #### SceneDelegate #### Swift ```swift // This method handles opening custom URL schemes (for example, "your-app://stripe-redirect") func scene(_ scene: UIScene, openURLContexts URLContexts: Set) { guard let url = URLContexts.first?.url else { return } let stripeHandled = StripeAPI.handleURLCallback(with: url) if (!stripeHandled) { // This was not a Stripe url – handle the URL normally as you would } } ``` #### AppDelegate #### Swift ```swift // This method handles opening custom URL schemes (for example, "your-app://stripe-redirect") func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey: Any] = [:]) -> Bool { let stripeHandled = StripeAPI.handleURLCallback(with: url) if (stripeHandled) { return true } else { // This was not a Stripe url – handle the URL normally as you would } return false } ``` #### SwiftUI #### Swift ```swift @main struct MyApp: App { var body: some Scene { WindowGroup { Text("Hello, world!").onOpenURL { incomingURL in let stripeHandled = StripeAPI.handleURLCallback(with: incomingURL) if (!stripeHandled) { // This was not a Stripe url – handle the URL normally as you would } } } } } ``` ## Recopila los datos del método de pago (Client-side) Usa la función de clase `collectUSBankAccountParams` en `STPCollectBankAccountParams` a fin de crear los parámetros necesarios para llamar a `collectBankAccountForSetup`. Debes proporcionar el nombre completo del usuario de la cuenta conectada para recopilar información sobre un `PaymentMethod` de ACH Direct Debit. Crea una instancia de `BankAccountCollector` para llamar a `collectBankAccountForSetup` y recopilar los datos de la cuenta bancaria, crear un `PaymentMethod` y adjuntar ese `PaymentMethod` al `SetupIntent`. Pasa el `client_secret` del `SetupIntent`, tu URL de retorno y los parámetros `STPCollectBankAccountParams` a `collectBankAccountForSetup`. #### Swift ```swift // Build params let collectParams = STPCollectBankAccountParams.collectUSBankAccountParams(with: name, email: email) // Calling this method displays a dialog for collecting bank account information let bankAccountCollector = STPBankAccountCollector() bankAccountCollector.collectBankAccountForSetup(clientSecret: clientSecret, returnURL: "your-app://stripe-redirect", params: collectParams, from: self) { intent, error in guard let intent = intent else { // handle error return } if case .requiresPaymentMethod = intent.status { // Customer canceled the Financial Connections dialog. Present them with other // payment method type options. } else if case .requiresConfirmation = intent.status { // We collected an account - possibly instantly verified, but possibly // manually-entered. let setupIntentParams = STPSetupIntentConfirmParams(clientSecret: clientSecret, paymentMethodType: .USBankAccount) // Confirm the SetupIntent STPPaymentHandler.shared().confirmSetupIntent( setupIntentParams, with: self ) { (status, intent, error) in switch status { case .failed: // Setup failed case .canceled: // Setup was canceled case .succeeded: // Setup succeeded, Payment Method attached to the Customer // Your logic to create a payout account could go here @unknown default: fatalError() } } } } ``` Esto carga el [flujo de autenticación](https://docs.stripe.com/financial-connections/fundamentals.md#authentication-flow), un cuadro de diálogo que brinda a las cuentas conectadas información acerca de los datos que compartirán. También les permite buscar y seleccionar su institución financiera e iniciar sesión de forma segura en su cuenta para verificar el acceso. `collectBankAccountForSetupWithClientSecret` se completa con `SetupIntent` o con un error. Cuando se completa con un `SetupIntent` y su estado es `requires_confirmation`, para confirmar el `SetupIntent`, llama a `confirmSetupIntent` en la instancia compartida `STPPaymentHandler`. `confirmSetupIntent` se completa con los mismos parámetros que `collectBankAccountForSetupWithClientSecret`. Si se confirma correctamente, el estado del `SetupIntent` será `succeeded`. Esto significa que puedes usar el `payment_method` del `SetupIntent` para crear un token de cuenta bancaria en tu servidor. De forma predeterminada, tus cuentas conectadas solo pueden agregar una cuenta corriente o de ahorros en el flujo de autenticación porque Stripe solo puede facilitar transferencias a una cuenta habilitada para ACH. También puedes ingresar de forma manual la cuenta y el número de enrutamiento si tu cuenta conectada no puede encontrar la institución o autenticar la cuenta. El flujo de entrada manual podría verse de la siguiente forma: ![Flujo de autenticación con alternativa de entrada manual](https://b.stripecdn.com/docs-statics-srv/assets/manual_fallback.c910f590ec792b6133bb88947332604c.png) Si deseas evitar que los usuarios de la cuenta conectada ingresen los datos de la cuenta bancaria manualmente, especifica `payment_method_options[us_bank_account][verification_method]=instant` cuando crees el `SetupIntent`. ### Crea una cuenta externa que puedas usar para las transferencias (Server-side) Después de confirmar el SetupIntent, usa el Método de pago adjunto para crear un Token de cuenta bancaria y, a continuación, usa el Token para crear una cuenta de pago externa. En primer lugar, crea un token de cuenta bancaria. ```curl curl https://api.stripe.com/v1/tokens \ -u "<>:" \ -H "Stripe-Account: {{CONNECTEDACCOUNT_ID}}" \ -d "bank_account[payment_method]={{PAYMENTMETHOD_ID}}" \ -d "customer={{CUSTOMER_ID}}" ``` A continuación, usa el ID del token para crear una cuenta de transferencia externa. ```curl curl https://api.stripe.com/v1/accounts/{{ACCOUNT_ID}} \ -u "<>:" \ -H "Stripe-Account: {{CONNECTEDACCOUNT_ID}}" \ -d "external_account={{TOKEN_ID}}" ``` De forma predeterminada, proporcionar una cuenta externa la establece como la nueva cuenta externa predeterminada para su moneda y elimina la cuenta predeterminada anterior, si existiera. Ya puedes enviar transferencias a tu cuenta conectada. Para obtener más información sobre cómo crear y administrar una cuenta externa para transferencias, consulta [Crea una cuenta bancaria externa](https://docs.stripe.com/api/external_account_bank_accounts/create.md). ### Recuperar datos en una cuenta de Financial Connections (Server-side) Puedes determinar si tu usuario vinculó una cuenta de conexiones financieras recuperando el SetupIntent con la propiedad `payment_method` expandida. ```curl curl -G https://api.stripe.com/v1/setup_intents/{{SETUP_INTENT_ID}} \ -u "<>:" \ -d "expand[]=payment_method" ``` Esto devolverá una respuesta API similar a la siguiente: ```javascript { "id": "{{SETUP_INTENT_ID}}", "object": "setup_intent", // ... "payment_method": { "id": "{{PAYMENT_METHOD_ID}}", "object": "payment_method", // ... "type": "us_bank_account", "us_bank_account": { // ... // the value of "financial_connections_account" may be null "financial_connections_account": "{{FINANCIAL_CONNECTIONS_ACCOUNT_ID}}", // ... } }, // ... } ``` Si el objeto `payment_method` `us_bank_account` del SetupIntent incluye una propiedad `financial_connections_account`, el usuario vinculó una cuenta de conexiones financieras. Puedes usar el valor `financial_connections_account` para acceder o actualizar los datos que especificaste en el parámetro `payment_method_options[us_bank_account][financial_connections][permissions]` del SetupIntent. Para proteger la privacidad de los datos de tus usuarios, los datos de cuenta accesibles para ti se limitan a los datos que especificaste en este parámetro. Sigue las guías sobre datos de [saldos](https://docs.stripe.com/financial-connections/balances.md), [propiedad](https://docs.stripe.com/financial-connections/ownership.md) y [transacciones](https://docs.stripe.com/financial-connections/transactions.md) para empezar a recuperar datos de la cuenta. ### (Opcional) Usar el método de pago para procesar pagos No podrás usar un PaymentMethod recopilado mediante la integración anterior para procesar pagos con PaymentIntents, porque el SetupIntent solo solicita el permiso `"outbound"` y no has obtenido la autorización de tu usuario al mostrar una [orden](https://docs.stripe.com/payments/ach-direct-debit/set-up-payment.md#web-collect-mandate-and-submit). Si quieres permitir que tu usuario use la misma cuenta para realizar pagos y recibir cobros, 1. elimina el parámetro `flow_directions` de la llamada a la API Create Setup Intent. 1. Recopila una [orden](https://docs.stripe.com/payments/ach-direct-debit/set-up-payment.md#web-collect-mandate-and-submit) de tu usuario. Consulta la [guía de ACH Direct Debit](https://docs.stripe.com/payments/ach-direct-debit/set-up-payment.md) para obtener más información. Este patrón de integración activa la verificación de microdepósitos si el usuario proporciona los datos de su cuenta bancaria mediante el formulario de entrada manual. #### Android ## Incluye una dependencia adicional para Financial Connections(Client-side) El [SDK para Android de Stripe](https://github.com/stripe/stripe-android) es de código abierto y está [completamente documentado](https://stripe.dev/stripe-android/). Para instalar el SDK, agrega `financial-connections` al bloque `dependencies` de tu archivo [app/build.gradle](https://developer.android.com/studio/build/dependencies): #### Kotlin ```kotlin plugins { id("com.android.application") } android { ... } dependencies { // ... // Financial Connections Android SDK implementation("com.stripe:financial-connections:23.8.0") } ``` > Para conocer detalles de la última versión y de versiones anteriores del SDK, consulta la página [Versiones](https://github.com/stripe/stripe-android/releases) en GitHub. Para recibir una notificación cuando se publique una nueva versión, [mira las versiones del repositorio](https://docs.github.com/en/github/managing-subscriptions-and-notifications-on-github/configuring-notifications#configuring-your-watch-settings-for-an-individual-repository). ## Recopila los datos del método de pago (Client-side) Usa `CollectBankAccountConfiguration.USBankAccount` para crear los parámetros necesarios a fin de llamar a `presentWithSetupIntent`. Debes proporcionar el nombre completo del usuario de la cuenta conectada para recopilar información sobre un `PaymentMethod` de ACH Direct Debit. Inicia una instancia de CollectBankAccountLauncher dentro de `onCreate` de tu actividad de cobro y especifica un método para administrar el resultado. Luego, llama a `presentWithSetupIntent` para recopilar los datos de la cuenta bancaria, crear un `PaymentMethod` y adjuntar ese `PaymentMethod` al `SetupIntent`. #### Kotlin ```kotlin import androidx.appcompat.app.AppCompatActivity class PayoutActivity : AppCompatActivity() { private lateinit var setupIntentClientSecret: String private lateinit var collectBankAccountLauncher: CollectBankAccountLauncher private val paymentLauncher: PaymentLauncher = PaymentLauncher.Companion.create( this, "YOUR_PUBLISHABLE_KEY", null, ::onPaymentResult ) override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) // Create collector collectBankAccountLauncher = CollectBankAccountLauncher.create( this ) { result: CollectBankAccountResult -> when (result) { is CollectBankAccountResult.Completed -> { val intent = result.response.intent if (intent.status == StripeIntent.Status.RequiresPaymentMethod) { // Customer canceled the Financial Connections dialog. Present them with other // payment method type options. } else if (intent.status == StripeIntent.Status.RequiresConfirmation) { // We collected an account - possibly instantly verified, but possibly // manually-entered. // Confirm the SetupIntent val confirmParams = ConfirmSetupIntentParams.create( clientSecret = setupIntentClientSecret, paymentMethodType = PaymentMethod.Type.USBankAccount ) paymentLauncher.confirm(confirmParams) } } is CollectBankAccountResult.Cancelled -> { // handle cancellation } is CollectBankAccountResult.Failed -> { // handle error print("Error: ${result.error}") } } } } fun collectPayoutAccount() { // ... // Build params val collectParams: CollectBankAccountConfiguration = CollectBankAccountConfiguration.USBankAccount( name, email ) // Calling this method triggers the Financial Connections dialog to be displayed collectBankAccountLauncher.presentWithSetupIntent( publishableKey, setupIntentClientSecret, collectParams ) } private fun onPaymentResult(paymentResult: PaymentResult) { when (paymentResult) { is PaymentResult.Completed -> { // Setup succeeded, Payment Method attached to the Customer // Your logic to create a payout account could go here } is PaymentResult.Canceled -> { // handle cancel flow } is PaymentResult.Failed -> { // handle failures } } } } ``` Esto carga el [flujo de autenticación](https://docs.stripe.com/financial-connections/fundamentals.md#authentication-flow), un cuadro de diálogo que brinda a las cuentas conectadas información acerca de los datos que compartirán. También les permite buscar y seleccionar su institución financiera e iniciar sesión de forma segura en su cuenta para verificar el acceso. `CollectBankAccountLauncher` se completa con un objeto de resultado que contiene el `SetupIntent` o un error. Cuando se completa con un `SetupIntent` y su estado es `"requires_confirmation"`, para confirmar el `SetupIntent`, usa el método `confirm` en una instancia de `PaymentLauncher`. Cuando se completa, `confirms` llama a un método configurable con un objeto [PaymentResult](https://stripe.dev/stripe-android/payments-core/com.stripe.android.payments.paymentlauncher/-payment-result/index.html?query=sealed%20class%20PaymentResult%20:%20Parcelable). Si la confirmación se realiza correctamente, el objeto `PaymentResult` es un `PaymentResult.Completed`. Esto significa que puedes usar el `pago_method` del `SetupIntent` para crear un token de cuenta bancaria en tu servidor. De forma predeterminada, tus cuentas conectadas solo pueden agregar una cuenta corriente o de ahorros en el flujo de autenticación porque Stripe solo puede facilitar transferencias a una cuenta habilitada para ACH. También puedes ingresar de forma manual la cuenta y el número de enrutamiento si tu cuenta conectada no puede encontrar la institución o autenticar la cuenta. El flujo de entrada manual podría verse de la siguiente forma: ![Flujo de autenticación con alternativa de entrada manual](https://b.stripecdn.com/docs-statics-srv/assets/manual_fallback.c910f590ec792b6133bb88947332604c.png) Si deseas evitar que los usuarios de la cuenta conectada ingresen los datos de la cuenta bancaria manualmente, especifica `payment_method_options[us_bank_account][verification_method]=instant` cuando crees el `SetupIntent`. ### Crea una cuenta externa que puedas usar para las transferencias (Server-side) Después de confirmar el SetupIntent, usa el Método de pago adjunto para crear un Token de cuenta bancaria y, a continuación, usa el Token para crear una cuenta de pago externa. En primer lugar, crea un token de cuenta bancaria. ```curl curl https://api.stripe.com/v1/tokens \ -u "<>:" \ -H "Stripe-Account: {{CONNECTEDACCOUNT_ID}}" \ -d "bank_account[payment_method]={{PAYMENTMETHOD_ID}}" \ -d "customer={{CUSTOMER_ID}}" ``` A continuación, usa el ID del token para crear una cuenta de transferencia externa. ```curl curl https://api.stripe.com/v1/accounts/{{ACCOUNT_ID}} \ -u "<>:" \ -H "Stripe-Account: {{CONNECTEDACCOUNT_ID}}" \ -d "external_account={{TOKEN_ID}}" ``` De forma predeterminada, proporcionar una cuenta externa la establece como la nueva cuenta externa predeterminada para su moneda y elimina la cuenta predeterminada anterior, si existiera. Ya puedes enviar transferencias a tu cuenta conectada. Para obtener más información sobre cómo crear y administrar una cuenta externa para transferencias, consulta [Crea una cuenta bancaria externa](https://docs.stripe.com/api/external_account_bank_accounts/create.md). ### Recuperar datos en una cuenta de Financial Connections (Server-side) Puedes determinar si tu usuario vinculó una cuenta de conexiones financieras recuperando el SetupIntent con la propiedad `payment_method` expandida. ```curl curl -G https://api.stripe.com/v1/setup_intents/{{SETUP_INTENT_ID}} \ -u "<>:" \ -d "expand[]=payment_method" ``` Esto devolverá una respuesta API similar a la siguiente: ```javascript { "id": "{{SETUP_INTENT_ID}}", "object": "setup_intent", // ... "payment_method": { "id": "{{PAYMENT_METHOD_ID}}", "object": "payment_method", // ... "type": "us_bank_account", "us_bank_account": { // ... // the value of "financial_connections_account" may be null "financial_connections_account": "{{FINANCIAL_CONNECTIONS_ACCOUNT_ID}}", // ... } }, // ... } ``` Si el objeto `payment_method` `us_bank_account` del SetupIntent incluye una propiedad `financial_connections_account`, el usuario vinculó una cuenta de conexiones financieras. Puedes usar el valor `financial_connections_account` para acceder o actualizar los datos que especificaste en el parámetro `payment_method_options[us_bank_account][financial_connections][permissions]` del SetupIntent. Para proteger la privacidad de los datos de tus usuarios, los datos de cuenta accesibles para ti se limitan a los datos que especificaste en este parámetro. Sigue las guías sobre datos de [saldos](https://docs.stripe.com/financial-connections/balances.md), [propiedad](https://docs.stripe.com/financial-connections/ownership.md) y [transacciones](https://docs.stripe.com/financial-connections/transactions.md) para empezar a recuperar datos de la cuenta. ### (Opcional) Usar el método de pago para procesar pagos No podrás usar un PaymentMethod recopilado mediante la integración anterior para procesar pagos con PaymentIntents, porque el SetupIntent solo solicita el permiso `"outbound"` y no has obtenido la autorización de tu usuario al mostrar una [orden](https://docs.stripe.com/payments/ach-direct-debit/set-up-payment.md#web-collect-mandate-and-submit). Si quieres permitir que tu usuario use la misma cuenta para realizar pagos y recibir cobros, 1. elimina el parámetro `flow_directions` de la llamada a la API Create Setup Intent. 1. Recopila una [orden](https://docs.stripe.com/payments/ach-direct-debit/set-up-payment.md#web-collect-mandate-and-submit) de tu usuario. Consulta la [guía de ACH Direct Debit](https://docs.stripe.com/payments/ach-direct-debit/set-up-payment.md) para obtener más información. Este patrón de integración activa la verificación de microdepósitos si el usuario proporciona los datos de su cuenta bancaria mediante el formulario de entrada manual. #### React Native ## Recopila los datos del método de pago (Client-side) Pasa el `client_secret` del `SetupIntent` y el nombre completo del usuario de la cuenta conectada a `collectBankAccountForSetup` para recopilar información sobre el método de pago. ```javascript import {collectBankAccountForSetup, confirmSetup} from '@stripe/stripe-react-native'; export default function PayoutAccountCollectionButton() { // Get SetupIntent client secret, connected account user's full name, and email address. // in this example, from a custom hook. const {clientSecret, name, email} = useMyCustomState(); const handleCollectBankAccountPress = async (clientSecret) => { const {setupIntent, error} = await collectBankAccountForSetup( clientSecret, { paymentMethodType: 'USBankAccount', paymentMethodData: { billingDetails: { name, email } } }, ); if (error) { // Inform your connected account user that there was an error. } else if (setupIntent) { if (setupIntent.status === SetupIntents.Status.RequiresConfirmation) { // Your connected account user provided bank account details // Confirm the SetupIntent const {error: confirmError, setupIntent: confirmedSetupIntent} = await confirmSetup(clientSecret, { type: 'USBankAccount' }); if (confirmError) { // Unable to confirm the SetupIntent, inform your connected account user there was an error } else if (confirmedSetupIntent) { if (confirmedSetupIntent.status === SetupIntents.Status.Succeeded) { // Setup succeeded, Payment Method attached to the Customer // Your logic to create a payout account could go here } else { // Unable to confirm the SetupIntent, re-fetch the SetupIntent for details } } } else { // Connected account user didn't link an account or provide details manually } } }; return (