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 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 se incluyen:

• Gestión automática de la autenticación
• Sin cargos duplicados
• Sin problemas de claves de idempotencia
• Compatibilidad para autenticación reforzada de clientes (SCA) y cambios similares en las normativas

Un conjunto completo de API

Utiliza la API Payment Intents junto con las API Setup Intents y Payment Methods. Estas API te ayudan a gestionar pagos dinámicos (por ejemplo, autenticación adicional como 3D Secure) 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 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. Describe cómo crear un PaymentIntent en el servidor y pasar su secreto de cliente al cliente en lugar de pasar todo el objeto PaymentIntent.

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

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

Mejores prácticas

• Recomendamos crear un PaymentIntent tan pronto como se conozca el importe, como, por ejemplo, cuando el cliente comience el proceso de compra, para ayudar a hacer un seguimiento de tu embudo de compras. Si el importe cambia, puedes actualizar el importe. Por ejemplo, si el cliente abandona el proceso de compra y añade nuevos artículos a su carrito, es posible que tengas que actualizar el importe cuando vuelva a iniciar 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 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 ayuda a hacer un seguimiento de los intentos de pago fallidos para 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 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, 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 o stripe.handleCardAction) para completar el pago.

Recupera el secreto del cliente

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

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, es una buena práctica 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 ha habido varios intentos de pago, por ejemplo, reintentos. Para cada cargo, puedes inspeccionar 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 conforme a las legislaciones regionales y las reglas de las redes de tarjeta, como la SCA. Para elegir qué valor usar, piensa cómo quieres usar este método de pago en el futuro.

También puedes aceptar pagos fuera de la sesión 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 https://api.stripe.com/v1/payment_intents \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -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 especificar una descripción diferente en cada pago, incluye el parámetro statement_descriptor.

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

La descripción del cargo en el extracto bancario está limitada a 22 caracteres, no se pueden utilizar los caracteres especiales <, >, ', ", ni *, 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 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 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 estás usando Radar for Fraud Teams, plantéate la posibilidad de especificar información adicional 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, 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 https://api.stripe.com/v1/payment_intents \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d amount=1099 \
  -d currency=usd \
  -d "payment_method_types[]"=card \
  -d "metadata[order_id]"=6735