# Crea cargos a un destino Crea cargos en la cuenta de tu plataforma, cobra comisiones y transfiere de inmediato los fondos restantes a tus cuentas conectadas. ## Empieza aquí: instala las habilidades de agente Stripe aconseja usar las habilidades oficiales para la integración en la API con las prácticas recomendadas. Sigue las instrucciones que se incluyen a continuación para aprender cómo. **Consejo: Usa cURL, en lugar de herramientas de Fetch.** Las habilidades se detallan en archivos de marcado de 10 a 20 KB. Las herramientas de Fetch las resumen. `curl -sL` garantiza el contenido completo. **Uso de `npx skills`**: comprueba si `npx` está instalado en el sistema. Si `npx` está disponible, ejecuta `npx skills add https://docs.stripe.com --list` para enumerar las habilidades disponibles y, a continuación, ejecuta `npx skills add https://docs.stripe.com --yes --skill <--skill other-skills>` para instalar habilidades individuales. **En el caso de que `npx skills` no esté disponible**: puedes usar cURL para obtener el índice de las habilidades disponibles, lo que hacen y sus archivos de `https://docs.stripe.com/.well-known/skills/index.json`. Para obtener una habilidad y sus archivos relacionados, usa cURL y descárgalos de `https://docs.stripe.com/.well-known/skills/`. Para este artículo, recomendamos usar estas habilidades: `stripe-best-practices` Crea *cargos a un destino* cuando los clientes hacen la transacción con tu plataforma por productos o servicios suministrados por tus cuentas conectadas y transfieres fondos inmediatamente a tus cuentas conectadas. Con este tipo de cargo: - Creas un cargo en la cuenta de tu plataforma. - Determinas si el total o una parte de los fondos se transfiere a la cuenta conectada. - Se debita del saldo de tu cuenta el costo de las comisiones, los reembolsos y los contracargos de Stripe. Este tipo de cargo funciona mejor para plataformas como Airbnb, un marketplace de alquiler de alojamientos o Lyft, una aplicación de traslados compartidos. Con [ciertas excepciones](https://docs.stripe.com/connect/account-capabilities.md#transfers-cross-border), si tu plataforma y una cuenta conectada no están en la misma región, debes especificar la cuenta conectada como [comerciante a cargo del cobro](https://docs.stripe.com/connect/destination-charges.md#settlement-merchant) usando el parámetro `on_behalf_of` en [Payment Intent](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-on_behalf_of)  o `payment_intent_data.on_behalf_of` en la [sesión de confirmación de compra](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-payment_intent_data-on_behalf_of). Recomendamos usar cargos a un destino para las cuentas conectadas que no tienen acceso al Dashboard completo de Stripe. ![](https://b.stripecdn.com/docs-statics-srv/assets/ios-overview.9e0d68d009dc005f73a6f5df69e00458.png) Integra la interfaz de usuario de pago prediseñada de Stripe a la confirmación de compra de tu aplicación iOS con la clase [PaymentSheet](https://stripe.dev/stripe-ios/stripe-paymentsheet/Classes/PaymentSheet.html). Consulta nuestro ejemplo de integración [en GitHub](https://github.com/stripe/stripe-ios/tree/master/Example/PaymentSheet%20Example). > #### Soporte de la API Accounts v2 > > Payment Sheet no ofrece soporte para *cuentas configuradas por el cliente*. Solo admite objetos `Customer`. ## Configura Stripe [Lado del servidor] [Lado del cliente] Primero, necesitas una cuenta de Stripe. [Inscríbete ahora](https://dashboard.stripe.com/register). ### Lado del servidor Esta integración necesita puntos de conexión en tu servidor que se comuniquen con la API de Stripe. Usa nuestras bibliotecas oficiales para acceder a la API de Stripe desde tu servidor: #### Ruby ```bash # Available as a gem sudo gem install stripe ``` ```ruby # If you use bundler, you can add this line to your Gemfile gem 'stripe' ``` ### Lado del cliente 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 **StripePaymentSheet** 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 'StripePaymentSheet' ``` 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 StripePaymentSheet ``` #### 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/StripePaymentSheet/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 **StripePaymentSheet.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/StripePaymentSheet/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. Configura el SDK con tu [clave publicable](https://dashboard.stripe.com/test/apikeys) de Stripe al iniciar la aplicación. Esto permite que tu aplicación haga solicitudes a la API de Stripe. #### Swift ```swift import UIKitimportStripePaymentSheet @main class AppDelegate: UIResponder, UIApplicationDelegate { func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {StripeAPI.defaultPublishableKey = "<>" // do any other necessary launch configuration return true } } ``` > Usa las [claves de prueba](https://docs.stripe.com/keys.md#obtain-api-keys) durante las pruebas y el desarrollo, y tus claves para [modo activo](https://docs.stripe.com/keys.md#test-live-modes) cuando publiques tu aplicación. ## Agregar un punto de conexión [Lado del servidor] > #### Nota > > Para mostrar la PaymentSheet antes de crear un PaymentIntent, consulta [Recopila datos de pago antes de crear un Intent](https://docs.stripe.com/payments/accept-a-payment-deferred.md?type=payment). Esta integración usa tres objetos de la API de Stripe: 1. [PaymentIntent](https://docs.stripe.com/api/payment_intents.md): Stripe lo utiliza para representar tu intención de cobrarle a un cliente, haciendo el seguimiento de los intentos de cobro y de los cambios en el estado del pago a lo largo del proceso. 1. (Opcional) Una [Account configurada por el cliente](https://docs.stripe.com/api/v2/core/accounts/object.md#v2_account_object-applied_configurations) o un [Customer](https://docs.stripe.com/api/customers.md) Object: para configurar un método de pago para pagos futuros, debes asociarlo a un cliente. Crea un objeto que represente a tu cliente cuando cree una cuenta en tu negocio. Si tu cliente realiza un pago como invitado, puedes crear una `Account` o `Customer` Object antes del pago y asociarlo más adelante con tu propia representación interna de la cuenta del cliente. 1. (Opcional) [CustomerSession](https://docs.stripe.com/api/customer_sessions.md): la información del objeto que representa a tu cliente es sensible y no se puede recuperar directamente desde una app. Una `CustomerSession` le otorga al SDK acceso temporal con alcance limitado a la `Account` o `Customer` y proporciona opciones de configuración adicionales. Consulta la lista completa de [opciones de configuración](https://docs.stripe.com/api/customer_sessions/create.md#create_customer_session-components). > Si nunca guardas tarjetas de tus clientes ni permites que vuelvan a usar tarjetas guardadas, puedes omitir el `Account` o `Customer` Object y el objeto `CustomerSession` en tu integración. Por motivos de seguridad, tu aplicación no puede crear estos objetos. En su lugar, agrega un punto de conexión en tu servidor que haga lo siguiente: 1. Recupera el objeto `Account` o `Customer`, o crea uno nuevo. 1. Crea una [CustomerSession](https://docs.stripe.com/api/customer_sessions.md) para el objeto `Account` o `Customer`. 1. Crea un `PaymentIntent` con el [importe](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-amount), la [moneda](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-currency), y el [customer_account](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-customer_account) o el [customer](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-customer). 1. Devuelve el *client secret* (The client secret is a unique key returned from Stripe as part of a PaymentIntent. This key lets the client access important fields from the PaymentIntent (status, amount, currency) while hiding sensitive ones (metadata, customer)) del `PaymentIntent`, el `client_secret` de la `CustomerSession`, el ID del `Account` o `Customer` y tu [clave publicable](https://dashboard.stripe.com/apikeys) a tu app. Los métodos de pago que se muestran a los clientes durante el proceso de compra también se incluyen en el PaymentIntent. Puedes permitir que Stripe extraiga los métodos de pago de tu configuración del Dashboard o puedes enumerarlos manualmente. Independientemente de la opción que elijas, debes saber que la moneda especificada en el PaymentIntent filtra los métodos de pago que se muestran al cliente. Por ejemplo, si especificas `eur` en el PaymentIntent y tienes habilitado OXXO en el Dashboard, OXXO no se mostrará al cliente porque OXXO no admite pagos en `eur`. A menos que tu integración requiera una opción basada en código para ofrecer métodos de pago, Stripe recomienda usar la opción automatizada. Esto se debe a que Stripe evalúa la moneda, las restricciones de los métodos de pago y otros parámetros para determinar la lista de métodos de pago admitidos. Se les da prioridad a los métodos de pago que aumentan la conversión y guardan mayor relación con la moneda y la ubicación del cliente. #### Gestionar los métodos de pago desde el Dashboard Puedes administrar los métodos de pago desde el [Dashboard](https://dashboard.stripe.com/settings/payment_methods). Stripe maneja la devolución de métodos de pago elegibles según factores como el monto de la transacción, la moneda y el flujo de pago. El PaymentIntent se crea según los métodos de pago que configuraste en el Dashboard. Si no quieres usar el Dashboard o si quieres especificar métodos de pago manualmente, puedes enumerarlos usando el atributo `payment_method_types`. #### curl ```bash # Create a Customer (use an existing Customer ID if this is a returning customer) curl https://api.stripe.com/v1/customers \ -u <>: \ -X "POST" \ -H "Stripe-Account: {{CONNECTED_ACCOUNT_ID}}" # Create an CustomerSession for the Customer curl https://api.stripe.com/v1/customer_sessions \ -u <>: \ -X "POST" \ -d "customer"="{{CUSTOMER_ID}}" \ -d "components[mobile_payment_element][enabled]"=true \ -d "components[mobile_payment_element][features][payment_method_save]"=enabled \ -d "components[mobile_payment_element][features][payment_method_redisplay]"=enabled \ -d "components[mobile_payment_element][features][payment_method_remove]"=enabled # Create a PaymentIntent curl https://api.stripe.com/v1/payment_intents \ -u <>: \ -X "POST" \ -d "customer"="{{CUSTOMER_ID}}" \ -d "amount"=1099 \ -d "currency"="eur" \ -d "automatic_payment_methods[enabled]"=true \ -d application_fee_amount="123" \ -d "transfer_data[destination]"="{{CONNECTED_ACCOUNT_ID}}" \ ``` #### Cómo enumerar métodos de pago manualmente #### curl ```bash # Create a Customer (use an existing Customer ID if this is a returning customer) curl https://api.stripe.com/v1/customers \ -u <>: \ -X "POST" \ -H "Stripe-Account: {{CONNECTED_ACCOUNT_ID}}" # Create an CustomerSession for the Customer curl https://api.stripe.com/v1/customer_sessions \ -u <>: \ -X "POST" \ -d "customer"="{{CUSTOMER_ID}}" \ -d "components[mobile_payment_element][enabled]"=true \ -d "components[mobile_payment_element][features][payment_method_save]"=enabled \ -d "components[mobile_payment_element][features][payment_method_redisplay]"=enabled \ -d "components[mobile_payment_element][features][payment_method_remove]"=enabled # Create a PaymentIntent curl https://api.stripe.com/v1/payment_intents \ -u <>: \ -X "POST" \ -d "customer"="{{CUSTOMER_ID}}" \ -d "amount"=1099 \ -d "currency"="eur" \ -d "payment_method_types[]"="bancontact" \ -d "payment_method_types[]"="card" \ -d "payment_method_types[]"="ideal" \ -d "payment_method_types[]"="klarna" \ -d "payment_method_types[]"="sepa_debit" \ -d application_fee_amount="123" \ -d "transfer_data[destination]"="{{CONNECTED_ACCOUNT_ID}}" \ ``` > Cada método de pago debe admitir la moneda especificada en el PaymentIntent, y tu empresa tiene que estar establecida en uno de los países que admite cada método de pago. Consulta la página de [opciones de integración de métodos de pago](https://docs.stripe.com/payments/payment-methods/integration-options.md) para obtener más información sobre qué admitimos. ## Integrar la hoja de pago [Lado del cliente] Para mostrar el Payment Element móvil en la pantalla de confirmación de compra: - Muestra los productos que compra el cliente junto con el importe total - Usa el [Address Element](https://docs.stripe.com/elements/address-element.md?platform=ios) para recopilar la información de envío necesaria del cliente - Agrega un botón de confirmación de compra para mostrar la interfaz de usuario (IU) de Stripe #### UIKit #### Accounts v2 En la pantalla de confirmación de compra de tu aplicación, obtén el secreto de cliente PaymentIntent, el secreto de cliente `CustomerSession`, el ID de la `cuenta`configurada por el cliente y la clave publicable del punto de conexión que creaste en el paso anterior. Usa `STPAPIClient.shared` para establecer tu clave publicable e iniciar la [PaymentSheet](https://stripe.dev/stripe-ios/stripe-paymentsheet/Classes/PaymentSheet.html). #### iOS (Swift) ```swift import UIKit@_spi(CustomerSessionBetaAccess) import StripePaymentSheet class CheckoutViewController: UIViewController { @IBOutlet weak var checkoutButton: UIButton! var paymentSheet: PaymentSheet? let backendCheckoutUrl = URL(string: "Your back-end endpoint/payment-sheet")! // Your back-end endpoint override func viewDidLoad() { super.viewDidLoad() checkoutButton.addTarget(self, action: #selector(didTapCheckoutButton), for: .touchUpInside) checkoutButton.isEnabled = false // MARK: Fetch the PaymentIntent client secret, CustomerSession client secret, customer-configured Account ID, and publishable key var request = URLRequest(url: backendCheckoutUrl) request.httpMethod = "POST" let task = URLSession.shared.dataTask(with: request, completionHandler: { [weak self] (data, response, error) in guard let data = data, let json = try? JSONSerialization.jsonObject(with: data, options: []) as? [String : Any], let customerAccountId = json["customerAccount"] as? String, let customerSessionClientSecret = json["customerSessionClientSecret"] as? String, let paymentIntentClientSecret = json["paymentIntent"] as? String, let publishableKey = json["publishableKey"] as? String, let self = self else { // Handle error return } STPAPIClient.shared.publishableKey = publishableKey// MARK: Create a PaymentSheet instance var configuration = PaymentSheet.Configuration() configuration.merchantDisplayName = "Example, Inc." configuration.customerAccount = .init(id: customerAccountId, customerSessionClientSecret: customerSessionClientSecret) // Set `allowsDelayedPaymentMethods` to true if your business handles // delayed notification payment methods like US bank accounts. configuration.allowsDelayedPaymentMethods = true self.paymentSheet = PaymentSheet(paymentIntentClientSecret:paymentIntentClientSecret, configuration: configuration) DispatchQueue.main.async { self.checkoutButton.isEnabled = true } }) task.resume() } } ``` #### Customers v1 En la pantalla de confirmación de compra de tu aplicación, obtén el secreto de cliente PaymentIntent, el secreto de cliente `CustomerSession`, el ID del `cliente` y la clave publicable del punto de conexión que creaste en el paso anterior. Usa `STPAPIClient.shared` para establecer tu clave publicable e iniciar la [PaymentSheet](https://stripe.dev/stripe-ios/stripe-paymentsheet/Classes/PaymentSheet.html). #### iOS (Swift) ```swift import UIKit@_spi(CustomerSessionBetaAccess) import StripePaymentSheet class CheckoutViewController: UIViewController { @IBOutlet weak var checkoutButton: UIButton! var paymentSheet: PaymentSheet? let backendCheckoutUrl = URL(string: "Your backend endpoint/payment-sheet")! // Your backend endpoint override func viewDidLoad() { super.viewDidLoad() checkoutButton.addTarget(self, action: #selector(didTapCheckoutButton), for: .touchUpInside) checkoutButton.isEnabled = false // MARK: Fetch the PaymentIntent client secret, CustomerSession client secret, Customer ID, and publishable key var request = URLRequest(url: backendCheckoutUrl) request.httpMethod = "POST" let task = URLSession.shared.dataTask(with: request, completionHandler: { [weak self] (data, response, error) in guard let data = data, let json = try? JSONSerialization.jsonObject(with: data, options: []) as? [String : Any], let customerId = json["customer"] as? String, let customerSessionClientSecret = json["customerSessionClientSecret"] as? String, let paymentIntentClientSecret = json["paymentIntent"] as? String, let publishableKey = json["publishableKey"] as? String, let self = self else { // Handle error return } STPAPIClient.shared.publishableKey = publishableKey// MARK: Create a PaymentSheet instance var configuration = PaymentSheet.Configuration() configuration.merchantDisplayName = "Example, Inc." configuration.customer = .init(id: customerId, customerSessionClientSecret: customerSessionClientSecret) // Set `allowsDelayedPaymentMethods` to true if your business handles // delayed notification payment methods like US bank accounts. configuration.allowsDelayedPaymentMethods = true self.paymentSheet = PaymentSheet(paymentIntentClientSecret:paymentIntentClientSecret, configuration: configuration) DispatchQueue.main.async { self.checkoutButton.isEnabled = true } }) task.resume() } } ``` Cuando el cliente toca el botón **Checkout**, llama a `present` para presentar la PaymentSheet. Después de que el cliente complete el pago, Stripe descarta la PaymentSheet y llama al bloque de finalización con [PaymentSheetResult](https://stripe.dev/stripe-ios/stripe-paymentsheet/Enums/PaymentSheetResult.html). #### iOS (Swift) ```swift @objc func didTapCheckoutButton() { // MARK: Start the checkout process paymentSheet?.present(from: self) { paymentResult in // MARK: Handle the payment result switch paymentResult { case .completed: print("Your order is confirmed") case .canceled: print("Canceled!") case .failed(let error): print("Payment failed: \(error)") } } } ``` #### SwiftUI #### Accounts v2 Crea un modelo `ObservableObject` para tu pantalla de confirmación de compra. Este modelo publica una [PaymentSheet](https://stripe.dev/stripe-ios/stripe-paymentsheet/Classes/PaymentSheet.html) y un [PaymentSheetResult](https://stripe.dev/stripe-ios/stripe-paymentsheet/Enums/PaymentSheetResult.html). ```swift import StripePaymentSheet import SwiftUI class CheckoutViewModel: ObservableObject { let backendCheckoutUrl = URL(string: "Your back-end endpoint/payment-sheet")! // Your back-end endpoint @Published var paymentSheet: PaymentSheet? @Published var paymentResult: PaymentSheetResult? } ``` Obtén el secreto de cliente PaymentIntent, el secreto de cliente `CustomerSession`, el ID de la `cuenta` configurada por el cliente y la clave publicable del punto de conexión que creaste en el paso anterior. Usa `STPAPIClient.shared` para establecer tu clave publicable e iniciar la [PaymentSheet](https://stripe.dev/stripe-ios/stripe-paymentsheet/Classes/PaymentSheet.html). ```swift @_spi(CustomerSessionBetaAccess) import StripePaymentSheet import SwiftUI class CheckoutViewModel: ObservableObject { let backendCheckoutUrl = URL(string: "Your back-end endpoint/payment-sheet")! // Your back-end endpoint @Published var paymentSheet: PaymentSheet? @Published var paymentResult: PaymentSheetResult? func preparePaymentSheet() { // MARK: Fetch thePaymentIntent and customer information from the back end var request = URLRequest(url: backendCheckoutUrl) request.httpMethod = "POST" let task = URLSession.shared.dataTask(with: request, completionHandler: { [weak self] (data, response, error) in guard let data = data, let json = try? JSONSerialization.jsonObject(with: data, options: []) as? [String : Any], let customerAccountId = json["customerAccount"] as? String, let customerSessionClientSecret = json["customerSessionClientSecret"] as? String, letpaymentIntentClientSecret = json["paymentIntent"] as? String, let publishableKey = json["publishableKey"] as? String, let self = self else { // Handle error return } STPAPIClient.shared.publishableKey = publishableKey// MARK: Create a PaymentSheet instance var configuration = PaymentSheet.Configuration() configuration.merchantDisplayName = "Example, Inc." configuration.customerAccount = .init(id: customerAccountId, customerSessionClientSecret: customerSessionClientSecret) // Set `allowsDelayedPaymentMethods` to true if your business handles // delayed notification payment methods like US bank accounts. configuration.allowsDelayedPaymentMethods = true DispatchQueue.main.async { self.paymentSheet = PaymentSheet(paymentIntentClientSecret:paymentIntentClientSecret, configuration: configuration) } }) task.resume() } } struct CheckoutView: View { @ObservedObject var model = CheckoutViewModel() var body: some View { VStack { if model.paymentSheet != nil { Text("Ready to pay.") } else { Text("Loading…") } }.onAppear { model.preparePaymentSheet() } } } ``` Agrega un [PaymentSheet.PaymentButton](https://stripe.dev/stripe-ios/stripe-paymentsheet/Classes/PaymentSheet/PaymentButton.html) a tu `View`. Esto se comporta de manera similar a un `Button` de SwiftUI, que te permite personalizarlo agregando una `View`. Cuando tocas el botón, se muestra la PaymentSheet. Después de completar el pago, Stripe cierra la PaymentSheet y llama al controlador `onCompletion` con un objeto [PaymentSheetResult](https://stripe.dev/stripe-ios/stripe-paymentsheet/Enums/PaymentSheetResult.html). ```swift @_spi(CustomerSessionBetaAccess) import StripePaymentSheet import SwiftUI class CheckoutViewModel: ObservableObject { let backendCheckoutUrl = URL(string: "Your back-end endpoint/payment-sheet")! // Your back-end endpoint @Published var paymentSheet: PaymentSheet? @Published var paymentResult: PaymentSheetResult? func preparePaymentSheet() { // MARK: Fetch the PaymentIntent and customer information from the back end var request = URLRequest(url: backendCheckoutUrl) request.httpMethod = "POST" let task = URLSession.shared.dataTask(with: request, completionHandler: { [weak self] (data, response, error) in guard let data = data, let json = try? JSONSerialization.jsonObject(with: data, options: []) as? [String : Any], let customerAccountId = json["customerAccount"] as? String, let customerSessionClientSecret = json["customerSessionClientSecret"] as? String, let paymentIntentClientSecret = json["paymentIntent"] as? String, let publishableKey = json["publishableKey"] as? String, let self = self else { // Handle error return } STPAPIClient.shared.publishableKey = publishableKey // MARK: Create a PaymentSheet instance var configuration = PaymentSheet.Configuration() configuration.merchantDisplayName = "Example, Inc." configuration.customerAccount = .init(id: customerAccountId, customerSessionClientSecret: customerSessionClientSecret) // Set `allowsDelayedPaymentMethods` to true if your business can handle payment methods // that complete payment after a delay, like SEPA Debit and Sofort. configuration.allowsDelayedPaymentMethods = true DispatchQueue.main.async { self.paymentSheet = PaymentSheet(paymentIntentClientSecret: paymentIntentClientSecret, configuration: configuration) } }) task.resume() } func onPaymentCompletion(result: PaymentSheetResult) { self.paymentResult = result } } struct CheckoutView: View { @ObservedObject var model = CheckoutViewModel() var body: some View { VStack {if let paymentSheet = model.paymentSheet { PaymentSheet.PaymentButton( paymentSheet: paymentSheet, onCompletion: model.onPaymentCompletion ) { Text("Buy") } } else { Text("Loading…") }if let result = model.paymentResult { switch result { case .completed: Text("Payment complete") case .failed(let error): Text("Payment failed: \(error.localizedDescription)") case .canceled: Text("Payment canceled.") } } }.onAppear { model.preparePaymentSheet() } } } ``` #### Customers v1 Crea un modelo `ObservableObject` para tu pantalla de confirmación de compra. Este modelo publica una [PaymentSheet](https://stripe.dev/stripe-ios/stripe-paymentsheet/Classes/PaymentSheet.html) y un [PaymentSheetResult](https://stripe.dev/stripe-ios/stripe-paymentsheet/Enums/PaymentSheetResult.html). ```swift import StripePaymentSheet import SwiftUI class CheckoutViewModel: ObservableObject { let backendCheckoutUrl = URL(string: "Your back-end endpoint/payment-sheet")! // Your back-end endpoint @Published var paymentSheet: PaymentSheet? @Published var paymentResult: PaymentSheetResult? } ``` Obtén el secreto de cliente PaymentIntent, el secreto de cliente CustomerSession, el ID del `cliente` y la clave publicable del punto de conexión que creaste en el paso anterior. Usa `STPAPIClient.shared` para establecer tu clave publicable e iniciar la [PaymentSheet](https://stripe.dev/stripe-ios/stripe-paymentsheet/Classes/PaymentSheet.html). ```swift @_spi(CustomerSessionBetaAccess) import StripePaymentSheet import SwiftUI class CheckoutViewModel: ObservableObject { let backendCheckoutUrl = URL(string: "Your back-end endpoint/payment-sheet")! // Your back-end endpoint @Published var paymentSheet: PaymentSheet? @Published var paymentResult: PaymentSheetResult? func preparePaymentSheet() { // MARK: Fetch thePaymentIntent and Customer information from the back end var request = URLRequest(url: backendCheckoutUrl) request.httpMethod = "POST" let task = URLSession.shared.dataTask(with: request, completionHandler: { [weak self] (data, response, error) in guard let data = data, let json = try? JSONSerialization.jsonObject(with: data, options: []) as? [String : Any], let customerId = json["customer"] as? String, let customerSessionClientSecret = json["customerSessionClientSecret"] as? String, letpaymentIntentClientSecret = json["paymentIntent"] as? String, let publishableKey = json["publishableKey"] as? String, let self = self else { // Handle error return } STPAPIClient.shared.publishableKey = publishableKey// MARK: Create a PaymentSheet instance var configuration = PaymentSheet.Configuration() configuration.merchantDisplayName = "Example, Inc." configuration.customer = .init(id: customerId, customerSessionClientSecret: customerSessionClientSecret) // Set `allowsDelayedPaymentMethods` to true if your business handles // delayed notification payment methods like US bank accounts. configuration.allowsDelayedPaymentMethods = true DispatchQueue.main.async { self.paymentSheet = PaymentSheet(paymentIntentClientSecret:paymentIntentClientSecret, configuration: configuration) } }) task.resume() } } struct CheckoutView: View { @ObservedObject var model = CheckoutViewModel() var body: some View { VStack { if model.paymentSheet != nil { Text("Ready to pay.") } else { Text("Loading…") } }.onAppear { model.preparePaymentSheet() } } } ``` Agrega un [PaymentSheet.PaymentButton](https://stripe.dev/stripe-ios/stripe-paymentsheet/Classes/PaymentSheet/PaymentButton.html) a tu `View`. Esto se comporta de manera similar a un `Button` de SwiftUI, que te permite personalizarlo agregando una `View`. Cuando tocas el botón, se muestra la PaymentSheet. Después de completar el pago, Stripe cierra la PaymentSheet y llama al controlador `onCompletion` con un objeto [PaymentSheetResult](https://stripe.dev/stripe-ios/stripe-paymentsheet/Enums/PaymentSheetResult.html). ```swift @_spi(CustomerSessionBetaAccess) import StripePaymentSheet import SwiftUI class CheckoutViewModel: ObservableObject { let backendCheckoutUrl = URL(string: "Your back-end endpoint/payment-sheet")! // Your back-end endpoint @Published var paymentSheet: PaymentSheet? @Published var paymentResult: PaymentSheetResult? func preparePaymentSheet() { // MARK: Fetch the PaymentIntent and Customer information from the back end var request = URLRequest(url: backendCheckoutUrl) request.httpMethod = "POST" let task = URLSession.shared.dataTask(with: request, completionHandler: { [weak self] (data, response, error) in guard let data = data, let json = try? JSONSerialization.jsonObject(with: data, options: []) as? [String : Any], let customerId = json["customer"] as? String, let customerSessionClientSecret = json["customerSessionClientSecret"] as? String, let paymentIntentClientSecret = json["paymentIntent"] as? String, let publishableKey = json["publishableKey"] as? String, let self = self else { // Handle error return } STPAPIClient.shared.publishableKey = publishableKey // MARK: Create a PaymentSheet instance var configuration = PaymentSheet.Configuration() configuration.merchantDisplayName = "Example, Inc." configuration.customer = .init(id: customerId, customerSessionClientSecret: customerSessionClientSecret) // Set `allowsDelayedPaymentMethods` to true if your business can handle payment methods // that complete payment after a delay, like SEPA Debit and Sofort. configuration.allowsDelayedPaymentMethods = true DispatchQueue.main.async { self.paymentSheet = PaymentSheet(paymentIntentClientSecret: paymentIntentClientSecret, configuration: configuration) } }) task.resume() } func onPaymentCompletion(result: PaymentSheetResult) { self.paymentResult = result } } struct CheckoutView: View { @ObservedObject var model = CheckoutViewModel() var body: some View { VStack {if let paymentSheet = model.paymentSheet { PaymentSheet.PaymentButton( paymentSheet: paymentSheet, onCompletion: model.onPaymentCompletion ) { Text("Buy") } } else { Text("Loading…") }if let result = model.paymentResult { switch result { case .completed: Text("Payment complete") case .failed(let error): Text("Payment failed: \(error.localizedDescription)") case .canceled: Text("Payment canceled.") } } }.onAppear { model.preparePaymentSheet() } } } ``` Si el `PaymentSheetResult` es `.completed`, infórmale al cliente (por ejemplo, mostrándole una pantalla de confirmación del pedido). Establecer `allowsDelayedPaymentMethods` en true permite aceptar métodos de pago de [notificación diferida](https://docs.stripe.com/payments/payment-methods.md#payment-notification) como cuentas bancarias en EE. UU. Para estos métodos de pago, el estado final del pago no se conoce cuando se completa el `PaymentSheet`, sino que se efectúa con éxito o falla más tarde. Si aceptas este tipo de métodos de pago, infórmale al cliente que su pedido está confirmado y solo finalízalo (por ejemplo, envía el producto) cuando el pago se realice correctamente. ## Configurar una URL de retorno [Lado del cliente] 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 } } } } } ``` ## Administrar eventos posteriores al pago [Lado del servidor] Stripe envía un evento [payment_intent.succeeded](https://docs.stripe.com/api/events/types.md#event_types-payment_intent.succeeded) cuando se completa el pago. Usa la [herramienta de webhook del Dashboard](https://dashboard.stripe.com/webhooks) o sigue la [guía de webhooks](https://docs.stripe.com/webhooks/quickstart.md) para recibir estos eventos y ejecutar acciones como, por ejemplo, enviar un correo electrónico de confirmación del pedido a tu cliente, registrar la venta en una base de datos o iniciar un flujo de envío. Escucha estos eventos en lugar de esperar una devolución de llamada del cliente. De su lado, el cliente puede cerrar la ventana del navegador o salir de la aplicación antes de que se ejecute la devolución de llamada, y clientes malintencionados podrían manipular la respuesta. Si configuras tu integración para escuchar eventos asincrónicos, podrás aceptar [diferentes tipos de métodos de pago](https://stripe.com/payments/payment-methods-guide) con una sola integración. Además de administrar el evento `payment_intent.succeeded`, recomendamos administrar estos otros eventos si se cobran pagos con el Payment Element: | Evento | Descripción | Acción | | ------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [payment_intent.succeeded](https://docs.stripe.com/api/events/types.md?lang=php#event_types-payment_intent.succeeded) | Se envía cuando un cliente completa correctamente un pago. | Envía al cliente una confirmación del pedido y *completa* (Fulfillment is the process of providing the goods or services purchased by a customer, typically after payment is collected) el pedido. | | [payment_intent.processing](https://docs.stripe.com/api/events/types.md?lang=php#event_types-payment_intent.processing) | Se envía cuando un cliente inicia con éxito un pago, pero éste aún no se completó. Este evento se envía normalmente cuando el cliente inicia un débito bancario. Le sigue un evento `payment_intent.succeeded` o `payment_intent.payment_failed` en el futuro. | Envía al cliente una confirmación del pedido que indique que el pago está pendiente. En caso de productos digitales, quizá te convenga completar el pedido antes de esperar que se complete el pago. | | [payment_intent.payment_failed](https://docs.stripe.com/api/events/types.md?lang=php#event_types-payment_intent.payment_failed) | Enviado cuando un cliente intenta un pago, pero el pago falla. | Si un pago pasa de `processing` a `payment_failed`, ofrécele al cliente otro intento de pago. | ## Probar la integración #### Tarjetas | Número de tarjeta | Escenario | Cómo hacer la prueba | | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | | 4242424242424242 | El pago con tarjeta se efectúa correctamente y no requiere autenticación. | Completa el formulario de tarjeta de crédito con el número de tarjeta de crédito y la fecha de vencimiento, el CVC o el código postal. | | 4000002500003155 | El pago con tarjeta requiere *autenticación* (Strong Customer Authentication (SCA) is a regulatory requirement in effect as of September 14, 2019, that impacts many European online payments. It requires customers to use two-factor authentication like 3D Secure to verify their purchase). | Completa el formulario de tarjeta de crédito con el número de tarjeta de crédito y la fecha de vencimiento, el CVC o el código postal. | | 4000000000009995 | La tarjeta es rechazada con un código de rechazo `insufficient_funds`. | Completa el formulario de tarjeta de crédito con el número de tarjeta de crédito y la fecha de vencimiento, el CVC o el código postal. | | 6205500000000000004 | La tarjeta UnionPay puede tener entre 13 y 19 dígitos. | Completa el formulario de tarjeta de crédito con el número de tarjeta de crédito y la fecha de vencimiento, el CVC o el código postal. | #### Redireccionamientos bancarios | Método de pago | Escenario | Cómo hacer la prueba | | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Bancontact, iDEAL | Tu cliente no pasa la autenticación en la página de redireccionamiento de un método de pago basado en redireccionamiento y con notificación inmediata. | Elige cualquier método de pago basado en redireccionamiento, completa los datos solicitados y confirma el pago. Luego, haz click en **Error en el pago de prueba** en la página de redireccionamiento. | | Pay by Bank | Tu cliente paga satisfactoriamente con un método de pago basado en redireccionamiento y con [notificación diferida](https://docs.stripe.com/payments/payment-methods.md#payment-notification). | Elige el método de pago, completa los datos solicitados y confirma el pago. Luego, haz click en **Completar el pago de prueba** en la página de redireccionamiento. | | Pay by Bank | Tu cliente no pasa la autenticación en la página de redireccionamiento de un método de pago basado en redireccionamiento y con notificación diferida. | Elige el método de pago, completa los datos solicitados y confirma el pago. Luego, haz click en **Error en el pago de prueba** en la página de redireccionamiento. | | BLIK | Los pagos BLIK generan errores de varias maneras: errores inmediatos (por ejemplo, el código venció o no es válido), errores demorados (el banco lo rechaza) o tiempos de espera (el cliente no respondió a tiempo). | Usa patrones de correo electrónico para [simular los diferentes errores.](https://docs.stripe.com/payments/blik/accept-a-payment.md#simulate-failures) | #### Débitos bancarios | Método de pago | Escenario | Cómo hacer la prueba | | ------------------- | --------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Débito directo SEPA | Tu cliente paga satisfactoriamente con débito directo SEPA. | Completa el formulario con el número de cuenta `AT321904300235473204`. El PaymentIntent confirmado pasa inicialmente al estado “en proceso” y, tres minutos más tarde, a “completado”. | | Débito directo SEPA | El estado del intento de pago de tu cliente pasa de `processing` a `requires_payment_method`. | Completa el formulario con el número de cuenta `AT861904300235473202`. | Consulta [Pruebas](https://docs.stripe.com/testing.md) para obtener información adicional para probar tu integración. ## Habilitar escaneo de tarjeta A fin de habilitar el soporte para escaneo de tarjetas para iOS, establece `NSCameraUsageDescription` (**Privacidad: descripción del uso de la cámara**) en el `Info.plist` de tu aplicación y especifica el motivo por el que se necesita acceder a la cámara (por ejemplo, «Para escanear tarjetas»). ## Optional: Habilitar Apple Pay > Si tu pantalla de confirmación de compra tiene un **botón de Apple Pay** exclusivo, sigue la [Guía de Apple Pay](https://docs.stripe.com/apple-pay.md#present-payment-sheet) y utiliza `ApplePayContext` para cobrar el pago desde ese botón. Puedes usar `PaymentSheet` para gestionar otros tipos de métodos de pago. ### Inscribirse para obtener un ID de comerciante Apple Obtén un ID de comerciante Apple [solicitando un nuevo identificador](https://developer.apple.com/account/resources/identifiers/add/merchant) en el sitio web de desarrolladores de Apple. Completa el formulario con una descripción y el identificador. La descripción es para tus registros y se puede modificar en el futuro. Stripe recomienda usar el nombre de tu aplicación como identificador (por ejemplo, `merchant.com.{{YOUR_APP_NAME}}`). ### Crear un nuevo certificado de Apple Pay Crea un certificado para que tu aplicación cifre los datos de pago. Ve a [Configuración de certificados de iOS](https://dashboard.stripe.com/settings/ios_certificates) en el Dashboard, haz clic en **Agregar nueva aplicación** y sigue la guía. Descarga un archivo de solicitud de firma de certificado (CSR) para obtener un certificado seguro de Apple que te permita utilizar Apple Pay. Se debe usar un archivo CSR para emitir exactamente un certificado. Si cambias tu ID de comerciante de Apple, debes ir a la [Configuración de certificados de iOS](https://dashboard.stripe.com/settings/ios_certificates) en el Dashboard para obtener una nueva CSR y un nuevo certificado. ### Integrarse con Xcode Agrega la funcionalidad Apple Pay a tu aplicación. En Xcode, abre la configuración del proyecto, selecciona la pestaña **Firma y funcionalidades** y agrega la funcionalidad **Apple Pay**. En este paso, quizá se te solicite iniciar sesión en tu cuenta de desarrollador. Selecciona el ID de comerciante que creaste antes, y tu aplicación estará lista para aceptar Apple Pay. ![](https://b.stripecdn.com/docs-statics-srv/assets/xcode.a701d4c1922d19985e9c614a6f105bf1.png) Habilitar la funcionalidad Apple Pay en Xcode ### Agregar Apple Pay #### Pago único Para agregar Apple Pay a PaymentSheet, establece [applePay](https://stripe.dev/stripe-ios/stripe-paymentsheet/Classes/PaymentSheet/Configuration.html#/s:6Stripe12PaymentSheetC13ConfigurationV8applePayAC05ApplefD0VSgvp) después de inicializar `PaymentSheet.Configuration` con tu ID de comerciante Apple y el [código de país de tu empresa](https://dashboard.stripe.com/settings/account). #### iOS (Swift) ```swift var configuration = PaymentSheet.Configuration() configuration.applePay = .init( merchantId: "merchant.com.your_app_name", merchantCountryCode: "US" ) ``` #### Pagos recurrentes Para agregar Apple Pay a PaymentSheet, establece [applePay](https://stripe.dev/stripe-ios/stripe-paymentsheet/Classes/PaymentSheet/Configuration.html#/s:6Stripe12PaymentSheetC13ConfigurationV8applePayAC05ApplefD0VSgvp) después de inicializar `PaymentSheet.Configuration` con tu ID de comerciante Apple y el [código de país de tu empresa](https://dashboard.stripe.com/settings/account). Conforme a las [directrices de Apple](https://developer.apple.com/design/human-interface-guidelines/apple-pay#Supporting-subscriptions) para pagos recurrentes, también debes establecer otros atributos en `PKPaymentRequest`. Agrega un controlador en [ApplePayConfiguration.paymentRequestHandlers](https://stripe.dev/stripe-ios/stripepaymentsheet/documentation/stripepaymentsheet/paymentsheet/applepayconfiguration/handlers/paymentrequesthandler) para configurar [PKPaymentRequest.paymentSummaryItems](https://developer.apple.com/documentation/passkit/pkpaymentrequest/1619231-paymentsummaryitems) con la cantidad que pretendes cobrar (por ejemplo, USD 9.95 al mes). También puedes adoptar [tokens de comerciante](https://developer.apple.com/apple-pay/merchant-tokens/) estableciendo las propiedades `recurringPaymentRequest` o `automaticReloadPaymentRequest` en la `PKPaymentRequest`. Para obtener más información sobre cómo usar los pagos recurrentes con Apple Pay, consulta la [Documentación de Apple sobre PassKit](https://developer.apple.com/documentation/passkit/pkpaymentrequest). #### iOS (Swift) ```swift let customHandlers = PaymentSheet.ApplePayConfiguration.Handlers( paymentRequestHandler: { request in // PKRecurringPaymentSummaryItem is available on iOS 15 or later if #available(iOS 15.0, *) { let billing = PKRecurringPaymentSummaryItem(label: "My Subscription", amount: NSDecimalNumber(string: "59.99")) // Payment starts today billing.startDate = Date() // Payment ends in one year billing.endDate = Date().addingTimeInterval(60 * 60 * 24 * 365) // Pay once a month. billing.intervalUnit = .month billing.intervalCount = 1 // recurringPaymentRequest is only available on iOS 16 or later if #available(iOS 16.0, *) { request.recurringPaymentRequest = PKRecurringPaymentRequest(paymentDescription: "Recurring", regularBilling: billing, managementURL: URL(string: "https://my-backend.example.com/customer-portal")!) request.recurringPaymentRequest?.billingAgreement = "You'll be billed $59.99 every month for the next 12 months. To cancel at any time, go to Account and click 'Cancel Membership.'" } request.paymentSummaryItems = [billing] request.currencyCode = "USD" } else { // On older iOS versions, set alternative summary items. request.paymentSummaryItems = [PKPaymentSummaryItem(label: "Monthly plan starting July 1, 2022", amount: NSDecimalNumber(string: "59.99"), type: .final)] } return request } ) var configuration = PaymentSheet.Configuration() configuration.applePay = .init(merchantId: "merchant.com.your_app_name", merchantCountryCode: "US", customHandlers: customHandlers) ``` ### Seguimiento de pedidos Para agregar información de [seguimiento de pedidos](https://developer.apple.com/design/human-interface-guidelines/technologies/wallet/designing-order-tracking) en iOS 16 o posterior, configura un [authorizationResultHandler](https://stripe.dev/stripe-ios/stripepaymentsheet/documentation/stripepaymentsheet/paymentsheet/applepayconfiguration/handlers/authorizationresulthandler) en tu `PaymentSheet.ApplePayConfiguration.Handlers`. Stripe llamará a tu implementación después de que se efectivice el pago, pero antes de que iOS descarte la hoja de Apple Pay. En tu implementación de `authorizationResultHandler`, obtén los datos del pedido de tu servidor para el pedido completado. Agrega los datos al [PKPaymentAuthorizationResult](https://developer.apple.com/documentation/passkit/pkpaymentauthorizationresult) proporcionado y devuelve el resultado modificado. Para obtener más información sobre el seguimiento de pedidos, consulta la [Documentación sobre los pedidos por billetera de Apple](https://developer.apple.com/documentation/walletorders). #### iOS (Swift) ```swift let customHandlers = PaymentSheet.ApplePayConfiguration.Handlers( authorizationResultHandler: { result in do { // Fetch the order details from your service let myOrderDetails = try await MyAPIClient.shared.fetchOrderDetails(orderID: orderID) result.orderDetails = PKPaymentOrderDetails( orderTypeIdentifier: myOrderDetails.orderTypeIdentifier, // "com.myapp.order" orderIdentifier: myOrderDetails.orderIdentifier, // "ABC123-AAAA-1111" webServiceURL: myOrderDetails.webServiceURL, // "https://my-backend.example.com/apple-order-tracking-backend" authenticationToken: myOrderDetails.authenticationToken) // "abc123" // Return your modified PKPaymentAuthorizationResult return result } catch { return PKPaymentAuthorizationResult(status: .failure, errors: [error]) } } ) var configuration = PaymentSheet.Configuration() configuration.applePay = .init(merchantId: "merchant.com.your_app_name", merchantCountryCode: "US", customHandlers: customHandlers) ``` ## Optional: Personalizar la hoja Todo lo que se quiera personalizar se configura usando el objeto [PaymentSheet.Configuration](https://stripe.dev/stripe-ios/stripe-paymentsheet/Classes/PaymentSheet/Configuration.html). ### Appearance Personaliza los colores y las fuentes, entre otros elementos, para que combinen con tu aplicación con la [API Appearance](https://docs.stripe.com/elements/appearance-api/mobile.md?platform=ios). ### Diseño del método de pago Configura el diseño de los métodos de pago en la hoja usando [paymentMethodLayout](https://stripe.dev/stripe-ios/stripepaymentsheet/documentation/stripepaymentsheet/paymentsheet/configuration-swift.struct/paymentmethodlayout). Puedes mostrarlos horizontalmente, verticalmente o dejar que Stripe optimice el diseño de manera automática. ![](https://b.stripecdn.com/docs-statics-srv/assets/ios-mpe-payment-method-layouts.9d0513e2fcec5660378ba1824d952054.png) #### Swift ```swift var configuration = PaymentSheet.Configuration() configuration.paymentMethodLayout = .automatic ``` ### Recopilar las direcciones de los usuarios Recopila las direcciones de envío o facturación locales e internacionales de tus clientes usando el [Address Element](https://docs.stripe.com/elements/address-element.md?platform=ios). ### Nombre de pantalla para el comerciante Especifica un nombre de empresa que vea el cliente configurando [merchantDisplayName](https://stripe.dev/stripe-ios/stripe-paymentsheet/Classes/PaymentSheet/Configuration.html#/s:18StripePaymentSheet0bC0C13ConfigurationV19merchantDisplayNameSSvp). De manera predeterminada, este es el nombre de tu aplicación. #### Swift ```swift var configuration = PaymentSheet.Configuration() configuration.merchantDisplayName = "My app, Inc." ``` ### Modo oscuro `PaymentSheet` se adapta automáticamente a la configuración de aspecto de todo el sistema del usuario (modo claro y modo oscuro). Si tu aplicación no admite el modo oscuro, puedes definir el [estilo](https://stripe.dev/stripe-ios/stripe-paymentsheet/Classes/PaymentSheet/Configuration.html#/s:18StripePaymentSheet0bC0C13ConfigurationV5styleAC18UserInterfaceStyleOvp) en modo `alwaysLight` o `alwaysDark`. ```swift var configuration = PaymentSheet.Configuration() configuration.style = .alwaysLight ``` ### Datos de facturación predeterminados Para establecer los valores predeterminados para los datos de facturación recopilados en la hoja de pago, configura la propiedad `defaultBillingDetails`. Los campos de la `PaymentSheet` se rellenan automáticamente con los valores que proporcionas. ```swift var configuration = PaymentSheet.Configuration() configuration.defaultBillingDetails.address.country = "US" configuration.defaultBillingDetails.email = "foo@bar.com" ``` ### Recopilación de los datos de facturación Usa `billingDetailsCollectionConfiguration` para especificar cómo deseas recopilar los datos de facturación en la hoja de pago. Puedes recopilar el nombre, el correo electrónico, el número de teléfono y la dirección del cliente. Si solo quieres los datos de facturación requeridos por el método de pago, establece `billingDetailsCollectionConfiguration.attachDefaultsToPaymentMethod` en true. En ese caso, `PaymentSheet.Configuration.defaultBillingDetails` se establece como los [datos de facturación](https://docs.stripe.com/api/payment_methods/object.md?lang=node#payment_method_object-billing_details) del método de pago. Si quieres recopilar datos de facturación adicionales que no son necesariamente requeridos por el método de pago, establece `billingDetailsCollectionConfiguration.attachDefaultsToPaymentMethod` en false. En ese caso, los datos de facturación recopilados mediante la `PaymentSheet` se establecen como los datos de facturación del método de pago. ```swift var configuration = PaymentSheet.Configuration() configuration.defaultBillingDetails.email = "foo@bar.com" configuration.billingDetailsCollectionConfiguration.name = .always configuration.billingDetailsCollectionConfiguration.email = .never configuration.billingDetailsCollectionConfiguration.address = .full configuration.billingDetailsCollectionConfiguration.attachDefaultsToPaymentMethod = true ``` > Pregúntale a tu asesor legal sobre las leyes que se aplican a la recopilación de información. Solicita los números de teléfono solo si los necesitas para la transacción. ## Optional: Completa el pago en tu interfaz de usuario Puedes presentar la hoja de pago para recopilar solo los datos del método de pago y luego llamar al método `confirm` para completar el pago en la interfaz de usuario de tu aplicación. Esto resulta útil si tienes un botón de compra personalizado o solicitas pasos adicionales después de recopilar los datos del pago. ![](https://b.stripecdn.com/docs-statics-srv/assets/ios-multi-step.cd631ea4f1cd8cf3f39b6b9e1e92b6c5.png) Completa el pago en la interfaz de usuario de tu aplicación #### UIKit Los siguientes pasos te explican cómo completar el pago en la interfaz de usuario de tu aplicación. Consulta nuestro ejemplo de integración en [GitHub](https://github.com/stripe/stripe-ios/blob/master/Example/PaymentSheet%20Example/PaymentSheet%20Example/ExampleCustomCheckoutViewController.swift). 1. Primero, inicializa [PaymentSheet.FlowController](https://stripe.dev/stripe-ios/stripepaymentsheet/documentation/stripepaymentsheet/paymentsheet/flowcontroller) en lugar de `PaymentSheet` y actualiza tu interfaz de usuario con su propiedad `paymentOption`. Esta propiedad contiene una imagen y una etiqueta que representan el método de pago predeterminado que el cliente seleccionó inicialmente. ```swift PaymentSheet.FlowController.create(paymentIntentClientSecret: paymentIntentClientSecret, configuration: configuration) { [weak self] result in switch result { case .failure(let error): print(error) case .success(let paymentSheetFlowController): self?.paymentSheetFlowController = paymentSheetFlowController // Update your UI using paymentSheetFlowController.paymentOption } } ``` 1. A continuación, llama a `presentPaymentOptions` para recopilar los datos del pago. Cuando se complete, actualiza nuevamente tu interfaz de usuario con la propiedad `paymentOption`. ```swift paymentSheetFlowController.presentPaymentOptions(from: self) { // Update your UI using paymentSheetFlowController.paymentOption } ``` 1. Por último, llama a `confirm`. ```swift paymentSheetFlowController.confirm(from: self) { paymentResult in // MARK: Handle the payment result switch paymentResult { case .completed: print("Payment complete!") case .canceled: print("Canceled!") case .failed(let error): print(error) } } ``` #### SwiftUI Los siguientes pasos te explican cómo completar el pago en la interfaz de usuario de tu aplicación. Consulta nuestro ejemplo de integración en [GitHub](https://github.com/stripe/stripe-ios/blob/master/Example/PaymentSheet%20Example/PaymentSheet%20Example/ExampleSwiftUICustomPaymentFlow.swift). 1. Primero, inicializa [PaymentSheet.FlowController](https://stripe.dev/stripe-ios/stripepaymentsheet/documentation/stripepaymentsheet/paymentsheet/flowcontroller) en lugar de `PaymentSheet`. Su propiedad `paymentOption` contiene una imagen y una etiqueta que representan el método de pago que el cliente tiene seleccionado actualmente, que puedes usar en tu interfaz de usuario. ```swift PaymentSheet.FlowController.create(paymentIntentClientSecret: paymentIntentClientSecret, configuration: configuration) { [weak self] result in switch result { case .failure(let error): print(error) case .success(let paymentSheetFlowController): self?.paymentSheetFlowController = paymentSheetFlowController // Use the paymentSheetFlowController.paymentOption properties in your UI myPaymentMethodLabel = paymentSheetFlowController.paymentOption?.label ?? "Select a payment method" myPaymentMethodImage = paymentSheetFlowController.paymentOption?.image ?? UIImage(systemName: "square.and.pencil")! } } ``` 1. Usa [PaymentSheet.FlowController.PaymentOptionsButton](https://stripe.dev/stripe-ios/stripepaymentsheet/documentation/stripepaymentsheet/paymentsheet/flowcontroller/paymentoptionsbutton) para integrar el botón que presenta la hoja para recopilar los datos de pago. Cuando `PaymentSheet.FlowController` llama al argumento `onSheetDismissed`, la `paymentOption` de la instancia `PaymentSheet.FlowController` refleja el método de pago seleccionado actualmente. ```swift PaymentSheet.FlowController.PaymentOptionsButton( paymentSheetFlowController: paymentSheetFlowController, onSheetDismissed: { myPaymentMethodLabel = paymentSheetFlowController.paymentOption?.label ?? "Select a payment method" myPaymentMethodImage = paymentSheetFlowController.paymentOption?.image ?? UIImage(systemName: "square.and.pencil")! }, content: { /* An example button */ HStack { Text(myPaymentMethodLabel) Image(uiImage: myPaymentMethodImage) } } ) ``` 1. Usa [PaymentSheet.FlowController.PaymentOptionsButton](https://stripe.dev/stripe-ios/stripepaymentsheet/documentation/stripepaymentsheet/paymentsheet/flowcontroller/paymentoptionsbutton) para integrar el botón que confirma el pago. ```swift PaymentSheet.FlowController.ConfirmButton( paymentSheetFlowController: paymentSheetFlowController, onCompletion: { result in // MARK: Handle the payment result switch result { case .completed: print("Payment complete!") case .canceled: print("Canceled!") case .failed(let error): print(error) } }, content: { /* An example button */ Text("Pay") } ) ``` Si el `PaymentSheetResult` es `.completed`, infórmale al cliente (por ejemplo, mostrándole una pantalla de confirmación del pedido). Establecer `allowsDelayedPaymentMethods` en true permite aceptar métodos de pago de [notificación diferida](https://docs.stripe.com/payments/payment-methods.md#payment-notification) como cuentas bancarias en EE. UU. Para estos métodos de pago, el estado final del pago no se conoce cuando se completa el `PaymentSheet`, sino que se efectúa con éxito o falla más tarde. Si aceptas este tipo de métodos de pago, infórmale al cliente que su pedido está confirmado y solo finalízalo (por ejemplo, envía el producto) cuando el pago se realice correctamente. ## Optional: Habilitar métodos de pago adicionales #### Destino Configura los métodos de pago para tu cuenta desde la [Págona de métodos de pago](https://dashboard.stripe.com/settings/payment_methods) en el Dashboard de Stripe. Los pagos con tarjeta, Google Pay y Apple Pay se habilitan de forma predeterminada, pero puedes habilitarlos y deshabilitarlos según sea necesario. Tus cuentas conectadas no pueden personalizar sus propios métodos de pago. Antes de que Stripe muestre el formulario de pago a un cliente, Stripe evalúa la moneda, las restricciones de los métodos de pago y otros parámetros para determinar la lista de métodos de pago aceptados. El formulario de pago da prioridad a los métodos de pago que aumentan la conversión y guardan mayor relación con la moneda y la ubicación del cliente. Los métodos de pago menos prioritarios se ocultan en un menú de contenido adicional. #### En nombre y representación de Ve a [Administrar métodos de pago para cuentas conectadas](https://dashboard.stripe.com/settings/payment_methods/connected_accounts) en el Dashboard para configurar qué métodos de pago aceptan tus cuentas conectadas. Los cambios en la configuración predeterminada se aplican a todas las cuentas conectadas nuevas y existentes. Consulta los siguientes recursos para obtener información sobre los métodos de pago: - [Guía de métodos de pago](https://stripe.com/payments/payment-methods-guide#choosing-the-right-payment-methods-for-your-business) para ayudarte a elegir los métodos de pago correctos para tu plataforma. - [Funcionalidades de cuenta](https://docs.stripe.com/connect/account-capabilities.md) para asegurarte de que los métodos de pago que elegiste funcionen en tus cuentas conectadas. - Consulta las tablas de [admisibilidad de métodos de pago y de productos](https://docs.stripe.com/payments/payment-methods/payment-method-support.md#product-support) para asegurarte de que los métodos de pago elegidos funcionen para tus productos y flujos de pago de Stripe. Para cada método de pago, puedes seleccionar una de las siguientes opciones desplegables: | | | | | **Activado de manera predeterminada** | Tus cuentas conectadas aceptan este método de pago durante el proceso de compra. Algunos métodos de pago solo pueden estar desactivados o bloqueados. Esto se debe a que tus cuentas conectadas con *acceso al Dashboard de Stripe* (Platforms can provide connected accounts with access to the full Stripe Dashboard or the Express Dashboard. Otherwise, platforms build an interface for connected accounts using embedded components or the Stripe API) deben activarlas en su página de configuración. | | **Desactivado de manera predeterminada** | Tus cuentas conectadas no aceptan este método de pago durante el proceso de compra. Si permites que tus cuentas conectadas con *acceso al Dashboard de Stripe* (Platforms can provide connected accounts with access to the full Stripe Dashboard or the Express Dashboard. Otherwise, platforms build an interface for connected accounts using embedded components or the Stripe API) administren sus propios métodos de pago, podrán activarlo. | | **Bloqueado** | Tus cuentas conectadas no aceptan este método de pago durante el proceso de compra. Si permites que tus cuentas conectadas con *acceso al Dashboard de Stripe* (Platforms can provide connected accounts with access to the full Stripe Dashboard or the Express Dashboard. Otherwise, platforms build an interface for connected accounts using embedded components or the Stripe API) administren sus propios métodos de pago, no tendrán la opción para activarlo. | ![Opciones desplegables para los métodos de pago, cada una de las cuales muestra una opción disponible (bloqueada, activada de forma predeterminada, desactivada de forma predeterminada)](https://b.stripecdn.com/docs-statics-srv/assets/dropdowns.ef651d721d5939d81521dd34dde4577f.png) Opciones de métodos de pago Si realizas un cambio en un método de pago, debes hacer clic en **Revisar cambios** en la barra inferior de la pantalla y en **Guardar y aplicar** para actualizar tus cuentas conectadas. ![Cuadro de diálogo que se muestra después de hacer clic en el botón Guardar con una lista de lo que el usuario cambió](https://b.stripecdn.com/docs-statics-srv/assets/dialog.a56ea7716f60db9778706790320d13be.png) Cuadro de diálogo Guardar ### Permite que las cuentas conectadas gestionen los métodos de pago Stripe recomienda permitir que tus cuentas conectadas personalicen sus propios métodos de pago. Esta opción le permite a cada cuenta conectada con *acceso al Dashboard de Stripe* (Platforms can provide connected accounts with access to the full Stripe Dashboard or the Express Dashboard. Otherwise, platforms build an interface for connected accounts using embedded components or the Stripe API) ver y actualizar página [Métodos de pago](https://dashboard.stripe.com/settings/payment_methods). Solo los propietarios de las cuentas conectadas pueden personalizar sus métodos de pago. El Dashboard de Stripe muestra el conjunto de métodos de pago predeterminados que aplicaste a todas las cuentas conectadas nuevas y existentes. Tus cuentas conectadas pueden anular estos valores predeterminados, excluyendo los métodos de pago que hayas bloqueado. Marca la casilla de verificación **Personalización de la cuenta** para habilitar esta opción. Debes hacer clic en **Revisar cambios** en la barra inferior de la pantalla y luego seleccionar **Guardar y aplicar** para actualizar esta configuración. ![Captura de pantalla de la casilla de verificación para seleccionar cuando se permite a propietarios conectados personalizar los métodos de pago](https://b.stripecdn.com/docs-statics-srv/assets/checkbox.275bd35d2a025272f03af029a144e577.png) Casilla de verificación de personalización de la cuenta ### Capacidades de métodos de pago Para permitir que tus cuentas conectadas acepten métodos de pago adicionales, sus `cuentas` deben tener funcionalidades de métodos de pago activos. Si seleccionaste la opción “Activado por defecto” para un método de pago en [Gestionar métodos de pago para tus cuentas conectadas](https://dashboard.stripe.com/settings/payment_methods/connected_accounts), Stripe solicita automáticamente la funcionalidad necesaria para las cuentas conectadas nuevas y las existentes si cumplen con los requisitos de verificación. Si la cuenta conectada no cumple con los requisitos o si quieres tener control directo, puedes solicitar de forma manual la funcionalidad en el dashboard o con la API. La mayoría de los métodos de pago tienen los mismos requisitos de verificación que la funcionalidad `card_payments`, con algunas restricciones y excepciones. En el [cuadro](https://docs.stripe.com/connect/account-capabilities.md#payment-methods) figuran las funcionalidades de métodos de pago que requieren verificación adicional. #### Dashboard [Busca una cuenta conectada](https://docs.stripe.com/connect/dashboard/managing-individual-accounts.md#finding-accounts) en el dashboard para editar sus funcionalidades y ver los requisitos de verificación pendientes. #### API Para una cuenta conectada existente, puedes [enumerar](https://docs.stripe.com/api/capabilities/list.md) sus funcionalidades existentes para determinar si necesitas solicitar funcionalidades adicionales. ```curl curl https://api.stripe.com/v1/accounts/{{CONNECTEDACCOUNT_ID}}/capabilities \ -u "<>:" ``` Solicita funcionalidades adicionales [actualizando](https://docs.stripe.com/api/capabilities/update.md) las funcionalidades de cada cuenta conectada. ```curl curl https://api.stripe.com/v1/accounts/{{CONNECTEDACCOUNT_ID}}/capabilities/us_bank_account_ach_payments \ -u "<>:" \ -d requested=true ``` Puede haber un retraso antes de que la capacidad solicitada se active. Si la capacidad tiene algún requisito de activación, la respuesta lo incluye en las matrices de `requirements`. ## Cobra comisiones Cuando se procesa un pago, en lugar de transferir el importe total de la transacción a una cuenta conectada, tu plataforma puede decidir tomar una parte del importe de la transacción en forma de comisiones. Puedes establecer el precio de las comisiones de dos maneras diferentes: - Utiliza la [herramienta de tarifas de la plataforma](https://docs.stripe.com/connect/platform-pricing-tools.md) para establecer y probar las reglas de comisiones de la plataforma. Esta función que no requiere programación del Dashboard de Stripe solo está disponible actualmente para plataformas responsables de pagar las comisiones de Stripe. - Establece tus reglas de tarifas internamente, especificando las comisiones directamente en un [PaymentIntent](https://docs.stripe.com/api/payment_intents/object.md) utilizando el parámetro [application_fee_amount](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-application_fee_amount) o [transfer_data[amount]](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-transfer_data-amount). Las comisiones establecidas con este método anulan la lógica de tarifas especificada en la herramienta de tarifas de la plataforma. #### application_fee_amount Cuando se crean cargos con `application_fee_amount`, el importe total del cargo se transfiere de inmediato de la plataforma a la cuenta `transfer_data[destination]` después de la captura del cargo. El `application_fee_amount` (que no puede superar el importe total del cargo) se transfiere de nuevo a la plataforma. ```curl curl https://api.stripe.com/v1/payment_intents \ -u "<>:" \ -d amount=1000 \ -d currency=usd \ -d "automatic_payment_methods[enabled]=true" \ -d application_fee_amount=123 \ -d "transfer_data[destination]={{CONNECTEDACCOUNT_ID}}" ``` Una vez cobrada la comisión de la plataforma, se crea un objeto [Application Fee](https://docs.stripe.com/api/application_fees/object.md). Puedes ver una lista de las comisiones de la plataforma en el [Dashboard](https://dashboard.stripe.com/connect/application_fees), con las [comisiones de la plataforma](https://docs.stripe.com/api/application_fees/list.md) o en [Sigma](https://docs.stripe.com/data/how-sigma-works.md). También puedes utilizar la propiedad `amount` en el objeto application fee para realizar informes detallados de las comisiones. Si usas un `application_fee_amount`, ten en cuenta que: - El `application_fee_amount` no puede superar el importe total de la transacción. - El `application_fee_amount` siempre se calcula en la misma moneda que la transacción. - La comisión de la plataforma *se liquida* (When funds are available in your Stripe balance) en la moneda de cobro de la cuenta conectada. En el caso de los cargos a un destino transfronterizos, esto podría [diferir de la moneda de cobro de tu plataforma](https://docs.stripe.com/connect/currencies/fx-quotes-api.md#application-fees-for-destination-charges-and-converting-balances). - Tu plataforma paga la comisión de Stripe después de que se transfiere el `application_fee_amount` a tu cuenta. - No se aplican comisiones adicionales de Stripe al importe. - Tu plataforma puede usar la medición, notificación y verificación de comisiones de la plataforma incorporadas para conciliar las [comisiones cobradas](https://dashboard.stripe.com/connect/application_fees). - En los dashboards o componentes alojados en Stripe, como el [componente Datos de pago](https://docs.stripe.com/connect/supported-embedded-components/payment-details.md), tu cuenta conectada puede ver tanto el importe total como el importe de la comisión de la plataforma. ### Flujo de fondos con cargos a un destino Con el código anterior, el importe total del cargo (USD 10.00) se agrega al saldo pendiente de la cuenta conectada. El `application_fee_amount` (USD 1.23) se deduce del importe del cargo y se transfiere a tu plataforma. Las comisiones de Stripe (USD 0.59) se deducen del saldo de la cuenta de tu plataforma. El importe de la comisión de la plataforma menos las comisiones de Stripe (USD 1.23 − USD 0.59 = USD 0.64) permanece en el saldo de la cuenta de tu plataforma. ![Flujo de fondos para cargos a un destino](https://b.stripecdn.com/docs-statics-srv/assets/destination_charge_app_fee.c9ef81298155b38f986df02d0efa9167.png) El `application_fee_amount` estará a disposición de la cuenta de la plataforma conforme a su calendario habitual de transferencias, como si se tratara de fondos de cualquier otro cargo de Stripe. #### transfer_data[amount] El valor `transfer_data[amount]` es un número entero positivo que refleja el importe del cargo que se transfiere a `transfer_data[destination]`. Resta las comisiones de tu plataforma del importe del cargo y luego especifica el resultado del cálculo como `transfer_data[amount]`, ```curl curl https://api.stripe.com/v1/payment_intents \ -u "<>:" \ -d amount=1000 \ -d currency=usd \ -d "automatic_payment_methods[enabled]=true" \ -d "transfer_data[amount]=877" \ -d "transfer_data[destination]={{CONNECTEDACCOUNT_ID}}" ``` Cuando se usa `transfer_data[amount]`, se aplica lo siguiente: - El importe no puede superar el importe total de la transacción. - El importe siempre se calcula en la misma moneda que la transacción. - El importe *se liquida* (When funds are available in your Stripe balance) en [la misma moneda que la moneda de cobro de tu plataforma](https://docs.stripe.com/connect/currencies/fx-quotes-api.md#application-fees-for-destination-charges-and-converting-balances). - En los Dashboards o componentes alojados en Stripe, como el Dashboard de Stripe o el Dashboard de Express, tu cuenta conectada no puede ver el importe total del cargo. Solo ven el importe transferido. - Tu plataforma paga las comisiones de Stripe sobre el cargo por separado. - No se aplican comisiones adicionales de Stripe al importe. - Para [calcular las comisiones](https://docs.stripe.com/data/query-all-fees-data.md#fees-paid-by-connected-accounts) después de que se crea un pago, p. ej., con fines de reporte, [recupera el PaymentIntent](https://docs.stripe.com/api/payment_intents/retrieve.md) y resta el `transfer_data[amount]` del `amount` en el PaymentIntent. Considera la posibilidad de utilizar el [importe de la comisión de la plataforma](https://docs.stripe.com/connect/destination-charges.md#application-fee) para simplificar la elaboración de informes mediante la creación de comisiones de la plataforma explícitas que estén vinculadas al cargo ### Flujo de fondos Con el código de arriba, el `amount` del cargo (10.00 USD) se agrega al saldo de la cuenta de la plataforma. El `transfer_data[amount]` (8.77 USD) se deduce del saldo de la cuenta de la plataforma y se agrega al saldo pendiente de la cuenta conectada. El `amount` del cargo (10.00 USD) menos el `transfer_data[amount]` (8,77 USD) menos las comisiones de Stripe (`amount` del cargo), por un importe neto de 0.64 USD, permanece en el saldo pendiente de la cuenta de la plataforma. ![](https://b.stripecdn.com/docs-statics-srv/assets/destination_charge_amount.46cd59f6496607d68020b546aa1af85f.png) El `transfer_data[amount]` estará a disposición de la cuenta conectada conforme a su calendario habitual de transferencias, como si se tratara de fondos de cualquier otro cargo de Stripe. Las plataformas pueden saber cuánto retienen de los cargos de `transfer_data[amount]` mirando la columna Comisión de plataforma de destino en la exportación del historial de Saldos. ## Especifica el comerciante a cargo del cobro El comerciante a cargo del cobro depende de las [funcionalidades](https://docs.stripe.com/connect/account-capabilities.md) activas en una cuenta y de cómo se crea el cargo. El comerciante a cargo del cobro determina de quién es la información utilizada para efectuar el cargo. Esto incluye la descripción del cargo (ya sea de la plataforma o de la cuenta conectada) que aparecerá para ese cargo en el extracto bancario o de tarjeta de crédito del cliente. Si especificas el comerciante a cargo del cobro, puedes ser más explícito sobre quién es el destinatario del cargo. Por ejemplo, algunas plataformas prefieren ser el comerciante a cargo del cobro porque el usuario final interactúa directamente con ellas, como es el caso de las plataformas on-demand. No obstante, algunas plataformas tienen cuentas conectadas que interactúan directamente con los consumidores finales (por ejemplo, las tiendas físicas de una plataforma de e-commerce). En estos casos, es más lógico que el comerciante a cargo del cobro sea la cuenta conectada. Puedes establecer el parámetro `on_behalf_of` en el ID de una cuenta conectada para que esa cuenta sea el comerciante a cargo del cobro. Cuando se usa `on_behalf_of`: - Los cargos *se liquidan* (When funds are available in your Stripe balance) en el país y *la moneda de cobro* (The settlement currency is the currency your bank account uses) de la cuenta conectada. - Se utiliza la estructura de comisiones del país de la cuenta conectada. - La descripción del cargo en el extracto bancario de la cuenta conectada se muestra en el extracto de la tarjeta de crédito del cliente. - Si la cuenta conectada está en un país diferente al de la plataforma, la dirección y el número de teléfono de la cuenta conectada se muestran en el extracto de la tarjeta de crédito del cliente. - La cantidad de días durante la que se retiene el [saldo pendiente](https://docs.stripe.com/connect/account-balances.md) antes de pagar depende de la configuración del [delay_days](https://docs.stripe.com/api/accounts/create.md#create_account-settings-payouts-schedule-delay_days) en la cuenta conectada. > #### API Accounts v2 > > No puedes usar la API Accounts v2 para gestionar la configuración de transferencias. Usa la API Accounts v1. Si se omite `on_behalf_of`, la plataforma es la empresa registrada para el pago. > El parámetro `on_behalf_of` solo se admite para cuentas conectadas con una funcionalidad de pagos como [card_payments](https://docs.stripe.com/connect/account-capabilities.md#card-payments). Las cuentas regidas por el [Contrato de servicios del destinatario](https://docs.stripe.com/connect/service-agreement-types.md#recipient) no pueden solicitar `card_payments` u otras funcionalidades de pago. ## Emitir reembolsos Si usas la API Payment Intents, los reembolsos deben emitirse contra [el último pago aceptado que se cree](https://docs.stripe.com/payments/payment-intents/verifying-status.md#identifying-charges). Los cargos creados en la cuenta de la plataforma se pueden rembolsar usando la clave secreta de la cuenta de la plataforma. Cuando se rembolsa un cargo con un `transfer_data[destination]`, de manera predeterminada, la cuenta de destino conserva los fondos transferidos y deja que la cuenta de la plataforma cubra el saldo negativo del rembolso. Para retirar los fondos de la cuenta conectada para cubrir el rembolso, establece el parámetro `reverse_transfer` en `true` al crear el rembolso: #### curl ```bash curl https://api.stripe.com/v1/refunds \ -u <>: \ -d charge="{CHARGE_ID}" \ -d reverse_transfer=true \ ``` De forma predeterminada, se rembolsa el cargo total, pero puedes crear un rembolso parcial definiendo el valor de `amount` con un número entero positivo. Si el rembolso implica que se devuelve el total del cargo, se revierte el total de la transferencia. De lo contrario, se revierte un importe proporcional de la transferencia. ### Reembolsar comisiones de la plataforma Cuando se reembolsa un cargo con una comisión de la plataforma, de manera predeterminada, la cuenta de la plataforma conserva los fondos de la comisión. Para volver a enviar los fondos de la comisión de la plataforma a la cuenta conectada, establece el parámetro [refund_application_fee](https://docs.stripe.com/api/refunds/create.md#create_refund-refund_application_fee) en `true` al crear el reembolso: #### curl ```bash curl https://api.stripe.com/v1/refunds \ -u <>: \ -d charge="{CHARGE_ID}" \ -d reverse_transfer=true \ -d refund_application_fee=true \ ``` Si reembolsas la comisión de la aplicación para un cargo a un Destino, también debes revertir la transferencia. Si el reembolso implica que se devuelve el total del cargo, dicho reembolso también incluye el total de la comisión. De lo contrario, reembolsarás un importe proporcional de la comisión. Como alternativa, puedes especificar un valor **false** para `refund_application_fee` y reembolsar la comisión de la plataforma por separado [a través de la API](https://docs.stripe.com/api.md#create_fee_refund). ### Reembolsos fallidos Si un reembolso falla, o lo [cancelas](https://docs.stripe.com/refunds.md#cancel-refund), el monto del reembolso fallido regresa al saldo de Stripe de tu cuenta de plataforma. Crea un [envío de fondos](https://docs.stripe.com/connect/separate-charges-and-transfers.md#create-transfer) para transferir los fondos a la cuenta conectada, según sea necesario. ## Gestionar disputas En el caso de los cargos de destino, con o sin `on_behalf_of`, Stripe debita los montos de las disputas y las comisiones de tu cuenta de la plataforma. Te recomendamos configurar [un webhook](https://docs.stripe.com/webhooks.md) para recibir notificaciones de los [eventos creados por la disputa](https://docs.stripe.com/api/events/types.md#event_types-charge.dispute.created). Cuando eso sucede, puedes intentar recuperar los fondos de la cuenta conectada revirtiendo la transferencia a través del [Dashboard](https://dashboard.stripe.com/test/transfers) o [creando una revocación de transferencia](https://docs.stripe.com/api/transfer_reversals/create.md). Si la cuenta conectada tiene un saldo negativo, Stripe intenta [debitar de su cuenta externa](https://docs.stripe.com/connect/account-balances.md#automatically-debit-connected-accounts) si `debit_negative_balances` se establece en `true`. Si impugnas la disputa y esta se resuelve a tu favor, puedes volver a transferir los fondos que revertiste previamente a la cuenta conectada. Si tu plataforma tiene un saldo insuficiente, la transferencia falla. Para evitar errores por saldo insuficiente, [agrega fondos a tu saldo de Stripe](https://docs.stripe.com/get-started/account/add-funds.md). > La retransferencia de una revocación anterior está sujeta a [restricciones de transferencia transfronteriza](https://docs.stripe.com/connect/account-capabilities.md#transfers-cross-border), lo que significa que es posible que no tengas medios para pagar tu cuenta conectada. Por el contrario, espera para recuperar transferencias de pagos transfronterizas disputadas por cargos a un destino con `on_behalf_of` hasta después de perder la disputa. ## Fallos en pagos asincrónicos En el caso de los cargos a un destino que usan métodos de pago asincrónicos (como débito ACH o débito SEPA), hay un retraso entre el momento en que se inicia el pago y el momento en que se confirman los fondos. Durante este tiempo, tanto el cargo como la transferencia al saldo pendiente de la cuenta conectada se encuentran en estado pendiente. Si el pago asincrónico falla, Stripe revierte automáticamente la transferencia. No se transfieren fondos de forma permanente a la cuenta conectada. ## Transferencias omitidas por estado de cuenta Los pagos que utilizan métodos de pago asincrónicos (como débito ACH o SEPA) demoran entre la autorización del pago y la disponibilidad de los fondos. Durante este tiempo, si la cuenta destino pierde la funcionalidad requerida de [envío de fondos](https://docs.stripe.com/connect/account-capabilities.md#supported-capabilities) o se cierra, Stripe no puede completar el envío de fondos según lo solicitado originalmente. Cuando Stripe intenta crear un envío de fondos, pero no puede hacerlo debido a la pérdida de funcionalidad o eliminación de cuenta, omitiremos el envío de fondos y los fondos permanecerán en el saldo de tu plataforma. Para detectar transferencias omitidas, escucha el evento webhook `charge.updated`. Si el valor de [transfer_data](https://docs.stripe.com/api/charges/object.md#charge_object-transfer_data) en el objeto cargo es `null`, esto indica un envío de fondos omitido. Cuando detectas un envío de fondos omitido, puedes crear un envío de fondos después de resolver el problema. ## Componentes integrados de Connect Los cargos a un destino son compatibles con los [componentes integrados de Connect](https://docs.stripe.com//connect/get-started-connect-embedded-components.md). Cuando usas el [componente integrado de pagos](https://docs.stripe.com/connect/supported-embedded-components/payments.md), puedes permitir que tus cuentas conectadas vean la información de pago desde tu sitio. Para los cargos a un destino con `on_behalf_of`, puedes usar la funcionalidad [destination_on_behalf_of_charge_management](https://docs.stripe.com/api/account_sessions/create.md#create_account_session-components-payments-features-destination_on_behalf_of_charge_management) para permitir que tus cuentas conectadas vean detalles adicionales, gestionen reembolsos y disputas, y permitan capturar pagos. Note: The following is a preview/demo component that behaves differently than live mode usage with real connected accounts. The actual component has more functionality than what might appear in this demo component. For example, for connected accounts without Stripe dashboard access (custom accounts), no user authentication is required in production. Los siguientes componentes muestran información para cargos a un destino: - [Componente de pago](https://docs.stripe.com/connect/supported-embedded-components/payments.md): muestra todos los pagos y las disputas de una cuenta. - [Detalles de pagos](https://docs.stripe.com/connect/supported-embedded-components/payment-details.md): Muestra todos los pagos y las disputas de una cuenta. - [Componente de lista de disputas](https://docs.stripe.com/connect/supported-embedded-components/disputes-list.md): muestra todas las disputas de una cuenta. - [Disputas para un componente de pago](https://docs.stripe.com/connect/supported-embedded-components/disputes-for-a-payment.md): muestra las disputas para un solo pago especificado. Puedes usarlo para incluir funcionalidades para gestionar disputas en una página con tu interfaz de usuario (IU) de pagos. ## See also - [Cómo trabajar con varias monedas](https://docs.stripe.com/connect/currencies.md) - [Descripción del cargo en el extracto bancario con Connect](https://docs.stripe.com/connect/statement-descriptors.md)