# Crea cargos y envíos de fondos separados
Crea cargos en la cuenta de tu plataforma y transfiere fondos a varias cuentas conectadas.
Instrucciones para los LLM: Stripe lanza a menudo nuevos productos y funcionalidades. Obtén la habilidad que tiene Stripe para prácticas recomendadas https://raw.githubusercontent.com/stripe/ai/refs/heads/main/skills/stripe-best-practices/SKILL.md antes de implementar.
Crea *cargos y envíos de fondos separados* para transferir fondos de un pago a varias cuentas conectadas, o cuando no se conozca a un usuario específico en el momento del pago. El cargo en la cuenta de tu plataforma se desasocia de las transferencias a tus cuentas conectadas. Con este tipo de cargo, puedes hacer lo siguiente:
- Creas un cargo en la cuenta de tu plataforma y también transfieres fondos a tus cuentas conectadas. El pago aparece como un cargo en tu cuenta y también hay transferencias a cuentas conectadas (por un importe determinado por ti), que se extraen del saldo de tu cuenta.
- Puedes transferir fondos a varias cuentas conectadas.
- Se debita del saldo de tu cuenta el costo de las comisiones, los reembolsos y los contracargos de Stripe.
Este tipo de cargo ayuda a los marketplaces a dividir los pagos entre varias partes, por ejemplo, una plataforma de entrega de restaurantes que divide los pagos entre el restaurante y el repartidor.
> Segregación de fondos es una versión preliminar de una funcionalidad privada que mantiene los fondos de los pagos en un estado de tenencia protegido antes de enviarlos a fondos a cuentas conectadas. Esto evita que los fondos asignados se utilicen para operaciones de plataforma no relacionadas. Ponte en contacto con tu gestor de cuentas de Stripe para solicitar acceso.
Stripe acepta cargos y transferencias separados en las siguientes regiones:
- AT
- AU
- BE
- BG
- BR
- CA
- CH
- CY
- CZ
- DE
- DK
- EE
- ES
- FI
- FR
- GB
- GR
- HR
- HU
- IE
- IT
- JP
- LI
- LT
- LU
- LV
- MT
- MX
- MY
- NL
- NO
- NZ
- PL
- PT
- RO
- SE
- SG
- SI
- SK
- US
## Transferencias transfronterizas
Stripe admite transferencias transfronterizas en el saldo de pagos entre los Estados Unidos, Canadá, el Reino Unido, el EEE y Suiza. En otras situaciones, tu plataforma y cualquier cuenta conectada deben estar en la misma región. Intentar transferir fondos a través de fronteras o saldos no admitidos devuelve un error. Consulta [Transferencias transfronterizas](https://docs.stripe.com/connect/cross-border-payouts.md) para ver los flujos de fondos admitidos entre otras regiones.
Solo debes usar transferencias en combinación con los casos de uso permitidos para [cargos](https://docs.stripe.com/connect/charges.md), [recargas](https://docs.stripe.com/connect/top-ups.md) y [comisiones](https://docs.stripe.com/connect/separate-charges-and-transfers.md#collect-fees). Te recomendamos usar cargos y envíos de fondos separados solo cuando seas responsable de los saldos negativos de tus cuentas conectadas.
Redirige a los clientes a una página de pagos alojada en Stripe con [Stripe Checkout](https://docs.stripe.com/payments/checkout.md). Comprueba cómo esta integración [se compara con los otros tipos de integración de Stripe](https://docs.stripe.com/payments/online-payments.md#compare-features-and-availability).
#### Esfuerzo de integración
Complexity: 2/5
#### Tipo de integración
Redirigir a la página de pagos alojada en Stripe
#### Personalización de la interfaz de usuario
Personalización limitada
- 20 fuentes preestablecidas
- 3 radio de borde preestablecido
- Fondo y color de borde personalizados
- Logotipo personalizado
[Probarlo](https://checkout.stripe.dev/)
Primero, [inscríbete](https://dashboard.stripe.com/register) para obtener una cuenta de Stripe.
Usa nuestras bibliotecas oficiales para acceder a la API de Stripe desde tu aplicación:
#### 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'
```
## Crea una sesión de Checkout [Lado del cliente] [Lado del servidor]
Una [sesión de Checkout](https://docs.stripe.com/api/checkout/sessions.md) controla lo que tu cliente puede ver en el formulario de pago, como las partidas, el importe y la moneda del pedido, así como los métodos de pago aceptados. Agrega un botón de pago en tu sitio web que llame a un punto de conexión del lado del servidor para crear una sesión de Checkout.
```html
Checkout
```
En tu servidor, crea una Checkout Session y redirige a tu cliente a la [URL](https://docs.stripe.com/api/checkout/sessions/object.md#checkout_session_object-url) que se devuelve en la respuesta.
```curl
curl https://api.stripe.com/v1/checkout/sessions \
-u "<>:" \
-d "line_items[0][price_data][currency]"=usd \
-d "line_items[0][price_data][product_data][name]"="Restaurant delivery service" \
-d "line_items[0][price_data][unit_amount]"=10000 \
-d "line_items[0][quantity]"=1 \
-d "payment_intent_data[transfer_group]"=ORDER100 \
-d mode=payment \
--data-urlencode success_url="https://example.com/success?session_id={CHECKOUT_SESSION_ID}"
```
- `line_items`: este atributo representa los artículos que compra el cliente. Los artículos se muestran en la página de pago alojada por Stripe.
- `payment_intent_data[transfer_group]`: utiliza una cadena única como `transfer_group` para identificar objetos asociados entre sí. Cuando Stripe crea automáticamente un cargo para un PaymentIntent con un valor `transfer_group`, asigna el mismo valor al `transfer_group` del cargo.
- `success_url`: Stripe redirige al cliente a la URL de confirmación después de que efectiviza un pago, y reemplaza la cadena `{CHECKOUT_SESSION_ID}` con la ID de la Checkout Session. Úsala para recuperar la Checkout Session e inspeccionar el estado para decidir qué mostrarás a tu cliente. También puede adjuntar sus propios parámetros de consulta, que se mantendrán durante el proceso de redireccionamiento. Consulta [Personaliza el comportamiento de redireccionamiento con una página alojada en Stripe](https://docs.stripe.com/payments/checkout/custom-success-page.md) para obtener más información.
(See full diagram at https://docs.stripe.com/connect/separate-charges-and-transfers)
## Gestionar eventos posteriores al pago [Lado del servidor]
Stripe envía un evento [checkout.session.completed](https://docs.stripe.com/api/events/types.md#event_types-checkout.session.completed) cuando se completa el pago. [Utiliza un webhook para recibir estos eventos](https://docs.stripe.com/webhooks/quickstart.md) y ejecutar acciones, como enviar un correo electrónico de confirmación del pedido a tu cliente, registrar la venta en una base de datos o iniciar el flujo de tareas para un 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. Además, algunos métodos de pago tardan entre 2 y 14 días en confirmar el pago. Si configuras tu integración para escuchar eventos asincrónicos, podrás aceptar varios [métodos de pago](https://stripe.com/payments/payment-methods-guide) con una sola integración.
Stripe recomienda administrar todos los siguientes eventos al cobrar pagos con Checkout:
| Evento | Descripción | Próximos pasos |
| -------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| [checkout.session.completed](https://docs.stripe.com/api/events/types.md#event_types-checkout.session.completed) | Mediante el envío del formulario de Checkout, el cliente ha autorizado correctamente el pago. | Espera hasta saber si el pago se concreta o no. |
| [checkout.session.async_payment_succeeded](https://docs.stripe.com/api/events/types.md#event_types-checkout.session.async_payment_succeeded) | El pago del cliente se efectuó correctamente. | Entrega los bienes o servicios comprados. |
| [checkout.session.async_payment_failed](https://docs.stripe.com/api/events/types.md#event_types-checkout.session.async_payment_failed) | El pago se rechazó o falló por algún otro motivo. | Ponte en contacto con el cliente por correo electrónico y solicítale que haga un nuevo pedido. |
Todos estos eventos incluyen el objeto [Checkout Session](https://docs.stripe.com/api/checkout/sessions.md). Una vez que el pago se efectúa correctamente, el [estado](https://docs.stripe.com/payments/paymentintents/lifecycle.md) del *PaymentIntent* (The Payment Intents API tracks the lifecycle of a customer checkout flow and triggers additional authentication steps when required by regulatory mandates, custom Radar fraud rules, or redirect-based payment methods) subyacente cambia de `processing` a `succeeded` o a un estado de falla.
## Crear un envío de fondos [Lado del servidor]
En tu servidor, envía fondos desde tu cuenta a una cuenta conectada creando un [envío de fondos](https://docs.stripe.com/api/transfers/create.md) y especificando el `transfer_group` utilizado.
```curl
curl https://api.stripe.com/v1/transfers \
-u "<>:" \
-d amount=7000 \
-d currency=usd \
-d destination="{{CONNECTEDACCOUNT_ID}}" \
-d transfer_group=ORDER100
```
Los importes de transferencia y cargo no tienen que coincidir. Puedes dividir un solo cargo entre varias transferencias o incluir varios cargos en una sola transferencia. En el siguiente ejemplo se crea una transferencia adicional asociada con el mismo `transfer_group`.
```curl
curl https://api.stripe.com/v1/transfers \
-u "<>:" \
-d amount=2000 \
-d currency=usd \
-d destination={{OTHER_CONNECTED_ACCOUNT_ID}} \
-d transfer_group=ORDER100
```
### Opciones de envíos de fondo
Puedes asignar cualquier valor a la cadena `transfer_group`, pero debes representar una sola acción comercial. También puedes realizar una transferencia sin un cargo asociado ni un `transfer_group`, por ejemplo, cuando debes pagar a un proveedor pero no hay un pago de cliente asociado.
> El `transfer_group` solo identifica los objetos asociados. No afecta a ninguna funcionalidad estándar. Para evitar que se ejecute una transferencia antes de que estén disponibles los fondos del cargo asociado, usa el atributo `source_transaction` de la transferencia.
De forma predeterminada, una solicitud de envío de fondos falla cuando el monto excede el [saldo disponible de la cuenta](https://docs.stripe.com/connect/account-balances.md) de la plataforma Stripe no reintenta automáticamente las solicitudes de envío de fondos fallidas.
Puedes evitar que se produzcan errores en las solicitudes de envío de fondos asociados a cargos. Cuando especificas el cargo asociado [como source_transaction del envío de fondos](https://docs.stripe.com/connect/separate-charges-and-transfers.md#transfer-availability), la solicitud de envío de fondos se efectúa automáticamente. Sin embargo, no ejecutamos dicho envío hasta que los fondos de ese cargo estén disponibles en la cuenta de la plataforma.
> Si utilizas cargos y envíos de fondos separados, tenlo en cuenta al planificar tu calendario de *transferencias* (A payout is the transfer of funds to an external account, usually a bank account, in the form of a deposit). Las transferencias automáticas pueden interferir con las transferencias que no tienen una `source_transaction` definida.
### Métodos de pago asincrónicos
Si usas *métodos de pago asincrónicos* (Asynchronous payment methods can take up to several days to confirm whether the payment has been successful. During this time, the payment can't be guaranteed) (como débito ACH o débito SEPA), espera a que se produzca un evento [charge.succeeded](https://docs.stripe.com/api/events/types.md#event_types-charge.succeeded) antes de crear una transferencia. A diferencia de los cargos a un destino, Stripe no revierte automáticamente una transferencia si falla el pago asincrónico asociado. Si creas una transferencia y luego falla el pago, el saldo de tu plataforma se debita por el importe de la transferencia. Luego, debes [revertir la transferencia](https://docs.stripe.com/connect/separate-charges-and-transfers.md#reverse-transfers) de forma manual para recuperar los fondos.
## 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. |
#### Billeteras
| Método de pago | Escenario | Cómo hacer la prueba |
| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Alipay | Tu cliente realiza un pago correctamente con un método de pago basado en redireccionamiento y con [notificación inmediata](https://docs.stripe.com/payments/payment-methods.md#payment-notification). | Elige cualquier método de pago basado en redireccionamiento, completa los datos solicitados y confirma el pago. Luego, haz click en **Completar pago de prueba** en la página de redireccionamiento. |
#### Redireccionamientos bancarios
| Método de pago | Escenario | Cómo hacer la prueba |
| ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Débito directo BECS | Tu cliente paga satisfactoriamente con débito directo BECS. | Completa el formulario con el número de cuenta `900123456` y BSB `000000`. El PaymentIntent confirmado pasa en un principio al estado `processing` y, 3 minutos más tarde, a `succeeded`. |
| Débito directo BECS | El pago de tu cliente falla con un código de error `account_closed`. | Completa el formulario con el número de cuenta `111111113` y BSB `000000`. |
| Bancontact, EPS, iDEAL y Przelewy24 | 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`. |
#### Vales
| Método de pago | Escenario | Cómo hacer la prueba |
| -------------- | ------------------------------------------ | -------------------------------------------------------------------------------------------------------- |
| Boleto, OXXO | Tu cliente paga con un vale Boleto u OXXO. | Selecciona Boleto u OXXO como método de pago y envía el pago. Cierra el diálogo después de que aparezca. |
Consulta [Pruebas](https://docs.stripe.com/testing.md) para obtener información adicional para probar tu integración.
## Optional: Habilita métodos de pago adicionales
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 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 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.
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`.
## 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.
```curl
curl https://api.stripe.com/v1/checkout/sessions \
-u "<>:" \
-d "line_items[0][price_data][currency]"=usd \
-d "line_items[0][price_data][product_data][name]"="Restaurant delivery service" \
-d "line_items[0][price_data][unit_amount]"=10000 \
-d "line_items[0][quantity]"=1 \
-d "payment_intent_data[on_behalf_of]"="{{CONNECTEDACCOUNT_ID}}" \
-d "payment_intent_data[transfer_group]"=ORDER100 \
-d mode=payment \
--data-urlencode success_url="https://example.com/success"
```
Integra un formulario de pago prediseñado en tu sitio con [Stripe Checkout](https://docs.stripe.com/payments/checkout.md). Comprueba cómo esta integración [se compara con los otros tipos de integración de Stripe](https://docs.stripe.com/payments/online-payments.md#compare-features-and-availability).
#### Esfuerzo de integración
Complexity: 2/5
#### Tipo de integración
Integra un formulario de pago prediseñado en tu sitio
#### Personalización de la interfaz de usuario
Personalización limitada
- 20 fuentes preestablecidas
- 3 radio de borde preestablecido
- Fondo y color de borde personalizados
- Logotipo personalizado
Primero, [inscríbete](https://dashboard.stripe.com/register) para obtener una cuenta de Stripe.
Usa nuestras bibliotecas oficiales para acceder a la API de Stripe desde tu aplicación:
#### 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'
```
## Crea una sesión de Checkout [Lado del cliente] [Lado del servidor]
Una [sesión de Checkout](https://docs.stripe.com/api/checkout/sessions.md) controla lo que tu cliente puede ver en el formulario de pago integrado, como las partidas, el importe del pedido y la moneda. Crea una sesión de Checkout en un punto de conexión del lado del servidor (por ejemplo, `/create-checkout-session`). La respuesta incluye un `client_secret` que usarás en el siguiente paso para montar Checkout.
```curl
curl https://api.stripe.com/v1/checkout/sessions \
-u "<>:" \
-d "line_items[0][price_data][currency]"=usd \
-d "line_items[0][price_data][product_data][name]"="Restaurant delivery service" \
-d "line_items[0][price_data][unit_amount]"=10000 \
-d "line_items[0][quantity]"=1 \
-d "payment_intent_data[transfer_group]"=ORDER100 \
-d mode=payment \
-d ui_mode=embedded \
--data-urlencode return_url="https://example.com/return?session_id={CHECKOUT_SESSION_ID}"
```
- `line_items`: este atributo representa los artículos que compra el cliente. Los ítems se muestran en el formulario de pago integrado.
- `payment_intent_data[transfer_group]`: utiliza una cadena única como `transfer_group` para identificar objetos asociados entre sí. Cuando Stripe crea automáticamente un cargo para un PaymentIntent con un valor `transfer_group`, asigna el mismo valor al `transfer_group` del cargo.
- `return_url`: Stripe redirige al cliente a la URL de devolución después de que complete un intento de pago y reemplaza la cadena `{CHECKOUT_SESSION_ID}` con la ID de la Checkout Session. Úsala para recuperar la Checkout Session e inspeccionar el estado para decidir qué mostrarás a tu cliente. Asegúrate de que la URL de devolución corresponda a una página de tu sitio web que proporcione el estado del pago. También puede adjuntar sus propios parámetros de consulta, que se mantendrán durante el proceso de redireccionamiento. Para obtener más información, consulta [Personalizar el comportamiento de redireccionamiento con un formulario integrado](https://docs.stripe.com/payments/checkout/custom-success-page.md?payment-ui=embedded-form).
(See full diagram at https://docs.stripe.com/connect/separate-charges-and-transfers)
## Monta Checkout [Lado del cliente]
#### HTML + JS
Checkout está disponible como parte de [Stripe.js](https://docs.stripe.com/js.md). Incluye el script de Stripe.js en tu página agregándolo al encabezado de tu archivo HTML. A continuación, crea un nodo DOM vacío (contenedor) para usarlo en el montaje.
```html
```
Inicializa Stripe.js con tu clave de API publicable. Pasa el `client_secret` del paso anterior a `options` cuando crees la instancia de Checkout:
```javascript
// Initialize Stripe.js
const stripe = Stripe('<>');
initialize();
// Fetch Checkout Session and retrieve the client secret
async function initialize() {
const fetchClientSecret = async () => {
const response = await fetch("/create-checkout-session", {
method: "POST",
});
const { clientSecret } = await response.json();
return clientSecret;
};
// Initialize Checkout
const checkout = await stripe.initEmbeddedCheckout({
fetchClientSecret,
});
// Mount Checkout
checkout.mount('#checkout');
}
```
#### React
Instala Connect.js y las bibliotecas de React Connect.js desde el [registro público de npm](https://www.npmjs.com/package/@stripe/react-connect-js).
```bash
npm install --save @stripe/connect-js @stripe/react-connect-js
```
Para utilizar el componente Embedded Checkout, crea un `EmbeddedCheckoutProvider`. Llama a `loadStripe` con tu clave de API publicable y especifica la `Promise` devuelta en el proveedor. Usa la indicación `options` aceptada por el proveedor para especificar el `client_secret` del paso anterior.
```jsx
import * as React from 'react';
import {loadStripe} from '@stripe/stripe-js';
import {
EmbeddedCheckoutProvider,
EmbeddedCheckout
} from '@stripe/react-stripe-js';
// Make sure to call `loadStripe` outside of a component’s render to avoid
// recreating the `Stripe` object on every render.
const stripePromise = loadStripe('<>');
const App = ({clientSecret}) => {
const options = {clientSecret};
return (
)
}
```
Checkout se muestra en un iframe que envía la información de pago a Stripe de manera segura mediante una conexión HTTPS. No coloques Checkout dentro de otro iframe porque, para algunos métodos de pago, se requiere el redireccionamiento a otra página a fin de confirmar el pago.
## Gestionar eventos posteriores al pago [Lado del servidor]
Stripe envía un evento [checkout.session.completed](https://docs.stripe.com/api/events/types.md#event_types-checkout.session.completed) cuando se completa el pago. [Utiliza un webhook para recibir estos eventos](https://docs.stripe.com/webhooks/quickstart.md) y ejecutar acciones, como enviar un correo electrónico de confirmación del pedido a tu cliente, registrar la venta en una base de datos o iniciar el flujo de tareas para un 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. Además, algunos métodos de pago tardan entre 2 y 14 días en confirmar el pago. Si configuras tu integración para escuchar eventos asincrónicos, podrás aceptar varios [métodos de pago](https://stripe.com/payments/payment-methods-guide) con una sola integración.
Stripe recomienda administrar todos los siguientes eventos al cobrar pagos con Checkout:
| Evento | Descripción | Próximos pasos |
| -------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| [checkout.session.completed](https://docs.stripe.com/api/events/types.md#event_types-checkout.session.completed) | Mediante el envío del formulario de Checkout, el cliente ha autorizado correctamente el pago. | Espera hasta saber si el pago se concreta o no. |
| [checkout.session.async_payment_succeeded](https://docs.stripe.com/api/events/types.md#event_types-checkout.session.async_payment_succeeded) | El pago del cliente se efectuó correctamente. | Entrega los bienes o servicios comprados. |
| [checkout.session.async_payment_failed](https://docs.stripe.com/api/events/types.md#event_types-checkout.session.async_payment_failed) | El pago se rechazó o falló por algún otro motivo. | Ponte en contacto con el cliente por correo electrónico y solicítale que haga un nuevo pedido. |
Todos estos eventos incluyen el objeto [Checkout Session](https://docs.stripe.com/api/checkout/sessions.md). Una vez que el pago se efectúa correctamente, el [estado](https://docs.stripe.com/payments/paymentintents/lifecycle.md) del *PaymentIntent* (The Payment Intents API tracks the lifecycle of a customer checkout flow and triggers additional authentication steps when required by regulatory mandates, custom Radar fraud rules, or redirect-based payment methods) subyacente cambia de `processing` a `succeeded` o a un estado de falla.
## Crear un envío de fondos [Lado del servidor]
En tu servidor, envía fondos desde tu cuenta a una cuenta conectada creando un [envío de fondos](https://docs.stripe.com/api/transfers/create.md) y especificando el `transfer_group` utilizado.
```curl
curl https://api.stripe.com/v1/transfers \
-u "<>:" \
-d amount=7000 \
-d currency=usd \
-d destination="{{CONNECTEDACCOUNT_ID}}" \
-d transfer_group=ORDER100
```
Los importes de transferencia y cargo no tienen que coincidir. Puedes dividir un solo cargo entre varias transferencias o incluir varios cargos en una sola transferencia. En el siguiente ejemplo se crea una transferencia adicional asociada con el mismo `transfer_group`.
```curl
curl https://api.stripe.com/v1/transfers \
-u "<>:" \
-d amount=2000 \
-d currency=usd \
-d destination={{OTHER_CONNECTED_ACCOUNT_ID}} \
-d transfer_group=ORDER100
```
### Opciones de envíos de fondo
Puedes asignar cualquier valor a la cadena `transfer_group`, pero debes representar una sola acción comercial. También puedes realizar una transferencia sin un cargo asociado ni un `transfer_group`, por ejemplo, cuando debes pagar a un proveedor pero no hay un pago de cliente asociado.
> El `transfer_group` solo identifica los objetos asociados. No afecta a ninguna funcionalidad estándar. Para evitar que se ejecute una transferencia antes de que estén disponibles los fondos del cargo asociado, usa el atributo `source_transaction` de la transferencia.
De forma predeterminada, una solicitud de envío de fondos falla cuando el monto excede el [saldo disponible de la cuenta](https://docs.stripe.com/connect/account-balances.md) de la plataforma Stripe no reintenta automáticamente las solicitudes de envío de fondos fallidas.
Puedes evitar que se produzcan errores en las solicitudes de envío de fondos asociados a cargos. Cuando especificas el cargo asociado [como source_transaction del envío de fondos](https://docs.stripe.com/connect/separate-charges-and-transfers.md#transfer-availability), la solicitud de envío de fondos se efectúa automáticamente. Sin embargo, no ejecutamos dicho envío hasta que los fondos de ese cargo estén disponibles en la cuenta de la plataforma.
> Si utilizas cargos y envíos de fondos separados, tenlo en cuenta al planificar tu calendario de *transferencias* (A payout is the transfer of funds to an external account, usually a bank account, in the form of a deposit). Las transferencias automáticas pueden interferir con las transferencias que no tienen una `source_transaction` definida.
### Métodos de pago asincrónicos
Si usas *métodos de pago asincrónicos* (Asynchronous payment methods can take up to several days to confirm whether the payment has been successful. During this time, the payment can't be guaranteed) (como débito ACH o débito SEPA), espera a que se produzca un evento [charge.succeeded](https://docs.stripe.com/api/events/types.md#event_types-charge.succeeded) antes de crear una transferencia. A diferencia de los cargos a un destino, Stripe no revierte automáticamente una transferencia si falla el pago asincrónico asociado. Si creas una transferencia y luego falla el pago, el saldo de tu plataforma se debita por el importe de la transferencia. Luego, debes [revertir la transferencia](https://docs.stripe.com/connect/separate-charges-and-transfers.md#reverse-transfers) de forma manual para recuperar los fondos.
## 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. |
#### Billeteras
| Método de pago | Escenario | Cómo hacer la prueba |
| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Alipay | Tu cliente realiza un pago correctamente con un método de pago basado en redireccionamiento y con [notificación inmediata](https://docs.stripe.com/payments/payment-methods.md#payment-notification). | Elige cualquier método de pago basado en redireccionamiento, completa los datos solicitados y confirma el pago. Luego, haz click en **Completar pago de prueba** en la página de redireccionamiento. |
#### Redireccionamientos bancarios
| Método de pago | Escenario | Cómo hacer la prueba |
| ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Débito directo BECS | Tu cliente paga satisfactoriamente con débito directo BECS. | Completa el formulario con el número de cuenta `900123456` y BSB `000000`. El PaymentIntent confirmado pasa en un principio al estado `processing` y, 3 minutos más tarde, a `succeeded`. |
| Débito directo BECS | El pago de tu cliente falla con un código de error `account_closed`. | Completa el formulario con el número de cuenta `111111113` y BSB `000000`. |
| Bancontact, EPS, iDEAL y Przelewy24 | 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`. |
#### Vales
| Método de pago | Escenario | Cómo hacer la prueba |
| -------------- | ------------------------------------------ | -------------------------------------------------------------------------------------------------------- |
| Boleto, OXXO | Tu cliente paga con un vale Boleto u OXXO. | Selecciona Boleto u OXXO como método de pago y envía el pago. Cierra el diálogo después de que aparezca. |
Consulta [Pruebas](https://docs.stripe.com/testing.md) para obtener información adicional para probar tu integración.
## Optional: Habilita métodos de pago adicionales
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 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 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.
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`.
## 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.
```curl
curl https://api.stripe.com/v1/checkout/sessions \
-u "<>:" \
-d "line_items[0][price_data][currency]"=usd \
-d "line_items[0][price_data][product_data][name]"="Restaurant delivery service" \
-d "line_items[0][price_data][unit_amount]"=10000 \
-d "line_items[0][quantity]"=1 \
-d "payment_intent_data[on_behalf_of]"="{{CONNECTEDACCOUNT_ID}}" \
-d "payment_intent_data[transfer_group]"=ORDER100 \
-d mode=payment \
-d ui_mode=embedded \
--data-urlencode return_url="https://example.com/return"
```
Para crear una integración de pagos personalizada, integra componentes de interfaz de usuario (IU) en tu sitio con [Stripe Elements](https://docs.stripe.com/payments/elements.md). El código del lado del cliente y del lado del servidor crea un formulario de confirmación de compra que acepta varios métodos de pago. Comprueba cómo esta integración [se compara con los otros tipos de integración de Stripe](https://docs.stripe.com/payments/online-payments.md#compare-features-and-availability).
#### Esfuerzo de integración
Complexity: 3/5
#### Tipo de integración
Combina componentes de la interfaz de usuario en un flujo de pago personalizado
#### Personalización de la interfaz de usuario
Personalización a nivel CSS con la [API Appearance](https://docs.stripe.com/elements/appearance-api.md)
Primero, [inscríbete](https://dashboard.stripe.com/register) para obtener una cuenta de Stripe.
Usa nuestras bibliotecas oficiales para acceder a la API de Stripe desde tu aplicación:
#### 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'
```
## Crear un PaymentIntent [Lado del servidor]
Stripe usa un objeto [PaymentIntent](https://docs.stripe.com/api/payment_intents.md) para representar tu intención de cobrar a un cliente y hace el seguimiento de los intentos de cobro y de los cambios en el estado del pago en todo el proceso.
Un excelente resumen de la integración de pagos que se describe en este documento. (See full diagram at https://docs.stripe.com/connect/separate-charges-and-transfers)
Los métodos de pago que se muestran a los clientes durante el proceso de finalización de compra también se incluyen en el PaymentIntent. Puedes permitir que Stripe extraiga automáticamente los métodos de pago desde la configuración de tu Dashboard o puedes enumerarlos manualmente.
A menos que tu integración requiera una opción basada en código para ofrecer métodos de pago, no los enumeres manualmente. 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. Stripe prioriza los métodos de pago que aumentan la conversión y guardan mayor relación con la moneda y la ubicación del cliente. Stripe oculta los métodos de pago menos prioritarios en un menú de contenido adicional.
#### Gestionar los métodos de pago desde el Dashboard
Crea una PaymentIntent en tu servidor con un importe, una moneda y un valor `transfer_group` para asociar con el envío de fondos más adelante. En la última versión de la API, especificar el parámetro `automatic_payment_methods` es opcional porque Stripe habilita su funcionalidad de forma predeterminada. Puedes gestionar los métodos de pago desde el [Dashboard](https://dashboard.stripe.com/settings/payment_methods). Stripe gestiona las devoluciones de los métodos de pago que cumplen los requisitos en función de factores como el importe de la transacción, la moneda y el flujo de pagos.
```curl
curl https://api.stripe.com/v1/payment_intents \
-u "<>:" \
-d amount=10000 \
-d currency=usd \
-d "automatic_payment_methods[enabled]"=true \
-d transfer_group=ORDER100
```
#### Enumerar métodos de pago manualmente
Crea una PaymentIntent en tu servidor con un importe, una moneda, una lista de tipos de métodos de pago y un valor `transfer_group` para asociar con el envío de fondos más adelante. Siempre decide cuánto cobrar del lado del servidor, un entorno de confianza, y no del lado del cliente. Esto impide que clientes maliciosos puedan elegir sus propios precios.
```curl
curl https://api.stripe.com/v1/payment_intents \
-u "<>:" \
-d amount=10000 \
-d currency=eur \
-d "payment_method_types[]"=bancontact \
-d "payment_method_types[]"=card \
-d "payment_method_types[]"=eps \
-d "payment_method_types[]"=ideal \
-d "payment_method_types[]"=p24 \
-d "payment_method_types[]"=sepa_debit \
-d transfer_group=ORDER100
```
Elige la moneda según los métodos de pago que quieras ofrecer. Algunos métodos de pago admiten múltiples monedas y países. Este ejemplo sirve para Bancontact, tarjetas de crédito, EPS, iDEAL, Przelewy24 y débito directo SEPA.
> 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 las [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.
### Recuperar el secreto de cliente
El PaymentIntent incluye un *secreto de cliente* (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)) que el lado del cliente usa para completar el proceso de pago de forma segura. Puedes usar diferentes métodos para pasar el secreto del cliente al lado del cliente.
#### Aplicación de una sola página
Recupera el secreto de cliente de un punto de conexión de tu servidor con la funcionalidad `fetch` del navegador. Este método es más conveniente si tu lado del cliente es una aplicación de una sola página, especialmente, si fue diseñada con un marco de front-end moderno como React. Crea el punto de conexión del servidor que se usa para el secreto de cliente:
#### Ruby
```ruby
get '/secret' do
intent = # ... Create or retrieve the PaymentIntent
{client_secret: intent.client_secret}.to_json
end
```
Luego recupera el secreto de cliente con JavaScript del lado del cliente:
```javascript
(async () => {
const response = await fetch('/secret');
const {client_secret: clientSecret} = await response.json();
// Render the form using the clientSecret
})();
```
#### Renderización del lado del servidor
Especifica el secreto de cliente desde tu servidor al cliente. Este enfoque funciona mejor si tu aplicación genera contenido estático en el servidor antes de enviarlo al navegador.
Agrega [client_secret](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-client_secret) en tu formulario de finalización de compra. En el código del lado de tu servidor, recupera el secreto de cliente de PaymentIntent:
#### Ruby
```erb
```
```ruby
get '/checkout' do
@intent = # ... Fetch or create the PaymentIntent
erb :checkout
end
```
## Recopilar datos de pago [Lado del cliente]
Recopila los datos de pago del cliente con el [Payment Element](https://docs.stripe.com/payments/payment-element.md). Payment Element es un componente de interfaz de usuario prediseñado que simplifica la recopilación de datos de pago para una variedad de métodos de pago.
El Payment Element contiene un iframe que envía la información de pago a Stripe de manera segura mediante una conexión HTTPS. No coloques el Payment Element dentro de otro iframe porque, para algunos métodos de pago, se requiere la redirección a otra página para la confirmación del pago.
Si optas por usar un iframe y quieres aceptar Apple Pay o Google Pay, el iframe debe tener el atributo [allow](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe#attr-allowpaymentrequest) establecido en `«payment*»`.
Para que la integración funcione, la dirección de la página del proceso de compra debe empezar con `https://` rather en lugar de `http://` for. Puedes probar tu integración sin usar HTTPS, pero recuerda [habilitarla](https://docs.stripe.com/security/guide.md#tls) cuando todo esté listo para aceptar pagos activos.
#### HTML + JS
### Configurar Stripe.js
El Payment Element se encuentra disponible automáticamente como funcionalidad de Stripe.js. Incluye el script de Stripe.js en tu página de finalización de compra agregándolo al `head` de tu archivo HTML. Siempre debes cargar Stripe.js directamente desde js.stripe.com para cumplir con la normativa PCI. No incluyas el script en un paquete ni alojes una copia en tus sistemas.
```html
Checkout
```
Crea una instancia de Stripe con el siguiente código JavaScript en tu página de pago:
```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
const stripe = Stripe('<>');
```
### Agrega el Payment Element a tu página de pago
El Payment Element necesita un lugar específico en tu página de pago. Crea un nodo DOM vacío (contenedor) con un ID único en tu formulario de pago:
```html
```
Cuando se cargue el formulario anterior, crea una instancia de Payment Element y móntala en el nodo DOM del contenedor. Especifica el [secreto de cliente](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-client_secret) del paso anterior en `options` cuando crees la instancia [Elements](https://docs.stripe.com/js/elements_object/create):
Debes administrar el secreto de cliente con cuidado porque sirve para completar el cargo. No lo registres, no lo insertes en direcciones URL ni lo expongas a nadie que no sea el cliente.
```javascript
const options = {
clientSecret: '{{CLIENT_SECRET}}',
// Fully customizable with appearance API.
appearance: {/*...*/},
};
// Set up Stripe.js and Elements to use in checkout form, passing the client secret obtained in a previous stepconst elements = stripe.elements(options);
// Create and mount the Payment Element
const paymentElementOptions = { layout: 'accordion'};
const paymentElement = elements.create('payment', paymentElementOptions);
paymentElement.mount('#payment-element');
```
#### React
### Configurar Stripe.js
Instala [React Stripe.js](https://www.npmjs.com/package/@stripe/react-stripe-js) y el [cargador de Stripe.js](https://www.npmjs.com/package/@stripe/stripe-js) desde el registro público de npm:
```bash
npm install --save @stripe/react-stripe-js @stripe/stripe-js
```
### Agrega y configura el proveedor Elements en tu página de pago
Para usar el componente Payment Element, envuelve el componente de tu página de confirmación de compra con un [proveedor Elements](https://docs.stripe.com/sdks/stripejs-react.md#elements-provider). Llama a `loadStripe` con tu clave publicable y especifica el valor `Promise` devuelto en el proveedor `Elements`. También debes especificar el [secreto de cliente](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-client_secret) del paso anterior como `options` al proveedor `Elements`.
```jsx
import React from 'react';
import ReactDOM from 'react-dom';
import {Elements} from '@stripe/react-stripe-js';
import {loadStripe} from '@stripe/stripe-js';
import CheckoutForm from './CheckoutForm';
// Make sure to call `loadStripe` outside of a component’s render to avoid
// recreating the `Stripe` object on every render.
const stripePromise = loadStripe('<>');
function App() {
const options = {
// passing the client secret obtained in step 3
clientSecret: '{{CLIENT_SECRET}}',
// Fully customizable with appearance API.
appearance: {/*...*/},
};
return (
);
};
ReactDOM.render(, document.getElementById('root'));
```
### Agregar el componente Payment Element
Usa el componente `PaymentElement` para crear tu formulario:
```jsx
import React from 'react';
import {PaymentElement} from '@stripe/react-stripe-js';
const CheckoutForm = () => {
return (
);
};
export default CheckoutForm;
```
Stripe Elements es una colección de componentes de interfaz de usuario (IU) desplegables. Para personalizar aún más tu formulario o recopilar otra información del cliente, consulta la [documentación de Elements](https://docs.stripe.com/payments/elements.md).
El Payment Element renderiza un formulario dinámico que le permite a tu cliente elegir un método de pago. Para cada método de pago, el formulario le pide automáticamente al cliente que complete todos los datos de pago necesarios.
### Personaliza el aspecto
Personaliza el Payment Element para que coincida con el diseño de tu sitio especificando el [objeto appearance](https://docs.stripe.com/js/elements_object/create#stripe_elements-options-appearance) en `options` al crear el proveedor `Elements`.
### Recopila las direcciones
Por defecto, el Payment Element solo junta los detalles necesarios de la dirección de facturación. Algunos comportamientos, como el [cálculo de impuestos](https://docs.stripe.com/api/tax/calculations/create.md) o la introducción de datos de envío, requieren la dirección completa de tu cliente. Puedes realizar lo siguiente:
- Utiliza el [Address Element](https://docs.stripe.com/elements/address-element.md) para aprovechar las funcionalidades de autocompletar y localizar para obtener la dirección completa de tu cliente. Esto ayuda a garantizar el cálculo de impuestos más preciso.
- Recopila los datos de la dirección mediante tu propio formulario personalizado.
### Solicita un token de comerciante de Apple Pay
Si configuraste tu integración para [aceptar pagos de Apple Pay](https://docs.stripe.com/payments/accept-a-payment.md?payment-ui=elements&api-integration=checkout), te recomendamos que configures la interfaz Apple Pay que devuelva un token de comercio, lo que permite habilitar transacciones iniciadas por el comercio (MIT). [Solicita el tipo de token de comercio correspondiente](https://docs.stripe.com/apple-pay/merchant-tokens.md?pay-element=web-pe) en el Payment Element.
## Enviar el pago a Stripe [Lado del cliente]
Usa [stripe.confirmPayment](https://docs.stripe.com/js/payment_intents/confirm_payment) para completar el pago con los datos del Payment Element. Proporciona una [return_url](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-return_url) a esta función para indicar a dónde Stripe debe redirigir al usuario después de completar el pago. Es posible que primero se redirija al usuario a un sitio intermedio, como una página de autorización del banco y, luego, a la`return_url`. Los pagos con tarjeta redirigen inmediatamente a la `return_url` cuando un pago se realiza correctamente.
Si no quieres realizar el redireccionamiento de pagos con tarjeta una vez que se completan los pagos, puedes configurar el [redireccionamiento](https://docs.stripe.com/js/payment_intents/confirm_payment#confirm_payment_intent-options-redirect) en `if_required`. Esto solo redirigirá a los clientes que finalizan su compra con métodos de pago basados en redireccionamiento.
#### HTML + JS
```javascript
const form = document.getElementById('payment-form');
form.addEventListener('submit', async (event) => {
event.preventDefault();
const {error} = await stripe.confirmPayment({
//`Elements` instance that was used to create the Payment Element
elements,
confirmParams: {
return_url: 'https://example.com/order/123/complete',
},
});
if (error) {
// This point will only be reached if there is an immediate error when
// confirming the payment. Show error to your customer (for example, payment
// details incomplete)
const messageContainer = document.querySelector('#error-message');
messageContainer.textContent = error.message;
} else {
// Your customer will be redirected to your `return_url`. For some payment
// methods like iDEAL, your customer will be redirected to an intermediate
// site first to authorize the payment, then redirected to the `return_url`.
}
});
```
#### React
Para llamar a [stripe.confirmPayment](https://docs.stripe.com/js/payment_intents/confirm_payment) desde el componente del formulario de pago, usa los hooks [useStripe](https://docs.stripe.com/sdks/stripejs-react.md#usestripe-hook) y [useElements](https://docs.stripe.com/sdks/stripejs-react.md#useelements-hook).
Si prefieres componentes de clase tradicionales en lugar de hooks, puedes usar un [ElementsConsumer](https://docs.stripe.com/sdks/stripejs-react.md#elements-consumer).
```jsx
import React, {useState} from 'react';
import {useStripe, useElements, PaymentElement} from '@stripe/react-stripe-js';
const CheckoutForm = () => {
const stripe = useStripe();
const elements = useElements();
const [errorMessage, setErrorMessage] = useState(null);
const handleSubmit = async (event) => {
// We don't want to let default form submission happen here,
// which would refresh the page.
event.preventDefault();
if (!stripe || !elements) {
// Stripe.js hasn't yet loaded.
// Make sure to disable form submission until Stripe.js has loaded.
return;
}
const {error} = await stripe.confirmPayment({
//`Elements` instance that was used to create the Payment Element
elements,
confirmParams: {
return_url: 'https://example.com/order/123/complete',
},
});
if (error) {
// This point will only be reached if there is an immediate error when
// confirming the payment. Show error to your customer (for example, payment
// details incomplete)
setErrorMessage(error.message);
} else {
// Your customer will be redirected to your `return_url`. For some payment
// methods like iDEAL, your customer will be redirected to an intermediate
// site first to authorize the payment, then redirected to the `return_url`.
}
};
return (
);
};
export default CheckoutForm;
```
Asegúrate de que la `return_url` corresponda a una página de tu sitio web que proporcione el estado del pago. Cuando Stripe redirige al cliente a la `return_url`, proporcionamos los siguientes parámetros de consulta de URL:
| Parámetro | Descripción |
| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `payment_intent` | El identificador único del `PaymentIntent`. |
| `payment_intent_client_secret` | El [secreto de cliente](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-client_secret) del objeto `PaymentIntent`. |
> Si tienes herramientas que rastrean la sesión del navegador del cliente, es posible que debas agregar el dominio `stripe.com` a la lista de exclusión de referentes. Los redireccionamientos hacen que algunas herramientas creen nuevas sesiones, lo que te impide realizar un seguimiento de la sesión completa.
Usa uno de los parámetros de consulta para recuperar el PaymentIntent. Examina el [estado del PaymentIntent](https://docs.stripe.com/payments/paymentintents/lifecycle.md) para decidir qué mostrarás a tus clientes. También puedes adjuntar tus propios parámetros de consulta cuando proporciones la `return_url`, que se mantendrán durante el proceso de redireccionamiento.
#### HTML + JS
```javascript
// Initialize Stripe.js using your publishable key
const stripe = Stripe('<>');
// Retrieve the "payment_intent_client_secret" query parameter appended to
// your return_url by Stripe.js
const clientSecret = new URLSearchParams(window.location.search).get(
'payment_intent_client_secret'
);
// Retrieve the PaymentIntent
stripe.retrievePaymentIntent(clientSecret).then(({paymentIntent}) => {
const message = document.querySelector('#message')
// Inspect the PaymentIntent `status` to indicate the status of the payment
// to your customer.
//
// Some payment methods will [immediately succeed or fail][0] upon
// confirmation, while others will first enter a `processing` state.
//
// [0]: https://stripe.com/docs/payments/payment-methods#payment-notification
switch (paymentIntent.status) {
case 'succeeded':
message.innerText = 'Success! Payment received.';
break;
case 'processing':
message.innerText = "Payment processing. We'll update you when payment is received.";
break;
case 'requires_payment_method':
message.innerText = 'Payment failed. Please try another payment method.';
// Redirect your user back to your payment page to attempt collecting
// payment again
break;
default:
message.innerText = 'Something went wrong.';
break;
}
});
```
#### React
```jsx
import React, {useState, useEffect} from 'react';
import {useStripe} from '@stripe/react-stripe-js';
const PaymentStatus = () => {
const stripe = useStripe();
const [message, setMessage] = useState(null);
useEffect(() => {
if (!stripe) {
return;
}
// Retrieve the "payment_intent_client_secret" query parameter appended to
// your return_url by Stripe.js
const clientSecret = new URLSearchParams(window.location.search).get(
'payment_intent_client_secret'
);
// Retrieve the PaymentIntent
stripe
.retrievePaymentIntent(clientSecret)
.then(({paymentIntent}) => {
// Inspect the PaymentIntent `status` to indicate the status of the payment
// to your customer.
//
// Some payment methods will [immediately succeed or fail][0] upon
// confirmation, while others will first enter a `processing` state.
//
// [0]: https://stripe.com/docs/payments/payment-methods#payment-notification
switch (paymentIntent.status) {
case 'succeeded':
setMessage('Success! Payment received.');
break;
case 'processing':
setMessage("Payment processing. We'll update you when payment is received.");
break;
case 'requires_payment_method':
// Redirect your user back to your payment page to attempt collecting
// payment again
setMessage('Payment failed. Please try another payment method.');
break;
default:
setMessage('Something went wrong.');
break;
}
});
}, [stripe]);
return message;
};
export default PaymentStatus;
```
## 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. |
## Crear un envío de fondos [Lado del servidor]
En tu servidor, envía fondos desde tu cuenta a una cuenta conectada creando un [envío de fondos](https://docs.stripe.com/api/transfers/create.md) y especificando el `transfer_group` utilizado.
```curl
curl https://api.stripe.com/v1/transfers \
-u "<>:" \
-d amount=7000 \
-d currency=usd \
-d destination="{{CONNECTEDACCOUNT_ID}}" \
-d transfer_group=ORDER100
```
Los importes de transferencia y cargo no tienen que coincidir. Puedes dividir un solo cargo entre varias transferencias o incluir varios cargos en una sola transferencia. En el siguiente ejemplo se crea una transferencia adicional asociada con el mismo `transfer_group`.
```curl
curl https://api.stripe.com/v1/transfers \
-u "<>:" \
-d amount=2000 \
-d currency=usd \
-d destination={{OTHER_CONNECTED_ACCOUNT_ID}} \
-d transfer_group=ORDER100
```
### Opciones de envíos de fondo
Puedes asignar cualquier valor a la cadena `transfer_group`, pero debes representar una sola acción comercial. También puedes realizar una transferencia sin un cargo asociado ni un `transfer_group`, por ejemplo, cuando debes pagar a un proveedor pero no hay un pago de cliente asociado.
> El `transfer_group` solo identifica los objetos asociados. No afecta a ninguna funcionalidad estándar. Para evitar que se ejecute una transferencia antes de que estén disponibles los fondos del cargo asociado, usa el atributo `source_transaction` de la transferencia.
De forma predeterminada, una solicitud de envío de fondos falla cuando el monto excede el [saldo disponible de la cuenta](https://docs.stripe.com/connect/account-balances.md) de la plataforma Stripe no reintenta automáticamente las solicitudes de envío de fondos fallidas.
Puedes evitar que se produzcan errores en las solicitudes de envío de fondos asociados a cargos. Cuando especificas el cargo asociado [como source_transaction del envío de fondos](https://docs.stripe.com/connect/separate-charges-and-transfers.md#transfer-availability), la solicitud de envío de fondos se efectúa automáticamente. Sin embargo, no ejecutamos dicho envío hasta que los fondos de ese cargo estén disponibles en la cuenta de la plataforma.
> Si utilizas cargos y envíos de fondos separados, tenlo en cuenta al planificar tu calendario de *transferencias* (A payout is the transfer of funds to an external account, usually a bank account, in the form of a deposit). Las transferencias automáticas pueden interferir con las transferencias que no tienen una `source_transaction` definida.
### Métodos de pago asincrónicos
Si usas *métodos de pago asincrónicos* (Asynchronous payment methods can take up to several days to confirm whether the payment has been successful. During this time, the payment can't be guaranteed) (como débito ACH o débito SEPA), espera a que se produzca un evento [charge.succeeded](https://docs.stripe.com/api/events/types.md#event_types-charge.succeeded) antes de crear una transferencia. A diferencia de los cargos a un destino, Stripe no revierte automáticamente una transferencia si falla el pago asincrónico asociado. Si creas una transferencia y luego falla el pago, el saldo de tu plataforma se debita por el importe de la transferencia. Luego, debes [revertir la transferencia](https://docs.stripe.com/connect/separate-charges-and-transfers.md#reverse-transfers) de forma manual para recuperar los fondos.
## 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. |
#### Billeteras
| Método de pago | Escenario | Cómo hacer la prueba |
| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Alipay | Tu cliente realiza un pago correctamente con un método de pago basado en redireccionamiento y con [notificación inmediata](https://docs.stripe.com/payments/payment-methods.md#payment-notification). | Elige cualquier método de pago basado en redireccionamiento, completa los datos solicitados y confirma el pago. Luego, haz click en **Completar pago de prueba** en la página de redireccionamiento. |
#### Redireccionamientos bancarios
| Método de pago | Escenario | Cómo hacer la prueba |
| ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Débito directo BECS | Tu cliente paga satisfactoriamente con débito directo BECS. | Completa el formulario con el número de cuenta `900123456` y BSB `000000`. El PaymentIntent confirmado pasa en un principio al estado `processing` y, 3 minutos más tarde, a `succeeded`. |
| Débito directo BECS | El pago de tu cliente falla con un código de error `account_closed`. | Completa el formulario con el número de cuenta `111111113` y BSB `000000`. |
| Bancontact, EPS, iDEAL y Przelewy24 | 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`. |
#### Vales
| Método de pago | Escenario | Cómo hacer la prueba |
| -------------- | ------------------------------------------ | -------------------------------------------------------------------------------------------------------- |
| Boleto, OXXO | Tu cliente paga con un vale Boleto u OXXO. | Selecciona Boleto u OXXO como método de pago y envía el pago. Cierra el diálogo después de que aparezca. |
Consulta [Pruebas](https://docs.stripe.com/testing.md) para obtener información adicional para probar tu integración.
## Optional: Habilita métodos de pago adicionales
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 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 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.
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`.
## 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.
```curl
curl https://api.stripe.com/v1/payment_intents \
-u "<>:" \
-d amount=10000 \
-d currency=usd \
-d "automatic_payment_methods[enabled]"=true \
-d on_behalf_of="{{CONNECTEDACCOUNT_ID}}" \
-d transfer_group=ORDER100
```
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).
## 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]
Esta integración usa tres objetos de la API de Stripe:
1. Un [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. Un objeto *Customer* (Customer objects represent customers of your business. They let you reuse payment methods and give you the ability to track multiple payments)(opcional). Para configurar un método de pago para pagos futuros, tienes que asociarlo a un objeto Customer. Crea el “Customer Object” cuando tu cliente cree una cuenta en tu empresa. Si tu cliente hace un pago como invitado, puedes crear un “Customer Object” antes del pago y asociarlo con tu propia representación interna de la cuenta del cliente más adelante.
1. Una Ephemeral Key del objeto Customer (opcional). La información que contiene el “Customer Object” es confidencial y no se puede recuperar directamente desde una aplicación. La clave efímera le otorga al SDK acceso temporal al objeto Customer.
Si quieres guardar tarjetas y permitir que los clientes frecuentes vuelvan a utilizarlas, necesitas los objetos Customer y Customer Ephemeral Key para tu integración. De lo contrario, puedes omitir estos objetos.
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:
1. Recupera el objeto Customer o crea uno nuevo.
1. Crea una Ephemeral Key para el objeto 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), el [cliente](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-customer) y un [grupo de transferencias](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-transfer_group) para asociar con el envío de fondos más adelante.
1. Devuelve a tu aplicación el *secreto de cliente* (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 Payment Intent, el valor `secret` de la clave efímera, el [ID del cliente](https://docs.stripe.com/api/customers/object.md#customer_object-id) y tu [clave publicable](https://dashboard.stripe.com/apikeys).
Los métodos de pago que se muestran a los clientes durante el proceso de finalización 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](https://dashboard.stripe.com/settings/payment_methods) o puedes enumerarlos manualmente.
A menos que tu integración requiera una opción basada en código para ofrecer métodos de pago, no los enumeres manualmente. 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. Stripe prioriza los métodos de pago que aumentan la conversión y guardan mayor relación con la moneda y ubicación del cliente. Ocultamos los métodos de pago de prioridad más baja en un menú de contenido adicional.
#### Gestionar los métodos de pago desde el Dashboard
Puedes bifurcar y ejecutar una implementación de este punto de conexión en [CodeSandbox](https://codesandbox.io/p/devbox/suspicious-lalande-l325w6) para realizar pruebas.
#### 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"
# Create an Ephemeral Key for the Customer
curl https://api.stripe.com/v1/ephemeral_keys \
-u <>: \
-H "Stripe-Version: 2026-02-25.clover" \
-X "POST" \
-d "customer"="{{CUSTOMER_ID}}" \
# Create a PaymentIntent
curl https://api.stripe.com/v1/payment_intents \
-u <>: \
-X "POST" \
-d "customer"="{{CUSTOMER_ID}}" \
-d "amount"=10000 \
-d "currency"="usd" \
# In the latest version of the API, specifying the `automatic_payment_methods` parameter
# is optional because Stripe enables its functionality by default.
-d "automatic_payment_methods[enabled]"=true \
-d transfer_group="ORDER100" \
```
#### Cómo enumerar métodos de pago manualmente
Puedes bifurcar y ejecutar una implementación de este punto de conexión en [CodeSandbox](https://codesandbox.io/p/devbox/suspicious-lalande-l325w6) para realizar pruebas.
#### 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"
# Create an Ephemeral Key for the Customer
curl https://api.stripe.com/v1/ephemeral_keys \
-u <>: \
-H "Stripe-Version: 2026-02-25.clover" \
-X "POST" \
-d "customer"="{{CUSTOMER_ID}}" \
# Create a PaymentIntent
curl https://api.stripe.com/v1/payment_intents \
-u <>: \
-X "POST" \
-d "customer"="{{CUSTOMER_ID}}" \
-d "amount"=10000 \
-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 transfer_group="ORDER100" \
```
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, asegúrate de:
- 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
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
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 backend endpoint/payment-sheet")! // Your backend 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 backend endpoint/payment-sheet")! // Your backend endpoint
@Published var paymentSheet: PaymentSheet?
@Published var paymentResult: PaymentSheetResult?
func preparePaymentSheet() {
// MARK: Fetch thePaymentIntent and Customer information from the backend
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 backend endpoint/payment-sheet")! // Your backend endpoint
@Published var paymentSheet: PaymentSheet?
@Published var paymentResult: PaymentSheetResult?
func preparePaymentSheet() {
// MARK: Fetch the PaymentIntent and Customer information from the backend
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 usuario (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. |
## Crear un envío de fondos [Lado del servidor]
En tu servidor, envía fondos desde tu cuenta a una cuenta conectada creando un [envío de fondos](https://docs.stripe.com/api/transfers/create.md) y especificando el `transfer_group` utilizado.
```curl
curl https://api.stripe.com/v1/transfers \
-u "<>:" \
-d amount=7000 \
-d currency=usd \
-d destination="{{CONNECTEDACCOUNT_ID}}" \
-d transfer_group=ORDER100
```
Los importes de transferencia y cargo no tienen que coincidir. Puedes dividir un solo cargo entre varias transferencias o incluir varios cargos en una sola transferencia. En el siguiente ejemplo se crea una transferencia adicional asociada con el mismo `transfer_group`.
```curl
curl https://api.stripe.com/v1/transfers \
-u "<>:" \
-d amount=2000 \
-d currency=usd \
-d destination={{OTHER_CONNECTED_ACCOUNT_ID}} \
-d transfer_group=ORDER100
```
### Opciones de envíos de fondo
Puedes asignar cualquier valor a la cadena `transfer_group`, pero debes representar una sola acción comercial. También puedes realizar una transferencia sin un cargo asociado ni un `transfer_group`, por ejemplo, cuando debes pagar a un proveedor pero no hay un pago de cliente asociado.
> El `transfer_group` solo identifica los objetos asociados. No afecta a ninguna funcionalidad estándar. Para evitar que se ejecute una transferencia antes de que estén disponibles los fondos del cargo asociado, usa el atributo `source_transaction` de la transferencia.
De forma predeterminada, una solicitud de envío de fondos falla cuando el monto excede el [saldo disponible de la cuenta](https://docs.stripe.com/connect/account-balances.md) de la plataforma Stripe no reintenta automáticamente las solicitudes de envío de fondos fallidas.
Puedes evitar que se produzcan errores en las solicitudes de envío de fondos asociados a cargos. Cuando especificas el cargo asociado [como source_transaction del envío de fondos](https://docs.stripe.com/connect/separate-charges-and-transfers.md#transfer-availability), la solicitud de envío de fondos se efectúa automáticamente. Sin embargo, no ejecutamos dicho envío hasta que los fondos de ese cargo estén disponibles en la cuenta de la plataforma.
> Si utilizas cargos y envíos de fondos separados, tenlo en cuenta al planificar tu calendario de *transferencias* (A payout is the transfer of funds to an external account, usually a bank account, in the form of a deposit). Las transferencias automáticas pueden interferir con las transferencias que no tienen una `source_transaction` definida.
### Métodos de pago asincrónicos
Si usas *métodos de pago asincrónicos* (Asynchronous payment methods can take up to several days to confirm whether the payment has been successful. During this time, the payment can't be guaranteed) (como débito ACH o débito SEPA), espera a que se produzca un evento [charge.succeeded](https://docs.stripe.com/api/events/types.md#event_types-charge.succeeded) antes de crear una transferencia. A diferencia de los cargos a un destino, Stripe no revierte automáticamente una transferencia si falla el pago asincrónico asociado. Si creas una transferencia y luego falla el pago, el saldo de tu plataforma se debita por el importe de la transferencia. Luego, debes [revertir la transferencia](https://docs.stripe.com/connect/separate-charges-and-transfers.md#reverse-transfers) de forma manual para recuperar los fondos.
## 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 usa `ApplePayContext` para cobrar el pago desde el botón de Apple Pay. 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.
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
Customize colors, fonts, and so on to match the look and feel of your app by using the [appearance API](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.
#### 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.
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 usuario (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: Habilita métodos de pago adicionales
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 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 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.
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`.
## 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.
```curl
curl https://api.stripe.com/v1/payment_intents \
-u "<>:" \
-d amount=10000 \
-d currency=usd \
-d "automatic_payment_methods[enabled]"=true \
-d on_behalf_of="{{CONNECTEDACCOUNT_ID}}" \
-d transfer_group=ORDER100
```
Integra la interfaz de usuario de pago prediseñada de Stripe a la confirmación de compra de tu aplicación Android con la clase [PaymentSheet](https://stripe.dev/stripe-android/paymentsheet/com.stripe.android.paymentsheet/-payment-sheet/index.html).
## 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 las 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 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 `stripe-android` 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 {
// ...
// Stripe Android SDK
implementation("com.stripe:stripe-android:23.0.2")
// Include the financial connections SDK to support US bank account as a payment method
implementation("com.stripe:financial-connections:23.0.2")
}
```
> 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).
Configura el SDK con tu [clave publicable](https://dashboard.stripe.com/apikeys) de Stripe para que pueda hacer solicitudes a la API de Stripe, así como en tu subclase `Application`:
#### Kotlin
```kotlin
import com.stripe.android.PaymentConfiguration
class MyApp : Application() {
override fun onCreate() {
super.onCreate()
PaymentConfiguration.init(
applicationContext,
"<>"
)
}
}
```
> 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]
Esta integración usa tres objetos de la API de Stripe:
1. Un [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. Un objeto *Customer* (Customer objects represent customers of your business. They let you reuse payment methods and give you the ability to track multiple payments)(opcional). Para configurar un método de pago para pagos futuros, tienes que asociarlo a un objeto Customer. Crea el “Customer Object” cuando tu cliente cree una cuenta en tu empresa. Si tu cliente hace un pago como invitado, puedes crear un “Customer Object” antes del pago y asociarlo con tu propia representación interna de la cuenta del cliente más adelante.
1. Una Ephemeral Key del objeto Customer (opcional). La información que contiene el “Customer Object” es confidencial y no se puede recuperar directamente desde una aplicación. La clave efímera le otorga al SDK acceso temporal al objeto Customer.
Si quieres guardar tarjetas y permitir que los clientes frecuentes vuelvan a utilizarlas, necesitas los objetos Customer y Customer Ephemeral Key para tu integración. De lo contrario, puedes omitir estos objetos.
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:
1. Recupera el objeto Customer o crea uno nuevo.
1. Crea una Ephemeral Key para el objeto 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), el [cliente](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-customer) y un [grupo de transferencias](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-transfer_group) para asociar con el envío de fondos más adelante.
1. Devuelve a tu aplicación el *secreto de cliente* (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 Payment Intent, el valor `secret` de la clave efímera, el [ID del cliente](https://docs.stripe.com/api/customers/object.md#customer_object-id) y tu [clave publicable](https://dashboard.stripe.com/apikeys).
Los métodos de pago que se muestran a los clientes durante el proceso de finalización 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](https://dashboard.stripe.com/settings/payment_methods) o puedes enumerarlos manualmente.
A menos que tu integración requiera una opción basada en código para ofrecer métodos de pago, no los enumeres manualmente. 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. Stripe prioriza los métodos de pago que aumentan la conversión y guardan mayor relación con la moneda y ubicación del cliente. Ocultamos los métodos de pago de prioridad más baja en un menú de contenido adicional.
#### Gestionar los métodos de pago desde el Dashboard
Puedes bifurcar y ejecutar una implementación de este punto de conexión en [CodeSandbox](https://codesandbox.io/p/devbox/suspicious-lalande-l325w6) para realizar pruebas.
#### 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"
# Create an Ephemeral Key for the Customer
curl https://api.stripe.com/v1/ephemeral_keys \
-u <>: \
-H "Stripe-Version: 2026-02-25.clover" \
-X "POST" \
-d "customer"="{{CUSTOMER_ID}}" \
# Create a PaymentIntent
curl https://api.stripe.com/v1/payment_intents \
-u <>: \
-X "POST" \
-d "customer"="{{CUSTOMER_ID}}" \
-d "amount"=10000 \
-d "currency"="usd" \
# In the latest version of the API, specifying the `automatic_payment_methods` parameter
# is optional because Stripe enables its functionality by default.
-d "automatic_payment_methods[enabled]"=true \
-d transfer_group="ORDER100" \
```
#### Cómo enumerar métodos de pago manualmente
Puedes bifurcar y ejecutar una implementación de este punto de conexión en [CodeSandbox](https://codesandbox.io/p/devbox/suspicious-lalande-l325w6) para realizar pruebas.
#### 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"
# Create an Ephemeral Key for the Customer
curl https://api.stripe.com/v1/ephemeral_keys \
-u <>: \
-H "Stripe-Version: 2026-02-25.clover" \
-X "POST" \
-d "customer"="{{CUSTOMER_ID}}" \
# Create a PaymentIntent
curl https://api.stripe.com/v1/payment_intents \
-u <>: \
-X "POST" \
-d "customer"="{{CUSTOMER_ID}}" \
-d "amount"=10000 \
-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 transfer_group="ORDER100" \
```
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]
Antes de mostrar el Payment Element móvil, tu página de finalización de compra debe cumplir con los siguientes requisitos:
- Mostrar los productos de la compra y el importe total
- Recopilar cualquier dato de envío requerido usando el [Address Element](https://docs.stripe.com/elements/address-element.md?platform=android)
- Incluye un botón de confirmación de compra para presentar la interfaz de usuario de Stripe
#### Jetpack Compose
[Inicializa](https://stripe.dev/stripe-android/paymentsheet/com.stripe.android.paymentsheet/-payment-sheet/-builder/index.html) una instancia de `PaymentSheet` dentro de `onCreate` de tu actividad de finalización de compra, especificando un método para administrar el resultado.
```kotlin
import androidx.compose.runtime.Composable
import androidx.compose.runtime.remember
import com.stripe.android.paymentsheet.PaymentSheet
import com.stripe.android.paymentsheet.PaymentSheetResult
@Composable
fun App() {
val paymentSheet = remember { PaymentSheet.Builder(::onPaymentSheetResult) }.build()
}
private fun onPaymentSheetResult(paymentSheetResult: PaymentSheetResult) {
// implemented in the next steps
}
```
A continuación, alcanza el secreto de cliente del PaymentIntent, el secreto de cliente de la sesión de este, el ID del cliente y la clave publicable del punto de conexión que creaste en el paso anterior. Define tu clave publicable usando `PaymentConfiguration` y guarda las otras para usarlas cuando presentes la PaymentSheet.
```kotlin
import androidx.compose.runtime.Composable
import androidx.compose.runtime.rememberimport androidx.compose.runtime.LaunchedEffect
import androidx.compose.runtime.getValue
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.setValue
import androidx.compose.ui.platform.LocalContext
import com.stripe.android.PaymentConfiguration
import com.stripe.android.paymentsheet.PaymentSheet
import com.stripe.android.paymentsheet.PaymentSheetResult
@Composable
fun App() {
val paymentSheet = remember { PaymentSheet.Builder(::onPaymentSheetResult) }.build()val context = LocalContext.current
var customerConfig by remember { mutableStateOf(null) }
varpaymentIntentClientSecret by remember { mutableStateOf(null) }
LaunchedEffect(context) {
// Make a request to your own server and retrieve payment configurations
val networkResult = ...
if (networkResult.isSuccess) {paymentIntentClientSecret = networkResult.paymentIntent
customerConfig = PaymentSheet.CustomerConfiguration.createWithCustomerSession(
id = networkResult.customer,
clientSecret = networkResult.customerSessionClientSecret
)PaymentConfiguration.init(context, networkResult.publishableKey)}
}
}
private fun onPaymentSheetResult(paymentSheetResult: PaymentSheetResult) {
// implemented in the next steps
}
```
Cuando el cliente toca tu botón de confirmación de compra, llama a [presentWithPaymentIntent](https://stripe.dev/stripe-android/paymentsheet/com.stripe.android.paymentsheet/-payment-sheet/index.html#1814490530%2FFunctions%2F2002900378) para presentar la hoja de pago. Una vez que el cliente completa el pago, la hoja se cierra y se llama al [PaymentSheetResultCallback](https://stripe.dev/stripe-android/paymentsheet/com.stripe.android.paymentsheet/-payment-sheet-result-callback/index.html) con un [PaymentSheetResult](https://stripe.dev/stripe-android/paymentsheet/com.stripe.android.paymentsheet/-payment-sheet-result/index.html).
```kotlin
import androidx.compose.material.Button
import androidx.compose.material.Text
import androidx.compose.runtime.Composable
import androidx.compose.runtime.LaunchedEffect
import androidx.compose.runtime.getValue
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.runtime.setValue
import androidx.compose.ui.platform.LocalContext
import com.stripe.android.PaymentConfiguration
import com.stripe.android.paymentsheet.PaymentSheet
import com.stripe.android.paymentsheet.PaymentSheetResult
@Composable
fun App() {
val paymentSheet = remember { PaymentSheet.Builder(::onPaymentSheetResult) }.build()
val context = LocalContext.current
var customerConfig by remember { mutableStateOf(null) }
var paymentIntentClientSecret by remember { mutableStateOf(null) }
LaunchedEffect(context) {
// Make a request to your own server and retrieve payment configurations
val networkResult = ...
if (networkResult.isSuccess) {
paymentIntentClientSecret = networkResult.paymentIntent
customerConfig = PaymentSheet.CustomerConfiguration.createWithCustomerSession(
id = networkResult.customer,
clientSecret = networkResult.customerSessionClientSecret
)
PaymentConfiguration.init(context, networkResult.publishableKey)
}
}Button(
onClick = {
val currentConfig = customerConfig
val currentClientSecret =paymentIntentClientSecret
if (currentConfig != null && currentClientSecret != null) {
presentPaymentSheet(paymentSheet, currentConfig, currentClientSecret)
}
}
) {
Text("Checkout")
}
}private fun presentPaymentSheet(
paymentSheet: PaymentSheet,
customerConfig: PaymentSheet.CustomerConfiguration,paymentIntentClientSecret: String
) {
paymentSheet.presentWithPaymentIntent(paymentIntentClientSecret,
PaymentSheet.Configuration.Builder(merchantDisplayName = "My merchant name")
.customer(customerConfig)
// Set `allowsDelayedPaymentMethods` to true if your business handles
// delayed notification payment methods like US bank accounts.
.allowsDelayedPaymentMethods(true)
.build()
)
}
private fun onPaymentSheetResult(paymentSheetResult: PaymentSheetResult) {when(paymentSheetResult) {
is PaymentSheetResult.Canceled -> {
print("Canceled")
}
is PaymentSheetResult.Failed -> {
print("Error: ${paymentSheetResult.error}")
}
is PaymentSheetResult.Completed -> {
// Display for example, an order confirmation screen
print("Completed")
}
}
}
```
#### Vistas (clásicas)
[Inicializa](https://stripe.dev/stripe-android/paymentsheet/com.stripe.android.paymentsheet/-payment-sheet/index.html#-394860221%2FConstructors%2F2002900378) una instancia de `PaymentSheet` dentro de `onCreate` de tu actividad de finalización de compra y especifica un método para administrar el resultado.
#### Kotlin
```kotlin
import com.stripe.android.paymentsheet.PaymentSheet
class CheckoutActivity : AppCompatActivity() {
lateinit var paymentSheet: PaymentSheet
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
paymentSheet = PaymentSheet.Builder(::onPaymentSheetResult).build(this)
}
fun onPaymentSheetResult(paymentSheetResult: PaymentSheetResult) {
// implemented in the next steps
}
}
```
A continuación, alcanza el secreto de cliente del PaymentIntent, el secreto de cliente de la sesión de este, el ID del cliente y la clave publicable del punto de conexión que creaste en el paso anterior. Define tu clave publicable usando `PaymentConfiguration` y guarda las otras para usarlas cuando presentes la PaymentSheet.
#### Kotlin
```kotlin
import com.stripe.android.paymentsheet.PaymentSheet
class CheckoutActivity : AppCompatActivity() {
lateinit var paymentSheet: PaymentSheetlateinit var customerConfig: PaymentSheet.CustomerConfiguration
lateinit varpaymentIntentClientSecret: String
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
paymentSheet = PaymentSheet.Builder(::onPaymentSheetResult).build(this)lifecycleScope.launch {
// Make a request to your own server and retrieve payment configurations
val networkResult = MyBackend.getPaymentConfig()
if (networkResult.isSuccess) {paymentIntentClientSecret = networkResult.paymentIntent
customerConfig = PaymentSheet.CustomerConfiguration.createWithCustomerSession(
id = networkResult.customer,
clientSecret = networkResult.customerSessionClientSecret
)PaymentConfiguration.init(context, networkResult.publishableKey)}
}
}
fun onPaymentSheetResult(paymentSheetResult: PaymentSheetResult) {
// implemented in the next steps
}
}
```
Cuando el cliente toca tu botón de confirmación de compra, llama a [presentWithPaymentIntent](https://stripe.dev/stripe-android/paymentsheet/com.stripe.android.paymentsheet/-payment-sheet/index.html#1814490530%2FFunctions%2F2002900378) para presentar la hoja de pago. Una vez que el cliente completa el pago, la hoja se cierra y se llama al [PaymentSheetResultCallback](https://stripe.dev/stripe-android/paymentsheet/com.stripe.android.paymentsheet/-payment-sheet-result-callback/index.html) con un [PaymentSheetResult](https://stripe.dev/stripe-android/paymentsheet/com.stripe.android.paymentsheet/-payment-sheet-result/index.html).
#### Kotlin
```kotlin
// ...
class CheckoutActivity : AppCompatActivity() {
lateinit var paymentSheet: PaymentSheet
lateinit var customerConfig: PaymentSheet.CustomerConfiguration
lateinit var paymentIntentClientSecret: String
// ...fun presentPaymentSheet() {
paymentSheet.presentWithPaymentIntent(paymentIntentClientSecret,
PaymentSheet.Configuration.Builder(merchantDisplayName = "My merchant name")
.customer(customerConfig)
// Set `allowsDelayedPaymentMethods` to true if your business handles
// delayed notification payment methods like US bank accounts.
.allowsDelayedPaymentMethods(true)
.build()
)
}
fun onPaymentSheetResult(paymentSheetResult: PaymentSheetResult) {when(paymentSheetResult) {
is PaymentSheetResult.Canceled -> {
print("Canceled")
}
is PaymentSheetResult.Failed -> {
print("Error: ${paymentSheetResult.error}")
}
is PaymentSheetResult.Completed -> {
// Display for example, an order confirmation screen
print("Completed")
}
}
}
}
```
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.
## 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. |
## Crear un envío de fondos [Lado del servidor]
En tu servidor, envía fondos desde tu cuenta a una cuenta conectada creando un [envío de fondos](https://docs.stripe.com/api/transfers/create.md) y especificando el `transfer_group` utilizado.
```curl
curl https://api.stripe.com/v1/transfers \
-u "<>:" \
-d amount=7000 \
-d currency=usd \
-d destination="{{CONNECTEDACCOUNT_ID}}" \
-d transfer_group=ORDER100
```
Los importes de transferencia y cargo no tienen que coincidir. Puedes dividir un solo cargo entre varias transferencias o incluir varios cargos en una sola transferencia. En el siguiente ejemplo se crea una transferencia adicional asociada con el mismo `transfer_group`.
```curl
curl https://api.stripe.com/v1/transfers \
-u "<>:" \
-d amount=2000 \
-d currency=usd \
-d destination={{OTHER_CONNECTED_ACCOUNT_ID}} \
-d transfer_group=ORDER100
```
### Opciones de envíos de fondo
Puedes asignar cualquier valor a la cadena `transfer_group`, pero debes representar una sola acción comercial. También puedes realizar una transferencia sin un cargo asociado ni un `transfer_group`, por ejemplo, cuando debes pagar a un proveedor pero no hay un pago de cliente asociado.
> El `transfer_group` solo identifica los objetos asociados. No afecta a ninguna funcionalidad estándar. Para evitar que se ejecute una transferencia antes de que estén disponibles los fondos del cargo asociado, usa el atributo `source_transaction` de la transferencia.
De forma predeterminada, una solicitud de envío de fondos falla cuando el monto excede el [saldo disponible de la cuenta](https://docs.stripe.com/connect/account-balances.md) de la plataforma Stripe no reintenta automáticamente las solicitudes de envío de fondos fallidas.
Puedes evitar que se produzcan errores en las solicitudes de envío de fondos asociados a cargos. Cuando especificas el cargo asociado [como source_transaction del envío de fondos](https://docs.stripe.com/connect/separate-charges-and-transfers.md#transfer-availability), la solicitud de envío de fondos se efectúa automáticamente. Sin embargo, no ejecutamos dicho envío hasta que los fondos de ese cargo estén disponibles en la cuenta de la plataforma.
> Si utilizas cargos y envíos de fondos separados, tenlo en cuenta al planificar tu calendario de *transferencias* (A payout is the transfer of funds to an external account, usually a bank account, in the form of a deposit). Las transferencias automáticas pueden interferir con las transferencias que no tienen una `source_transaction` definida.
### Métodos de pago asincrónicos
Si usas *métodos de pago asincrónicos* (Asynchronous payment methods can take up to several days to confirm whether the payment has been successful. During this time, the payment can't be guaranteed) (como débito ACH o débito SEPA), espera a que se produzca un evento [charge.succeeded](https://docs.stripe.com/api/events/types.md#event_types-charge.succeeded) antes de crear una transferencia. A diferencia de los cargos a un destino, Stripe no revierte automáticamente una transferencia si falla el pago asincrónico asociado. Si creas una transferencia y luego falla el pago, el saldo de tu plataforma se debita por el importe de la transferencia. Luego, debes [revertir la transferencia](https://docs.stripe.com/connect/separate-charges-and-transfers.md#reverse-transfers) de forma manual para recuperar los fondos.
## 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.
## Optional: Activar Google Pay
### Configura tu integración
Para usar Google Pay, primero habilita la API de Google Pay agregando lo siguiente a la etiqueta `` de tu **AndroidManifest.xml**:
```xml
...
```
Para obtener más detalles, consulta cómo [configurar la API de Google Pay](https://developers.google.com/pay/api/android/guides/setup) para Android en Google Pay.
### Agregar Google Pay
Para agregar Google Pay a tu integración, especifica un [PaymentSheet.GooglePayConfiguration](https://stripe.dev/stripe-android/paymentsheet/com.stripe.android.paymentsheet/-payment-sheet/-google-pay-configuration/index.html) con tu entorno de Google Pay (de producción o de prueba) y el [código de país de tu empresa](https://dashboard.stripe.com/settings/account) al inicializar [PaymentSheet.Configuration](https://stripe.dev/stripe-android/paymentsheet/com.stripe.android.paymentsheet/-payment-sheet/-configuration/index.html).
#### Kotlin
```kotlin
val googlePayConfiguration = PaymentSheet.GooglePayConfiguration(
environment = PaymentSheet.GooglePayConfiguration.Environment.Test,
countryCode = "US",
currencyCode = "USD" // Required for Setup Intents, optional for Payment Intents
)
val configuration = PaymentSheet.Configuration.Builder(merchantDisplayName = "My merchant name")
.googlePay(googlePayConfiguration)
.build()
```
### Prueba Google Pay
Google te permite realizar pagos de prueba a través de su tarjeta [Test card suite](https://developers.google.com/pay/api/android/guides/resources/test-card-suite). El conjunto de pruebas admite el uso de [tarjetas de prueba](https://docs.stripe.com/testing.md) de Stripe.
Debes probar Google Pay usando un dispositivo Android físico en lugar de un dispositivo simulado, en un país donde se admite Google Pay. Inicia sesión en una cuenta Google en tu dispositivo de prueba con una tarjeta real guardada en Google Wallet.
## Optional: Personalizar la hoja
Todo lo que se quiera personalizar se configura usando el objeto [PaymentSheet.Configuration](https://stripe.dev/stripe-android/paymentsheet/com.stripe.android.paymentsheet/-payment-sheet/-configuration/index.html).
### Appearance
Customize colors, fonts, and more to match the look and feel of your app by using the [appearance API](https://docs.stripe.com/elements/appearance-api/mobile.md?platform=android).
### Diseño del método de pago
Configura el diseño de los métodos de pago en la hoja con [paymentMethodLayout](https://stripe.dev/stripe-android/paymentsheet/com.stripe.android.paymentsheet/-payment-sheet/-configuration/-builder/index.html#2123253356%2FFunctions%2F2002900378). Puedes mostrarlos horizontalmente, verticalmente o dejar que Stripe optimice el diseño de manera automática.
#### Kotlin
```kotlin
PaymentSheet.Configuration.Builder("Example, Inc.")
.paymentMethodLayout(PaymentSheet.PaymentMethodLayout.Automatic)
.build()
```
### 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=android).
### Nombre con el que aparecerá la empresa
Especifica el nombre que quieres que el cliente vea para tu empresa configurando [merchantDisplayName](https://stripe.dev/stripe-android/paymentsheet/com.stripe.android.paymentsheet/-payment-sheet/-configuration/index.html#-191101533%2FProperties%2F2002900378). De manera predeterminada, este es el nombre de tu aplicación.
#### Kotlin
```kotlin
PaymentSheet.Configuration.Builder(
merchantDisplayName = "My app, Inc."
).build()
```
### Modo oscuro
De forma predeterminada, `PaymentSheet` se adapta automáticamente a la configuración de aspecto de todo el sistema del usuario (modo claro y modo oscuro). Puedes cambiarla definiendo modo claro o modo oscuro en tu aplicación:
#### Kotlin
```kotlin
// force dark
AppCompatDelegate.setDefaultNightMode(AppCompatDelegate.MODE_NIGHT_YES)
// force light
AppCompatDelegate.setDefaultNightMode(AppCompatDelegate.MODE_NIGHT_NO)
```
### 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.
#### Kotlin
```kotlin
val address = PaymentSheet.Address(country = "US")
val billingDetails = PaymentSheet.BillingDetails(
address = address,
email = "foo@bar.com"
)
val configuration = PaymentSheet.Configuration.Builder(merchantDisplayName = "Merchant, Inc.")
.defaultBillingDetails(billingDetails)
.build()
```
### Configura la recopilación de datos de facturación
Usa `BillingDetailsCollectionConfiguration` para especificar cómo deseas recopilar los datos de facturación en la PaymentSheet.
Puedes recopilar el nombre, el correo electrónico, el número de teléfono y la dirección del cliente.
Si quieres adjuntar datos de facturación predeterminados al objeto PaymentMethod aun cuando esos campos no se hayan recopilado en la interfaz de usuario, establece `billingDetailsCollectionConfiguration.attachDefaultsToPaymentMethod` en `true`.
#### Kotlin
```kotlin
val billingDetails = PaymentSheet.BillingDetails(
email = "foo@bar.com"
)
val billingDetailsCollectionConfiguration = BillingDetailsCollectionConfiguration(
attachDefaultsToPaymentMethod = true,
name = BillingDetailsCollectionConfiguration.CollectionMode.Always,
email = BillingDetailsCollectionConfiguration.CollectionMode.Never,
address = BillingDetailsCollectionConfiguration.AddressCollectionMode.Full,
)
val configuration = PaymentSheet.Configuration.Builder(merchantDisplayName = "Merchant, Inc.")
.defaultBillingDetails(billingDetails)
.billingDetailsCollectionConfiguration(billingDetailsCollectionConfiguration)
.build()
```
> 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 una hoja de pago para recopilar solo los datos del método de pago y 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.
> Una integración de ejemplo está [disponible en nuestro GitHub](https://github.com/stripe/stripe-android/blob/master/paymentsheet-example/src/main/java/com/stripe/android/paymentsheet/example/samples/ui/paymentsheet/custom_flow/CustomFlowActivity.kt).
1. Primero, inicializa [PaymentSheet.FlowController](https://stripe.dev/stripe-android/paymentsheet/com.stripe.android.paymentsheet/-payment-sheet/-flow-controller/index.html) en lugar de `PaymentSheet` usando uno de los métodos [Builder](https://stripe.dev/stripe-android/paymentsheet/com.stripe.android.paymentsheet/-payment-sheet/-flow-controller/-builder/index.html).
#### Android (Kotlin)
```kotlin
class CheckoutActivity : AppCompatActivity() {
private lateinit var flowController: PaymentSheet.FlowController
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
val flowController = PaymentSheet.FlowController.Builder(
resultCallback = ::onPaymentSheetResult,
paymentOptionResultCallback = ::onPaymentOption,
).build(this)
}
}
```
1. A continuación, llama a `configureWithPaymentIntent` con las claves de objeto de Stripe recuperadas del backend y actualiza tu interfaz de usuario en la devolución de llamada usando [getPaymentOption()](https://stripe.dev/stripe-android/paymentsheet/com.stripe.android.paymentsheet/-payment-sheet/-flow-controller/index.html#-2091462043%2FFunctions%2F2002900378). Contiene una imagen y una etiqueta que representan el método de pago seleccionado actualmente por el cliente.
#### Android (Kotlin)
```kotlin
flowController.configureWithPaymentIntent(
paymentIntentClientSecret = paymentIntentClientSecret,
configuration = PaymentSheet.Configuration.Builder("Example, Inc.")
.customer(PaymentSheet.CustomerConfiguration(
id = customerId,
ephemeralKeySecret = ephemeralKeySecret
))
.build()
) { isReady, error ->
if (isReady) {
// Update your UI using `flowController.getPaymentOption()`
} else {
// handle FlowController configuration failure
}
}
```
1. A continuación, llama a [presentPaymentOptions](https://stripe.dev/stripe-android/paymentsheet/com.stripe.android.paymentsheet/-payment-sheet/-flow-controller/index.html#449924733%2FFunctions%2F2002900378) para recopilar los datos del pago. Cuando el cliente termina, la hoja se cierra y llama al [paymentResultCallback](https://stripe.dev/stripe-android/paymentsheet/com.stripe.android.paymentsheet/-payment-option-callback/index.html) especificado anteriormente en `create`. Implementa este método para actualizar tu interfaz de usuario con la `paymentOption` devuelta.
#### Android (Kotlin)
```kotlin
// ...
flowController.presentPaymentOptions()
// ...
private fun onPaymentOption(paymentOptionResult: PaymentOptionResult) {
val paymentOption = paymentOptionResult.paymentOption
if (paymentOption != null) {
paymentMethodButton.text = paymentOption.label
paymentMethodButton.setCompoundDrawablesRelativeWithIntrinsicBounds(
paymentOption.drawableResourceId,
0,
0,
0
)
} else {
paymentMethodButton.text = "Select"
paymentMethodButton.setCompoundDrawablesRelativeWithIntrinsicBounds(
null,
null,
null,
null
)
}
}
```
1. Finalmente, llama a [confirm](https://stripe.dev/stripe-android/paymentsheet/com.stripe.android.paymentsheet/-payment-sheet/-flow-controller/index.html#-479056656%2FFunctions%2F2002900378) para completar el pago. Cuando el cliente termina, la hoja se cierra y llama al [paymentResultCallback](https://stripe.dev/stripe-android/paymentsheet/com.stripe.android.paymentsheet/-payment-sheet-result-callback/index.html#237248767%2FFunctions%2F2002900378) especificado anteriormente en `create`.
#### Android (Kotlin)
```kotlin
// ...
flowController.confirmPayment()
// ...
private fun onPaymentSheetResult(
paymentSheetResult: PaymentSheetResult
) {
when (paymentSheetResult) {
is PaymentSheetResult.Canceled -> {
// Payment canceled
}
is PaymentSheetResult.Failed -> {
// Payment Failed. See logcat for details or inspect paymentSheetResult.error
}
is PaymentSheetResult.Completed -> {
// Payment Complete
}
}
}
```
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: Habilita métodos de pago adicionales
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 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 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.
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`.
## 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.
```curl
curl https://api.stripe.com/v1/payment_intents \
-u "<>:" \
-d amount=10000 \
-d currency=usd \
-d "automatic_payment_methods[enabled]"=true \
-d on_behalf_of="{{CONNECTEDACCOUNT_ID}}" \
-d transfer_group=ORDER100
```
Esta integración combina todos los pasos necesarios para realizar el pago, incluida la recopilación de los datos de pago y la confirmación del pago, en una única hoja que se muestra en la parte superior de tu aplicación.
## 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 las 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 React Native](https://github.com/stripe/stripe-react-native) es de código abierto y está plenamente documentado. Internamente, utiliza SDK para [iOS nativo](https://github.com/stripe/stripe-ios) y [Android](https://github.com/stripe/stripe-android). Para instalar el SDK para React Native de Stripe, ejecuta uno de los siguientes comandos en el directorio del proyecto (según el administrador de paquetes que utilices):
#### hilado
```bash
yarn add @stripe/stripe-react-native
```
#### npm
```bash
npm install @stripe/stripe-react-native
```
A continuación, instala otras dependencias necesarias:
- Para iOS, vaya al directorio **ios** y ejecute `pod install` para asegurarse de que también instala las dependencias nativas necesarias.
- Para Android, no hay más dependencias para instalar.
> Recomendamos seguir la [guía oficial de TypeScript](https://reactnative.dev/docs/typescript#adding-typescript-to-an-existing-project) para agregar soporte para TypeScript.
### Inicialización de Stripe
Para inicializar Stripe en tu aplicación React Native, ajusta tu pantalla de pago con el componente `StripeProvider` o usa el método de inicialización `initStripe`. Solo se requiere la [clave publicable](https://docs.stripe.com/keys.md#obtain-api-keys) de la API en `publishableKey`. El siguiente ejemplo muestra cómo inicializar Stripe usando el componente `StripeProvider`.
```jsx
import { useState, useEffect } from 'react';
import { StripeProvider } from '@stripe/stripe-react-native';
function App() {
const [publishableKey, setPublishableKey] = useState('');
const fetchPublishableKey = async () => {
const key = await fetchKey(); // fetch key from your server here
setPublishableKey(key);
};
useEffect(() => {
fetchPublishableKey();
}, []);
return (
{/* Your app code here */}
);
}
```
> Usa las [claves de prueba](https://docs.stripe.com/keys.md#obtain-api-keys) de la API 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]
Esta integración usa tres objetos de la API de Stripe:
1. Un [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. Un objeto *Customer* (Customer objects represent customers of your business. They let you reuse payment methods and give you the ability to track multiple payments)(opcional). Para configurar un método de pago para pagos futuros, tienes que asociarlo a un objeto Customer. Crea el “Customer Object” cuando tu cliente cree una cuenta en tu empresa. Si tu cliente hace un pago como invitado, puedes crear un “Customer Object” antes del pago y asociarlo con tu propia representación interna de la cuenta del cliente más adelante.
1. Una Ephemeral Key del objeto Customer (opcional). La información que contiene el “Customer Object” es confidencial y no se puede recuperar directamente desde una aplicación. La clave efímera le otorga al SDK acceso temporal al objeto Customer.
Si quieres guardar tarjetas y permitir que los clientes frecuentes vuelvan a utilizarlas, necesitas los objetos Customer y Customer Ephemeral Key para tu integración. De lo contrario, puedes omitir estos objetos.
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:
1. Recupera el objeto Customer o crea uno nuevo.
1. Crea una Ephemeral Key para el objeto 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), el [cliente](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-customer) y un [grupo de transferencias](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-transfer_group) para asociar con el envío de fondos más adelante.
1. Devuelve a tu aplicación el *secreto de cliente* (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 Payment Intent, el valor `secret` de la clave efímera, el [ID del cliente](https://docs.stripe.com/api/customers/object.md#customer_object-id) y tu [clave publicable](https://dashboard.stripe.com/apikeys).
Los métodos de pago que se muestran a los clientes durante el proceso de finalización 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](https://dashboard.stripe.com/settings/payment_methods) o puedes enumerarlos manualmente.
A menos que tu integración requiera una opción basada en código para ofrecer métodos de pago, no los enumeres manualmente. 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. Stripe prioriza los métodos de pago que aumentan la conversión y guardan mayor relación con la moneda y ubicación del cliente. Ocultamos los métodos de pago de prioridad más baja en un menú de contenido adicional.
#### Gestionar los métodos de pago desde el Dashboard
Puedes bifurcar y ejecutar una implementación de este punto de conexión en [CodeSandbox](https://codesandbox.io/p/devbox/suspicious-lalande-l325w6) para realizar pruebas.
#### 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"
# Create an Ephemeral Key for the Customer
curl https://api.stripe.com/v1/ephemeral_keys \
-u <>: \
-H "Stripe-Version: 2026-02-25.clover" \
-X "POST" \
-d "customer"="{{CUSTOMER_ID}}" \
# Create a PaymentIntent
curl https://api.stripe.com/v1/payment_intents \
-u <>: \
-X "POST" \
-d "customer"="{{CUSTOMER_ID}}" \
-d "amount"=10000 \
-d "currency"="usd" \
# In the latest version of the API, specifying the `automatic_payment_methods` parameter
# is optional because Stripe enables its functionality by default.
-d "automatic_payment_methods[enabled]"=true \
-d transfer_group="ORDER100" \
```
#### Cómo enumerar métodos de pago manualmente
Puedes bifurcar y ejecutar una implementación de este punto de conexión en [CodeSandbox](https://codesandbox.io/p/devbox/suspicious-lalande-l325w6) para realizar pruebas.
#### 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"
# Create an Ephemeral Key for the Customer
curl https://api.stripe.com/v1/ephemeral_keys \
-u <>: \
-H "Stripe-Version: 2026-02-25.clover" \
-X "POST" \
-d "customer"="{{CUSTOMER_ID}}" \
# Create a PaymentIntent
curl https://api.stripe.com/v1/payment_intents \
-u <>: \
-X "POST" \
-d "customer"="{{CUSTOMER_ID}}" \
-d "amount"=10000 \
-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 transfer_group="ORDER100" \
```
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]
Antes de mostrar el Payment Element móvil, tu página de finalización de compra debe cumplir con los siguientes requisitos:
- Mostrar los productos de la compra y el importe total
- Recopilar la información de envío necesaria
- Incluir un botón de pago para presentar la interfaz de usuario de Stripe
En la finalización de compra de tu aplicación, haz una solicitud de red al punto de conexión de back-end que creaste en el paso anterior y llama a `initPaymentSheet` desde el hook `useStripe`.
```javascript
export default function CheckoutScreen() {
const { initPaymentSheet, presentPaymentSheet } = useStripe();
const [loading, setLoading] = useState(false);
const fetchPaymentSheetParams = async () => {
const response = await fetch(`${API_URL}/payment-sheet`, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
},
});
const { paymentIntent, ephemeralKey, customer } = await response.json();
return {
paymentIntent,
ephemeralKey,
customer,
};
};
const initializePaymentSheet = async () => {
const {
paymentIntent,
ephemeralKey,
customer,
} = await fetchPaymentSheetParams();
const { error } = await initPaymentSheet({
merchantDisplayName: "Example, Inc.",
customerId: customer,
customerEphemeralKeySecret: ephemeralKey,
paymentIntentClientSecret: paymentIntent,
// Set `allowsDelayedPaymentMethods` to true if your business can handle payment
//methods that complete payment after a delay, like SEPA Debit and Sofort.
allowsDelayedPaymentMethods: true,
defaultBillingDetails: {
name: 'Jane Doe',
}
});
if (!error) {
setLoading(true);
}
};
const openPaymentSheet = async () => {
// see below
};
useEffect(() => {
initializePaymentSheet();
}, []);
return (
);
}
```
Cuando el cliente toque el botón **Pagar**, llama a `presentPaymentSheet()` para abrir la hoja. Después de que el cliente completa el pago, la hoja se cierra y la promesa se resuelve con un `StripeError` opcional.
```javascript
export default function CheckoutScreen() {
// continued from above
const openPaymentSheet = async () => {
const { error } = await presentPaymentSheet();
if (error) {
Alert.alert(`Error code: ${error.code}`, error.message);
} else {
Alert.alert('Success', 'Your order is confirmed!');
}
};
return (
);
}
```
Si no se produjo ningún error, infórmale al usuario que el proceso terminó (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 (solo para iOS) [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
}
}
}
}
}
```
Además, debes definir la [returnURL](https://stripe.dev/stripe-ios/stripe-paymentsheet/Classes/PaymentSheet/Configuration.html#/s:6Stripe12PaymentSheetC13ConfigurationV9returnURLSSSgvp) del objeto [PaymentSheet.Configuration](https://stripe.dev/stripe-ios/stripe-paymentsheet/Classes/PaymentSheet/Configuration.html) en la URL de tu aplicación.
```swift
var configuration = PaymentSheet.Configuration()
configuration.returnURL = "your-app://stripe-redirect"
```
## Administrar eventos posteriores al pago
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. |
## Crear un envío de fondos [Lado del servidor]
En tu servidor, envía fondos desde tu cuenta a una cuenta conectada creando un [envío de fondos](https://docs.stripe.com/api/transfers/create.md) y especificando el `transfer_group` utilizado.
```curl
curl https://api.stripe.com/v1/transfers \
-u "<>:" \
-d amount=7000 \
-d currency=usd \
-d destination="{{CONNECTEDACCOUNT_ID}}" \
-d transfer_group=ORDER100
```
Los importes de transferencia y cargo no tienen que coincidir. Puedes dividir un solo cargo entre varias transferencias o incluir varios cargos en una sola transferencia. En el siguiente ejemplo se crea una transferencia adicional asociada con el mismo `transfer_group`.
```curl
curl https://api.stripe.com/v1/transfers \
-u "<>:" \
-d amount=2000 \
-d currency=usd \
-d destination={{OTHER_CONNECTED_ACCOUNT_ID}} \
-d transfer_group=ORDER100
```
### Opciones de envíos de fondo
Puedes asignar cualquier valor a la cadena `transfer_group`, pero debes representar una sola acción comercial. También puedes realizar una transferencia sin un cargo asociado ni un `transfer_group`, por ejemplo, cuando debes pagar a un proveedor pero no hay un pago de cliente asociado.
> El `transfer_group` solo identifica los objetos asociados. No afecta a ninguna funcionalidad estándar. Para evitar que se ejecute una transferencia antes de que estén disponibles los fondos del cargo asociado, usa el atributo `source_transaction` de la transferencia.
De forma predeterminada, una solicitud de envío de fondos falla cuando el monto excede el [saldo disponible de la cuenta](https://docs.stripe.com/connect/account-balances.md) de la plataforma Stripe no reintenta automáticamente las solicitudes de envío de fondos fallidas.
Puedes evitar que se produzcan errores en las solicitudes de envío de fondos asociados a cargos. Cuando especificas el cargo asociado [como source_transaction del envío de fondos](https://docs.stripe.com/connect/separate-charges-and-transfers.md#transfer-availability), la solicitud de envío de fondos se efectúa automáticamente. Sin embargo, no ejecutamos dicho envío hasta que los fondos de ese cargo estén disponibles en la cuenta de la plataforma.
> Si utilizas cargos y envíos de fondos separados, tenlo en cuenta al planificar tu calendario de *transferencias* (A payout is the transfer of funds to an external account, usually a bank account, in the form of a deposit). Las transferencias automáticas pueden interferir con las transferencias que no tienen una `source_transaction` definida.
### Métodos de pago asincrónicos
Si usas *métodos de pago asincrónicos* (Asynchronous payment methods can take up to several days to confirm whether the payment has been successful. During this time, the payment can't be guaranteed) (como débito ACH o débito SEPA), espera a que se produzca un evento [charge.succeeded](https://docs.stripe.com/api/events/types.md#event_types-charge.succeeded) antes de crear una transferencia. A diferencia de los cargos a un destino, Stripe no revierte automáticamente una transferencia si falla el pago asincrónico asociado. Si creas una transferencia y luego falla el pago, el saldo de tu plataforma se debita por el importe de la transferencia. Luego, debes [revertir la transferencia](https://docs.stripe.com/connect/separate-charges-and-transfers.md#reverse-transfers) de forma manual para recuperar los fondos.
## 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 [Lado del cliente]
> Se requiere habilitar el escaneo de tarjetas para el proceso de revisión de aplicaciones iOS de Apple. El escaneo de tarjetas no es necesario para el proceso de revisión de aplicaciones Android, pero recomendamos habilitarlo.
### iOS
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) Android
Para obtener soporte al escanear tarjetas, [solicita el acceso de producción](https://developers.google.com/pay/api/android/guides/test-and-deploy/request-prod-access) a la API de Google Pay desde [Google Pay and Wallet Console](https://pay.google.com/business/console?utm_source=devsite&utm_medium=devsite&utm_campaign=devsite).
- Si habilitaste Google Pay, la funcionalidad para escanear tarjetas está disponible de forma automática en nuestra interfaz de usuario (IU) en los dispositivos compatibles. Para obtener más información sobre los dispositivos compatibles, consulta las [restricciones de la API de Google Pay](https://developers.google.com/pay/payment-card-recognition/debit-credit-card-recognition).
- **Importante:** La funcionalidad para escanear tarjetas solo aparece en compilaciones firmadas con la misma clave de firma registrada en [Google Pay & Wallet Console](https://pay.google.com/business/console). Las compilaciones de prueba o depuración que usen claves de firma diferentes (por ejemplo, compilaciones distribuidas a través de Firebase App Tester) no mostrarán la opción **Escanear tarjeta**. Para probar el escaneo de tarjetas en compilaciones previas al lanzamiento, debes realizar lo siguiente:
- Firma tus compilaciones de prueba con tu clave de firma de producción
- Agrega la huella digital de tu clave de firma de prueba a Google Pay and Wallet Console
## Optional: Habilitar Apple Pay
### 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.
Habilitar la funcionalidad Apple Pay en Xcode
### Agregar Apple Pay
#### Pago único
Especifica tu ID de comerciante al crear `StripeProvider`:
```javascript
import { StripeProvider } from '@stripe/stripe-react-native';
function App() {
return (
{/* Your app code here */}
);
}
```
Cuando accedes a `initPaymentSheet`, ingresa tus [parámetros de Apple Pay](https://stripe.dev/stripe-react-native/api-reference/modules/PaymentSheet.html#ApplePayParams):
```javascript
await initPaymentSheet({
// ...
applePay: {
merchantCountryCode: 'US',
},
});
```
#### Pagos recurrentes
Cuando accedes a `initPaymentSheet`, introduce los [parámetros de Apple Pay](https://stripe.dev/stripe-react-native/api-reference/modules/PaymentSheet.html#ApplePayParams) con `merchantCountryCode` establecido en el código de país de tu empresa.
In accordance with [Apple’s guidelines](https://developer.apple.com/design/human-interface-guidelines/apple-pay#Supporting-subscriptions) for recurring payments, you must also set a `cardItems` that includes a [RecurringCartSummaryItem](https://stripe.dev/stripe-react-native/api-reference/modules/ApplePay.html#RecurringCartSummaryItem) with the amount you intend to charge (for example, “59.95 USD a month”).
También puedes adoptar [tokens de comerciante](https://developer.apple.com/apple-pay/merchant-tokens/) estableciendo la `request` con su `type` establecido en `PaymentRequestType.Recurring`
Para obtener más información sobre cómo usar pagos recurrentes con Apple Pay, consulta la [documentación de PassKit de Apple](https://developer.apple.com/documentation/passkit/pkpaymentrequest).
#### iOS (React Native)
```javascript
const initializePaymentSheet = async () => {
const recurringSummaryItem = {
label: 'My Subscription',
amount: '59.99',
paymentType: 'Recurring',
intervalCount: 1,
intervalUnit: 'month',
// Payment starts today
startDate: new Date().getTime() / 1000,
// Payment ends in one year
endDate: new Date().getTime() / 1000 + 60 * 60 * 24 * 365,
};
const {error} = await initPaymentSheet({
// ...
applePay: {
merchantCountryCode: 'US',
cartItems: [recurringSummaryItem],
request: {
type: PaymentRequestType.Recurring,
description: 'Recurring',
managementUrl: 'https://my-backend.example.com/customer-portal',
billing: recurringSummaryItem,
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.'",
},
},
});
};
```
### 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 una función de de llamada`setOrderTracking`. Stripe llama a tu implementación después de que se complete el pago, pero antes de que iOS descarte la hoja de Apple Pay.
En su implementación de la función de devolución de llamada `setOrderTracking`, obtén los detalles del pedido de tu servidor para el pedido completado y transfiere los datos a la función de `completion` proporcionada.
Para obtener más información sobre el seguimiento de pedidos, consulta la [documentación sobre pedidos de billetera de Apple](https://developer.apple.com/documentation/walletorders).
#### iOS (React Native)
```javascript
await initPaymentSheet({
// ...
applePay: {
// ...
setOrderTracking: async complete => {
const apiEndpoint =
Platform.OS === 'ios'
? 'http://localhost:4242'
: 'http://10.0.2.2:4567';
const response = await fetch(
`${apiEndpoint}/retrieve-order?orderId=${orderId}`,
{
method: 'GET',
headers: {
'Content-Type': 'application/json',
},
},
);
if (response.status === 200) {
const orderDetails = await response.json();
// orderDetails should include orderIdentifier, orderTypeIdentifier,
// authenticationToken and webServiceUrl
complete(orderDetails);
}
},
},
});
```
## Optional: Activar Google Pay
### Configura tu integración
Para usar Google Pay, primero habilita la API de Google Pay agregando lo siguiente a la etiqueta `` de tu **AndroidManifest.xml**:
```xml
...
```
Para obtener más detalles, consulta cómo [configurar la API de Google Pay](https://developers.google.com/pay/api/android/guides/setup) para Android en Google Pay.
### Agregar Google Pay
Al inicializar `PaymentSheet`. establece `merchantCountryCode` en el código de país de tu empresa y establece `googlePay` en verdadero.
También puedes usar el entorno de prueba especificando el parámetro `testEnv`. Solo puedes probar Google Pay en un dispositivo Android físico. Sigue la [documentación de React Native](https://reactnative.dev/docs/running-on-device) para probar tu aplicación en un dispositivo físico.
```javascript
const { error, paymentOption } = await initPaymentSheet({
// ...
googlePay: {
merchantCountryCode: 'US',
testEnv: true, // use test environment
},
});
```
## Optional: Personalizar la hoja
Todo lo que se quiera personalizar se configura usando `initPaymentSheet`.
### Aspecto
Customize colors, fonts, and so on to match the look and feel of your app by using the [appearance API](https://docs.stripe.com/elements/appearance-api/mobile.md?platform=react-native).
### Nombre de pantalla para el comerciante
Especifica el nombre que quieres que el cliente vea para tu empresa configurando `merchantDisplayName`. El valor predeterminado es el nombre de tu aplicación.
```javascript
await initPaymentSheet({
// ...
merchantDisplayName: 'Example Inc.',
});
```
### Modo oscuro
De forma predeterminada, `PaymentSheet` se adapta automáticamente a la configuración de aspecto de todo el sistema del usuario (modo claro y modo oscuro). Puedes cambiarla definiendo la propiedad `style` en `alwaysLight` o `alwaysDark` en iOS.
```javascript
await initPaymentSheet({
// ...
style: 'alwaysDark',
});
```
En Android, debes definir modo claro u oscuro en tu aplicación:
```
// force dark
AppCompatDelegate.setDefaultNightMode(AppCompatDelegate.MODE_NIGHT_YES)
// force light
AppCompatDelegate.setDefaultNightMode(AppCompatDelegate.MODE_NIGHT_NO)
```
### Datos de facturación predeterminados
Para establecer los valores predeterminados para los datos de facturación recopilados en PaymentSheet, configura la propiedad `defaultBillingDetails`. Los campos de `PaymentSheet` se completan automáticamente con los valores que proporcionas.
```javascript
await initPaymentSheet({
// ...
defaultBillingDetails: {
email: 'foo@bar.com',
address: {
country: 'US',
},
},
});
```
### Recopila datos de facturación
Usa`billingDetailsCollectionConfiguration` para especificar cómo deseas recopilar los datos de facturación en PaymentSheet.
Puedes recopilar el nombre, el correo electrónico, el número de teléfono y la dirección del cliente.
Si no tienes intención de recopilar los valores que exige el método de pago, debes hacer lo siguiente:
1. Adjunta los valores no recopilados por `PaymentSheet` a la propiedad `defaultBillingDetails`.
1. Configura `billingDetailsCollectionConfiguration.attachDefaultsToPaymentMethod` en `true`.
```javascript
await initPaymentSheet({
// ...
defaultBillingDetails: {
email: 'foo@bar.com',
},
billingDetailsCollectionConfiguration: {
name: PaymentSheet.CollectionMode.ALWAYS,
email: PaymentSheet.CollectionMode.NEVER,
address: PaymentSheet.AddressCollectionMode.FULL,
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 una 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.
> Un ejemplo de integración [está a tu disposición en nuestro GitHub](https://github.com/stripe/stripe-react-native/blob/master/example/src/screens/PaymentsUICustomScreen.tsx).
1. Primero, llama a `initPaymentSheet` y especifica `customFlow: true`. `initPaymentSheet` se resuelve con una opción de pago inicial que contiene una imagen y una etiqueta que representan el método de pago del cliente. Actualiza tu interfaz de usuario con estos datos.
```javascript
const {
initPaymentSheet,
presentPaymentSheet,
confirmPaymentSheetPayment,
} = useStripe()
const { error, paymentOption } = await initPaymentSheet({
customerId: customer,
customerEphemeralKeySecret: ephemeralKey,
paymentIntentClientSecret: paymentIntent,
customFlow: true,
merchantDisplayName: 'Example Inc.',
});
// Update your UI with paymentOption
```
1. Usa `presentPaymentSheet` para recopilar datos del pago. Una vez que el cliente termina, la hoja se cierra y se resuelve la promesa. Actualiza la interfaz de usuario (IU) con los datos del método de pago elegido.
```javascript
const { error, paymentOption } = await presentPaymentSheet();
```
1. Usa `confirmPaymentSheetPayment` para confirmar el pago. Esto se resuelve con el resultado del pago.
```javascript
const { error } = await confirmPaymentSheetPayment();
if (error) {
Alert.alert(`Error code: ${error.code}`, error.message);
} else {
Alert.alert(
'Success',
'Your order is confirmed!'
);
}
```
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: Habilita métodos de pago adicionales
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 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 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.
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`.
## 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.
```curl
curl https://api.stripe.com/v1/payment_intents \
-u "<>:" \
-d amount=10000 \
-d currency=usd \
-d "automatic_payment_methods[enabled]"=true \
-d on_behalf_of="{{CONNECTEDACCOUNT_ID}}" \
-d transfer_group=ORDER100
```
## Cobra comisiones
Cuando se utilizan cargos y transferencias separados, la plataforma puede cobrar comisiones sobre un cargo al reducir la cantidad que transfiere a las cuentas de destino. Por ejemplo, considera una transacción de servicio de entrega a domicilio en un restaurante que implique pagos al restaurante y al socio de la App:
1. El cliente paga un cargo de 100 USD.
1. Stripe cobra una comisión de 3.20 USD y agrega los 96.80 USD restantes al saldo pendiente de la cuenta de la plataforma.
1. La plataforma transfiere 70 USD a la cuenta conectada del restaurante y 20 USD a la cuenta conectada del conductor.
1. Una comisión de plataforma de 6.80 USD permanece en la cuenta de la plataforma.
> #### Comisión de la plataforma con fondos segregados
>
> Funds segregation es una versión preliminar funcionalidad privada que le permite debitar solicitud tarifas directamente de los fondos asignados durante transferir, proporcionando una separación contable limpia. Ponte en contacto con tu gestor de cuentas de Stripe para solicitar acceso.
Para obtener información sobre cómo procesar pagos en múltiples monedas con Connect, consulta [cómo trabajar con múltiples monedas](https://docs.stripe.com/connect/currencies.md).
## Disponibilidad de los envíos de fondos
El comportamiento predeterminado es transferir fondos desde el saldo disponible de la cuenta de la plataforma. Si intentas transferir un monto que exceda el saldo disponible, falla y aparece un mensaje de error. Para evitar este problema, al crear una transferencia, vincula la partida a un [cargo](https://docs.stripe.com/api/charges.md) existente especificando el ID del cargo como parámetro `source_transaction`. Con un `source_transaction`, la solicitud de transferencia devuelve el saldo correcto independientemente de tu saldo disponible si el cargo relacionado aún no se ha acreditado. Sin embargo, los fondos no estarán disponibles en la cuenta de destino hasta que los fondos del cargo asociado estén disponibles para transferirlos desde la cuenta de la plataforma.
> #### Transferencias con segregación de fondos
>
> La funcionalidad de versión preliminar privada de segregación de fondos requiere el parámetro `source_transaction` para las transferencias desde fondos asignados, de modo que queden vinculadas a su pago original.
> Si una transferencia falla debido a que el dinero en el saldo de tu plataforma no es suficiente, el hecho de agregar fondos no provocará automáticamente que se vuelva a intentar la acción fallida. Después de agregar fondos, debes repetir el envío o la transferencia que falló.
Si el cargo de origen tiene un valor `transfer_group`, Stripe asigna el mismo valor al `transfer_group` de la transferencia. De no ser así, Stripe genera una cadena con el formato `group_` más el ID del PaymentIntent asociado, por ejemplo: `group_pi_2NHDDD589O8KAxCG0179Du2s`. Asigna esa cadena como el `transfer_group` tanto para el cargo como para la transferencia.
> Debes especificar el `source_transaction` al crear un envío de fondos. No puedes actualizar ese atributo más adelante.
```curl
curl https://api.stripe.com/v1/transfers \
-u "<>:" \
-d amount=7000 \
-d currency=usd \
-d source_transaction="{{CHARGE_ID}}" \
-d destination="{{CONNECTEDACCOUNT_ID}}"
```
Puedes obtener la identificación del cargo del *PaymentIntent* (API object that represents your intent to collect payment from a customer, tracking charge attempts and payment state changes throughout the process):
- Obtén el [atributo latest_charge](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-latest_charge) del PaymentIntent. Este atributo es el ID del cargo más reciente asociado al PaymentIntent.
- [Solicita una lista de cargos](https://docs.stripe.com/api/charges/list.md), donde se especifique el `payment_intent` en la solicitud. Este método devuelve los datos completos de todos los cargos asociados con el PaymentIntent.
Cuando se usa este parámetro:
- El importe del envío de fondos no debe superar el importe del cargo de origen
- Puedes crear varios envíos de fondos con la misma `source_transaction` siempre que la suma de los envíos no supere el cargo de origen
- El envío de fondos asume el estado pendiente del cargo asociado, es decir, si los fondos del cargo están disponibles en N días, el pago recibido a través del envío de fondos por la cuenta de Stripe de destino también estará disponible en N días.
- Stripe crea automáticamente un `transfer_group` para ti
- La moneda de la transacción de saldo asociada con el cargo debe coincidir con la moneda de la transferencia
*Los métodos de pago asincrónicos* (Asynchronous payment methods can take up to several days to confirm whether the payment has been successful. During this time, the payment can't be guaranteed), como *ACH* (Automated Clearing House (ACH) is a US financial network used for electronic payments and money transfers that doesn’t rely on paper checks, credit card networks, wire transfers, or cash), pueden fallar después de realizar una solicitud de envío de fondos posterior. Para estos pagos, evita usar `source_transaction`. En su lugar, espera a que se active un evento [charge.succeeded](https://docs.stripe.com/api/events/types.md#event_types-charge.succeeded) antes de transferir los fondos. Si tienes que usar `source_transaction` con estos pagos, debes implementar una funcionalidad para gestionar los errores de pagos.
Cuando falla un pago utilizado como `source_transaction`, se transfieren fondos del saldo de la cuenta de tu plataforma a la cuenta conectada para cubrir el pago. Para recuperar estos fondos, [revierte](https://docs.stripe.com/connect/separate-charges-and-transfers.md#reverse-transfers) la transferencia asociada con el `source_transaction` fallido.
## Emite reembolsos
Puedes reembolsar cargos creados en tu plataforma usando su *clave secreta* (Stripe APIs use your secret API key to authenticate requests from your server; you can use this key to make any API call on behalf of your account, such as creating a charge or performing a refund). Sin embargo, el reembolso de un cargo no influye en ningún envío de fondos asociado. Tu plataforma es la que debe conciliar los importes adeudados reduciendo los importes de los envíos de fondos posteriores o [revirtiendo los envíos de fondos](https://docs.stripe.com/connect/separate-charges-and-transfers.md#reversing-transfers).
> #### Reembolsos con segregación de fondos
>
> La vista previa privada }de la funcionalidad segregación de fondos utiliza fondos asignados para reembolsos antes de debitar el saldo de pagos de su plataforma, proporcionando una separación contable limpia.
```curl
curl https://api.stripe.com/v1/refunds \
-u "<>:" \
-d charge="{{CHARGE_ID}}"
```
## Revertir envíos de fondos
Connect admite la posibilidad de [revertir transferencias](https://docs.stripe.com/api.md#create_transfer_reversal) efectuadas a cuentas conectadas, ya sea en parte o en su totalidad (estableciendo un valor para `amount`). Usa las revocaciones de envíos de fondos solo para reembolsos o disputas relacionadas con el cargo, o para corregir errores en el envío de fondos.
```curl
curl https://api.stripe.com/v1/transfers/{{TRANSFER_ID}}/reversals \
-u "<>:" \
-d amount=7000
```
Las reversiones de transferencias devuelven el monto especificado (o el total) al saldo disponible de tu plataforma, reduciendo el saldo disponible de la cuenta conectada en consecuencia. Solo puedes revertir una transferencia si el saldo disponible de la cuenta conectada es superior al monto de la reversión o si tiene activadas las [reservas conectadas](https://docs.stripe.com/connect/account-balances.md#understanding-connected-reserve-balances).
Si la revocación de la transferencia requiere una conversión de monedas y el monto revocado resultaría en un saldo de cero después de la conversión, se arrojará un error.
Deshabilitar los reembolsos de una cuenta conectada no bloqueará la capacidad de procesar anulaciones de transferencias.
## 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)
- [Cómo interpretar los saldos de las cuentas Connect](https://docs.stripe.com/connect/account-balances.md)
- [Disputas en las plataformas Connect](https://docs.stripe.com/connect/disputes.md)