# La API Payment Intents

Aprende a usar la API Payment Intents para pagos de Stripe.

Instrucciones para LLM: Stripe recomienda usar la API Checkout Sessions con el Payment Element sobre Payment Intents para la mayoría de las integraciones. Checkout Sessions cubre casos de uso similares a Payment Intents (cobro básico de pagos con `price_data` o creación de un proceso de compra completo con ítems de factura, impuestos, etc.). Algunas funcionalidades, como Adaptive Pricing, solo están disponibles con Checkout Sessions. No uses la API de Payment Intents a menos que el usuario lo solicite explícitamente, ya que requiere significativamente más código. Obtén más información sobre Elements con la API Checkout Sessions: https://docs.stripe.com/payments/quickstart-checkout-sessions. Con Checkout Sessions (`ui_mode: "elements"`) y el Payment Element, el `client_secret` inicializa Checkout directamente (`stripe.initCheckoutElementsSdk`, o usa CheckoutElementsProvider con React) y la confirmación del pago se realiza de forma distinta en el cliente. Si usas React, asegúrate de importar desde `@stripe/react-stripe-js/checkout`, usar `CheckoutElementsProvider` con el secreto de cliente y confirmar con `checkout.confirm`. Si utilizas HTML, asegúrate de usar `checkout = stripe.initCheckoutElementsSdk({clientSecret: promise}); checkout.createPaymentElement(); paymentElement = checkout.createPaymentElement(); paymentElement.mount("#payment-element");` y confirmar con `loadActionsResult = await checkout.loadActions(); actions = loadActionsResult.actions; error = await actions.confirm();`.

