La API Payment Intents

Usa la API Payment Intents 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. 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:

• Gestión automática de la autenticación
• Sin cargos duplicados
• No hay problemas con la clave de idempotencia
• Compatibilidad para autenticación reforzada de clientes (SCA) y cambios normativos similares

Un conjunto completo de API

Usa la API Payment Intents junto con las API Setup Intents y Payment Methods. Estas API te ayudarán a gestionar pagos dinámicos (por ejemplo, otra autenticación como 3D Secure) y te prepararán para expandir tu empresa a otros países, adherir a nuevas normativas y admitir métodos de pago regionales.

Crear una integración con la API Payment Intents supone dos acciones: crear y confirmar 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. En esta guía se describe cómo crear un PaymentIntent en el servidor y especificar su secreto de cliente al cliente en lugar de especificar todo el objeto PaymentIntent.

Cuando creas el PaymentIntent, puedes especificar opciones como el importe y la moneda:

curl https://api.stripe.com/v1/payment_intents \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -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. Si el importe cambia, puedes actualizar su importe. Por ejemplo, si tu cliente se retira del proceso de confirmación de compra y agrega nuevos artículos a su 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 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 te ayuda a rastrear los intentos de pago fallidos correspondientes a un determinado carrito o sesión.

• Recuerda proporcionar una clave de idempotencia 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, 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 o stripe.handleCardAction) para efectivizar el pago.

Recuperar el secreto de cliente

El PaymentIntent incluye un secreto de cliente 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.

get '/secret' do
  intent = # ... Create or retrieve the PaymentIntent
  {client_secret: intent.client_secret}.to_json
end

(async () => {
  const response = await fetch('/secret');
  const {client_secret: clientSecret} = await response.json();
  // Render the form using the clientSecret
})();

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 para detectar cuando el pago se completa con éxito o falla.

Un PaymentIntent puede tener más de un objeto Charge asociado si hubo varios intentos de pago, por ejemplo, reintentos. Para cada cargo, puedes revisar el resultado y los detalles del método de pago utilizados.

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

El parámetro 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). Para determinar qué valor usar, piensa cómo quieres usar este método de pago en el futuro.

Puedes aceptar pagos fuera de la sesión 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 https://api.stripe.com/v1/payment_intents \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -d amount=1099 \
  -d currency=usd \
  -d setup_future_usage=off_session

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

La descripción del cargo en el extracto bancario de tu cuenta de Stripe aparece en los extractos del cliente de forma predeterminada cada vez que haces un cargo en su tarjeta. Para proporcionar una descripción diferente por pago, incluye el parámetro statement_descriptor.

curl https://api.stripe.com/v1/payment_intents \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -d amount=1099 \
  -d currency=usd \
  -d "payment_method_types[]"=card \
  -d statement_descriptor="Custom descriptor"

Las descripciones del cargo en el extracto bancario no pueden tener más de 22 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 de la descripción del cargo en el extracto bancario 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 caracteres están incluidos en el límite de 22 caracteres.

Cómo almacenar información en metadatos

Stripe admite el agregado de metadatos 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 Radar para Equipos de Fraude, 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 y contar con más información dentro del Dashboard, lo que puede agilizar tu 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 https://api.stripe.com/v1/payment_intents \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -d amount=1099 \
  -d currency=usd \
  -d "payment_method_types[]"=card \
  -d "metadata[order_id]"=6735