# La API Payment Intents Aprende a usar la API Payment Intents para pagos de Stripe. Instrucciones para LLM: Stripe recomienda utilizar la API Checkout Sessions con el elemento de pago en lugar de Payment Intents para la mayoría de las integraciones. Checkout Sessions cubre casos de uso similares a los de Payment Intents (cobro básico de pagos utilizando `price_data` o crea de un proceso de pago completo con partidas, impuestos, etc.). Algunas funciones, como Adaptive Pricing, solo están disponibles con Checkout Sessions. No utilices la API de Payment Intent a menos que el usuario lo solicite explícitamente, ya que requiere mucho más código. Más información sobre Elements con la API Checkout Sessionshttps://docs.stripe.com/payments/quickstart-checkout-sessions. Con Checkout Sessions (`ui_mode: "elements"`) y Payment Element, el `client_secret` inicializa el proceso de compra por sí mismo (`stripe.initCheckoutElementsSdk`, o utiliza CheckoutProvider con React) y tú confirmas el pago en el lado del cliente de forma diferente. Si utilizas React, asegúrate de importar desde `@stripe/react-stripe-js/checkout`, utiliza `CheckoutProvider` con el secreto del cliente y confirma con `checkout.confirm`. Si utilizas HTML, asegúrate de utiliza `checkout = stripe.initCheckoutElementsSdk({clientSecret: promise}); checkout.createPaymentElement(); paymentElement = checkout.createPaymentElement(); paymentElement.mount("#payment-element");` y confirma 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 finalizar el proceso de compra, y activa pasos de autenticación adicionales cuando sean necesarios. Entre algunas de las ventajas de usar la API [Payment Intents](https://docs.stripe.com/api/payment_intents.md) se incluyen: - Gestión automática de la autenticación - Sin cargos duplicados - Sin [problemas de claves 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 similares en las normativas ## Un conjunto completo de API Utiliza 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, al tiempo que te permiten ser compatible con 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 comenzar, consulta la [guía para aceptar un pago](https://docs.stripe.com/payments/accept-a-payment.md?ui=elements). Describe cómo crear un PaymentIntent en el servidor y pasar 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 pasar 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 divisa: ```curl curl https://api.stripe.com/v1/payment_intents \ -u "<>:" \ -d amount=1099 \ -d currency=usd ``` ### Mejores prácticas - Recomendamos crear un PaymentIntent tan pronto como sepas la cantidad, como cuando el cliente empieza el proceso de compra, para ayudarte a supervisar tu [canal de compra](https://en.wikipedia.org/wiki/Purchase_funnel). Si la cantidad cambia, puedes[actualizar](https://docs.stripe.com/api.md#update_payment_intent) su [importe](https://docs.stripe.com/api.md#payment_intent_object-amount). Por ejemplo, si tu cliente se retira del proceso de compra y añade nuevos artículos a su carrito, puede que tengas que actualizar la cantidad cuando vuelva a empezar el proceso de compra. - Si el proceso de compra se interrumpe y se reanuda más tarde, intenta volver a utilizar 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 necesitas de nuevo. En el modelo de datos de tu aplicación, puedes guardar el ID del PaymentIntent en el carrito de compras o la sesión del cliente para facilitar su recuperación. La ventaja de volver a utilizar el PaymentIntent es que el [estado del objeto](https://docs.stripe.com/payments/paymentintents/lifecycle.md) ayuda a hacer un seguimiento de los intentos de pago fallidos para 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 está basada en el ID asociado al carrito o a la sesión del cliente en tu aplicación. ## Pasar el secreto de cliente al lado del cliente La PaymentIntent contiene un [secreto de cliente](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-client_secret), una clave que es única para cada PaymentIntent. En el lado del cliente de la aplicación, Stripe.js utiliza el secreto de cliente como parámetro al invocar funciones (como [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 completar el pago. ### Recupera el secreto del 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 utiliza 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 en tu servidor, utilizando la función `fetch` del navegador. Este enfoque es mejor si tu lado del cliente es una aplicación de una sola página, en particular una construida con un marco de front-end moderno como React. Crea el punto de conexión del servidor que se utiliza para el secreto de cliente: #### Ruby ```ruby get '/secret' do intent = # ... Create or retrieve the PaymentIntent {client_secret: intent.client_secret}.to_json end ``` Y luego busca el secreto del 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 Envía el secreto del cliente al cliente desde tu servidor. Este enfoque funciona mejor si tu aplicación genera contenido estático en el servidor antes de enviarlo al navegador. Añade el [client_secret](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-client_secret) en tu formulario de proceso de compra. En el código del lado del servidor, recupera el secreto de cliente de PaymentIntent: #### Ruby ```erb
``` ```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, es una buena práctica 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` podría tener más de un objeto de [cargo](https://docs.stripe.com/api/charges.md) asociado si ha habido varios intentos de pago. Por ejemplo, los reintentos pueden crear múltiples`cargos`. Para cada aceptar pagos puedes consultar el[resultado](https://docs.stripe.com/api/charges/object.md#charge_object-outcome) y los [detalles del método pago](https://docs.stripe.com/api/charges/object.md#charge_object-payment_method_details) usado. ## 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 conforme a las legislaciones regionales y las reglas de las redes de tarjeta, como la [SCA](https://docs.stripe.com/strong-customer-authentication.md). Para elegir qué valor usar, piensa cómo quieres usar este método de pago en el futuro. | Cómo quieres utilizar 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 y fuera de la sesión | `off_session` | También 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 una tarjeta configurada para pagos durante la sesión, pero es más probable que el banco rechace el pago fuera de la sesión y exija 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 "<>:" \ -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. Utiliza la configuración *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 tienes previsto aceptar pagos fuera de la sesión con la tarjeta guardada. ## Descripción dinámica del cargo en el extracto bancario By default, your Stripe account’s [statement descriptor](https://docs.stripe.com/get-started/account/set-up.md#public-business-information) appears on customer statements whenever you charge their card. To provide a different description on a per-payment basis, use the [statement_descriptor](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-statement_descriptor) parameter. ```curl curl https://api.stripe.com/v1/payment_intents \ -u "<>:" \ -d amount=1099 \ -d currency=usd \ -d "payment_method_types[]=card" \ -d "statement_descriptor_suffix=Custom descriptor" ``` > #### Nota > > Utiliza el `statement_descriptor` para los cargos que no sean de tarjeta y el parámetro `statement_descriptor_suffix` para los cargos de tarjeta. La [descripción del cargo en el extracto bancario](https://docs.stripe.com/get-started/account/statement-descriptors.md) está limitada a 22 caracteres, no se pueden utilizar los caracteres especiales `<`, `>`, `'`, `"`, o `*`, y no debe estar formada únicamente por números. Cuando se utiliza una descripción dinámica del cargo en el extracto bancario, el texto dinámico se añade al [prefijo de la descripción del cargo en el extracto bancario](https://dashboard.stripe.com/settings/public) establecido en el Dashboard de Stripe. También se añade un asterisco (`*`) y un espacio en blanco para separar la descripción del cargo en el extracto bancario por defecto de la parte dinámica. Estos 2 caracteres se contabilizan en el límite de 22 caracteres. ## Cómo almacenar información en metadatos Stripe admite añadir [metadatos](https://docs.stripe.com/api.md#metadata) a las solicitudes más comunes como, por ejemplo, procesar pagos. Los metadatos no están a la vista del cliente ni determinan que nuestro sistema de prevención de fraudes rechace o bloquee un pago. Con 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 los informes comunes. Por ejemplo, puedes adjuntar el ID del pedido de tu tienda al PaymentIntent de ese pedido. Esta acción te facilita la conciliación de los pagos en Stripe con los pedidos en tu sistema. Si utilizas Radar for Fraud Teams**, considera la posibilidad de pasar información adicional sobre el cliente y el pedido como metadatos. Luego puedes redactar [reglas Radar usando atributos de](https://docs.stripe.com/radar/rules/reference.md#metadata-attributes) metadatos y contar con más información dentro del Dashboard, lo que puede agilizar el proceso de revisar. Cuando un PaymentIntent crea un cargo, el PaymentIntent copia sus metadatos en el cargo. Las actualizaciones posteriores 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 "<>:" \ -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 - [Aceptar un pago en línea](https://docs.stripe.com/payments/accept-a-payment.md?platform=web) - [Aceptar un pago en una aplicación de iOS](https://docs.stripe.com/payments/accept-a-payment.md?payment-ui=mobile&platform=ios) - [Aceptar un pago en una aplicación de 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)