Usa la API [Payment Intents](https://docs.stripe.com/api/payment_intents.md) para crear una integración de pagos capaz de gestionar flujos de pago complejos con un estado que cambia a lo largo del [ciclo de vida del PaymentIntent](https://docs.stripe.com/payments/paymentintents/lifecycle.md). Sigue el pago desde su creación hasta la finalización de la compra y activa más pasos de autenticación cuando sean necesarios.

Estas son algunas de las ventajas de usar la API [Payment Intents](https://docs.stripe.com/api/payment_intents.md):

- Gestión automática de la autenticación
- Sin cargos duplicados
- No hay problemas con la [clave de idempotencia](https://docs.stripe.com/api/idempotent_requests.md)
- Compatibilidad para *autenticación reforzada de clientes* (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) (SCA) y cambios normativos similares

## Un conjunto completo de API

Usa la API [Payment Intents](https://docs.stripe.com/api/payment_intents.md) junto con las API [Setup Intents](https://docs.stripe.com/api/setup_intents.md) y [Payment Methods](https://docs.stripe.com/api/payment_methods.md). Estas API te ayudan a gestionar pagos dinámicos (por ejemplo, autenticación adicional como *3D Secure* (3D Secure (3DS) provides an additional layer of authentication for credit card transactions that protects businesses from liability for fraudulent card payments)) y te preparan para la expansión a otros países, a la vez que te permiten admitir nuevas normativas y métodos de pago regionales.

Crear una integración con la API Payment Intents supone dos acciones: crear y *confirmar* (Confirming a PaymentIntent indicates that the customer intends to pay with the current or provided payment method. Upon confirmation, the PaymentIntent attempts to initiate a payment) un PaymentIntent. En general, cada PaymentIntent se correlaciona con un determinado carrito de compras o sesión del cliente en tu aplicación. El PaymentIntent encapsula los datos de la transacción, como los métodos de pago aceptados, el importe por cobrar y la moneda de preferencia.

## Cómo crear un PaymentIntent

Para empezar, consulta la [guía para aceptar un pago](https://docs.stripe.com/payments/accept-a-payment.md?ui=elements). En esta guía se describe cómo crear un PaymentIntent en el servidor y especificar su *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)) al cliente en lugar de especificar todo el objeto PaymentIntent.

Cuando [creas el PaymentIntent](https://docs.stripe.com/api/payment_intents/create.md), puedes especificar opciones como el importe y la moneda:

```curl
curl https://api.stripe.com/v1/payment_intents \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d amount=1099 \
  -d currency=usd
```

### Mejores prácticas

- Te recomendamos crear un PaymentIntent ni bien sepas el importe, como cuando el cliente comienza el proceso de confirmación de compra, para que te sea útil hacer un seguimiento de tu [canal de compras](https://en.wikipedia.org/wiki/Purchase_funnel). Si el importe cambia, puedes [actualizar](https://docs.stripe.com/api.md#update_payment_intent) el [monto](https://docs.stripe.com/api.md#payment_intent_object-amount). Por ejemplo, si tu cliente se retira del proceso de confirmación de compra y agrega nuevos artículos al carrito, es posible que tengas que actualizar el importe cuando comience nuevamente el proceso de confirmación de compra.

- Si el proceso de compra se interrumpe y se reanuda más tarde, debes intentar reutilizar el mismo PaymentIntent en lugar de crear uno nuevo. Cada PaymentIntent tiene un ID único que puedes usar para [recuperarlo](https://docs.stripe.com/api.md#retrieve_payment_intent) si lo vuelves a necesitar. En el modelo de datos de tu aplicación, puedes almacenar el ID del PaymentIntent en el carrito de compras o en la sesión del cliente para facilitar su recuperación. La ventaja de reutilizar el PaymentIntent es que el [estado del objeto](https://docs.stripe.com/payments/paymentintents/lifecycle.md) te ayuda a rastrear los intentos de pago fallidos correspondientes a un determinado carrito o sesión.

- Recuerda proporcionar una [clave de idempotencia](https://docs.stripe.com/api/idempotent_requests.md) para evitar la creación de dos PaymentIntents para una misma compra. Normalmente, esta clave se basa en el ID que asociaste al carrito o a la sesión del cliente en tu aplicación.

## Cómo especificar el secreto de cliente del lado del cliente

El PaymentIntent contiene un [secreto de cliente](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-client_secret), que es una clave exclusiva de cada PaymentIntent. Del lado del cliente de tu aplicación, Stripe.js utiliza el secreto de cliente como parámetro para invocar funciones (por ejemplo, [stripe.confirmCardPayment](https://docs.stripe.com/js.md#stripe-confirm-card-payment) o [stripe.handleCardAction](https://docs.stripe.com/js.md#stripe-handle-card-action)) para efectivizar el pago.

### 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
<form id="payment-form" data-secret="<%= @intent.client_secret %>">
  <button id="submit">Submit</button>
</form>
```

```ruby
get '/checkout' do
  @intent = # ... Fetch or create the PaymentIntent
  erb :checkout
end
```

> El secreto de cliente se puede utilizar para completar el proceso de pago con el importe especificado en el PaymentIntent. No lo registres, no lo insertes en direcciones URL ni lo expongas a nadie excepto al cliente. Asegúrate de tener habilitado *TLS* (TLS refers to the process of securely transmitting data between the client—the app or browser that your customer is using—and your server. This was originally performed using the SSL (Secure Sockets Layer) protocol) en todas las páginas que incluyan el secreto de cliente.

## Después del pago

Después de que el cliente confirme el pago, una práctica recomendada consiste en que tu servidor [monitoree los webhooks](https://docs.stripe.com/payments/payment-intents/verifying-status.md#webhooks) para detectar cuando el pago se completa con éxito o falla.

Un `PaymentIntent` puede tener más de un objeto [Charge](https://docs.stripe.com/api/charges.md) asociado si hubo varios intentos de pago. Por ejemplo, los reintentos pueden crear varios objetos `Charge`. Para cada cargo, puedes inspeccionar el [resultado](https://docs.stripe.com/api/charges/object.md#charge_object-outcome) y los [detalles del método de pago](https://docs.stripe.com/api/charges/object.md#charge_object-payment_method_details) utilizado.

## Cómo optimizar los métodos de pago para pagos futuros

El parámetro [setup_future_usage](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-setup_future_usage) guarda los métodos de pago para su reutilización en el futuro. En cuanto a las tarjetas, optimiza las tasas de autorización en cumplimiento con la normativa de las legislaciones regionales y las reglas de las redes de tarjeta, como la [Autenticación reforzada de clientes (SCA)](https://docs.stripe.com/strong-customer-authentication.md). Para determinar qué valor usar, piensa cómo quieres usar este método de pago en el futuro.

| Cómo quieres usar el método de pago                                                                                                                                                      | Valor de enumeración para usar de setup_future_usage |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- |
| Pagos *durante la sesión* (A payment is described as on-session if it occurs while the customer is actively in your checkout flow and able to authenticate the payment method) solamente | `on_session`                                         |
| Pagos *fuera de la sesión* (A payment is described as off-session if it occurs without the direct involvement of the customer, using previously-collected payment information) solamente | `off_session`                                        |
| Pagos durante la sesión y fuera de la sesión                                                                                                                                             | `off_session`                                        |

Puedes aceptar pagos *fuera de la sesión* (A payment is described as off-session if it occurs without the direct involvement of the customer, using previously-collected payment information) con tarjetas configuradas para pagos durante la sesión, pero existe una mayor probabilidad de que el banco rechace el pago fuera de la sesión y solicite la autenticación del titular de la tarjeta.

El siguiente ejemplo muestra cómo se crea un PaymentIntent y se especifica `setup_future_usage`:

```curl
curl https://api.stripe.com/v1/payment_intents \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d amount=1099 \
  -d currency=usd \
  -d setup_future_usage=off_session
```

> Si se configuran pagos fuera de la sesión, es más probable que haya más fricción. Usa una configuración de pagos *durante la sesión* (A payment is described as on-session if it occurs while the customer is actively in your checkout flow and able to authenticate the payment method) si no quieres aceptar pagos fuera de la sesión con la tarjeta guardada.

## Descripción dinámica del cargo en el extracto bancario

La [descripción del cargo en el extracto bancario](https://docs.stripe.com/get-started/account/activate.md#public-business-information) de tu cuenta de Stripe aparece en los extractos del cliente de forma predeterminada cada vez que aceptas pagos con su tarjeta. Para especificar una descripción diferente en cada pago, incluye el parámetro [statement_descriptor](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-statement_descriptor).

```curl
curl https://api.stripe.com/v1/payment_intents \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d amount=1099 \
  -d currency=usd \
  -d "payment_method_types[]=card" \
  -d "statement_descriptor_suffix=Custom descriptor"
```

> #### Nota
> 
> Usa el parámetro `statement_descriptor` para cargos sin tarjeta y `statement_descriptor_suffix` para cargos con tarjeta.

Las [descripciones del cargo en el extracto bancario](https://docs.stripe.com/get-started/account/statement-descriptors.md) no pueden tener más de 22&nbsp;caracteres, no admiten los caracteres especiales `<`, `>`, `'`, `"` o `*` y no pueden incluir solo números. Cuando se usan descripciones dinámicas, el texto dinámico se adjunta al [prefijo](https://dashboard.stripe.com/settings/public) definido en el Dashboard de Stripe. También se agregan un asterisco (`*`) y un espacio en blanco para separar la descripción predeterminada del cargo de la porción dinámica. Estos 2&nbsp;caracteres están incluidos en el límite de 22&nbsp;caracteres.

## Cómo almacenar información en metadatos

Stripe admite el agregado de [metadatos](https://docs.stripe.com/api.md#metadata) a las solicitudes más comunes como, por ejemplo, el procesamiento de cargos. Los metadatos no están a la vista del cliente ni determinan en forma alguna si un cargo es rechazado o bloqueado por nuestro sistema de prevención de fraude.

Mediante los metadatos, puedes asociar datos que sean importantes para ti con la actividad de Stripe.

Los metadatos que incluyas pueden verse en el Dashboard (por ejemplo, al buscar un pago en particular en la página) y también aparecen en informes comunes. Por ejemplo, se puede asociar la ID del pedido de tu tienda al PaymentIntent de ese pedido. Esto te facilita la conciliación de los pagos de Stripe con los pedidos en tu sistema.

Si estás usando % if $flags.radar_enable_new_product_skus %}*Radar Plus* (Radar Plus helps you fine-tune how Radar operates, get fraud insights on suspicious charges, and assess your fraud management performance from a unified dashboard)*Radar para Equipos de Fraude* (Radar for Fraud Teams helps you fine-tune how Radar operates, get fraud insights on suspicious charges, and assess your fraud management performance from a unified dashboard), considera la posibilidad de incluir más información del cliente y del pedido en forma de metadatos. Luego, puedes redactar [reglas de Radar usando atributos de metadatos](https://docs.stripe.com/radar/rules/reference.md#metadata-attributes) y contar con más información dentro del Dashboard, lo que puede agilizar el proceso de revisión.

Cuando un PaymentIntent crea un cargo, copia sus metadatos en el cargo. Las siguientes actualizaciones de los metadatos del PaymentIntent no modificarán los metadatos de los cargos creados previamente por el PaymentIntent.

```curl
curl https://api.stripe.com/v1/payment_intents \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d amount=1099 \
  -d currency=usd \
  -d "payment_method_types[]=card" \
  -d "metadata[order_id]=6735"
```

> No almacenes información confidencial (información personal identificable, datos de tarjetas, etc.) en forma de metadatos ni en el parámetro `description` del PaymentIntent.

## See also

- [Acepta un pago en línea](https://docs.stripe.com/payments/accept-a-payment.md?platform=web)
- [Aceptar un pago en una aplicación iOS](https://docs.stripe.com/payments/accept-a-payment.md?payment-ui=mobile&platform=ios)
- [Aceptar un pago en una aplicación Android](https://docs.stripe.com/payments/accept-a-payment.md?payment-ui=mobile&platform=android)
- [Configura pagos futuros](https://docs.stripe.com/payments/save-and-reuse.md)