Cómo migrar a la API Payment Intents

¿Te interesa usar Stripe Billing, Tax, descuentos, envíos o conversión de moneda?

Estamos desarrollando una integración de Payment Element que gestiona las suscripciones, los impuestos, los descuentos, los envíos y la conversión de monedas. Para obtener más información, consulta la guía Crear una página de confirmación de compra.

Aprende a migrar tu integración actual de la API Charges y tarjetas.

La migración del flujo de pago puede resultar una tarea titánica. Es más seguro empezar a usar la API Payment Intents de a poco en paralelo con la API Charges. Para ello, puedes dividir la migración en los siguientes pasos:

Actualiza la versión de la API y la biblioteca de cliente.
Si corresponde, migra el código que lee las propiedades de Charge para tener una ruta de lectura uniforme entre los cargos creados por la API Charges y los cargos creados por la API Payment Intents. De esta manera, garantizas que la integración de lectura funcione tanto para la integración anterior de pagos como para la nueva.
Migra tu integración actual de la API Charges para web, iOS y Android para usar la API Payment Intents.
Migra la integración para guardar tarjetas en los objetos Customer.
Haz pruebas con tarjetas de prueba reglamentarias para garantizar que la integración actualizada gestione la autenticación correctamente.

Actualiza tu versión de API y la biblioteca de cliente

Si bien la API Payment Intents funciona en todas las versiones de API, te recomendamos actualizar a la última versión. Si decides usar una versión de API anterior a 2019-02-11, presta atención a los siguientes dos cambios cuando repases los ejemplos de códigos:

requires_source ahora se llama requires_payment_method
requires_source_action ahora se llama requires_action

Asimismo, si usas una de nuestras SDK, actualiza a la última versión de la biblioteca para usar la API Payment Intents.

Migra tus flujos para pagos puntuales

Una integración creada con Stripe.js y Elements consta de los siguientes pasos:

Registra tu intención de cobrar el pago del lado del servidor
Recopila los datos del pago del lado del cliente
Inicia la creación del pago
Completa el pedido del cliente del lado del servidor

Paso 1: Registrar la intención de cobrar el pago del lado del servidor

Crea un PaymentIntent en tu servidor y hazlo accesible del lado del cliente.

Antes

Después

Antes no era posible

Command Line
curl https://api.stripe.com/v1/payment_intents \
  -usk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -d "amount"=1099 \
  -d "currency"="usd"

Paso 2: Recopilar los datos de pago del lado del cliente

Usa la función confirmCardPayment, que recopila la información de pago y la envía directamente a Stripe.

Antes

Después

stripe.createToken(
  cardElement
).then(function(token) {
  // Send token to server
});

stripe.confirmCardPayment(
  INTENT_SECRET_FROM_STEP_1,
  {
    payment_method: {card: cardElement}
  }
).then(function(result) {
  if (result.error) {
    // Display error.message in your UI.
  } else {
    // The payment has succeeded
    // Display a success message
  }
});

Paso 3: Iniciar la creación del pago

En tu integración actual, el último paso consiste en utilizar la información de pago tokenizada para crear un cargo en el servidor. Esto ya no es necesario, ya que la función confirmCardPayment, invocada en el paso anterior, inicia la creación del cargo.

Antes

Después

Command Line
curl https://api.stripe.com/v1/charges \
  -usk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -d "source"="{{FROM_PREVIOUS_STEP}}" \
  -d "amount"=1099 \
  -d "currency"="usd"

Se completa en el paso anterior

Paso 4: Completar el pedido del cliente

Con la confirmación automática, el cargo se crea de forma asincrónica en función de la acción que ejecuta el cliente de su lado, por lo que debes controlar los webhooks para determinar si se concreta el pago. Para tomar medidas como completar el pedido del cliente después de la confirmación del pago, implementa soporte para webhooks y monitorea el evento payment_intent.succeeded.

Antes

Después

Si el cargo se efectúa con éxito, completa el pedido.

Suscríbete al webhook payment_intent.succeeded y procesa en el controlador de webhooks.

Ahora que has hecho la migración, usa las tarjetas de prueba en la siguiente sección para verificar si la integración actualizada gestiona la autenticación con 3D Secure.

Migra la integración para guardar tarjetas en objetos Customer

La integración de la API Payment Intents que recopila información de tarjetas dentro del flujo de finalización de compra consta de los siguientes pasos:

Registra tu intención de cobrar el pago del lado del servidor
Recopila los datos del pago del lado del cliente
Inicia la creación del pago
Completa el pedido del cliente del lado del servidor

Paso 1: Registrar la intención de cobrar el pago del lado del servidor

Crea un PaymentIntent en tu servidor. Establece setup_future_usage en off_session, si tu intención principal es cobrar a los usuarios cuando estén fuera de la aplicación, o en on_session, si planeas cobrarles cuando estén en la aplicación. Si tienes pensado utilizar la tarjeta tanto para pagos dentro como fuera de la sesión, usa la configuración off_session. Si especificas el parámetro setup_future_usage junto con el ID del cliente, el PaymentMethod resultante se guardará en ese cliente después de la confirmación del PaymentIntent y de que el cliente complete todas las acciones solicitadas. A continuación, pon el PaymentIntent a disposición del lado del cliente.

Antes

Después

Antes no era posible

Command Line
curl https://api.stripe.com/v1/payment_intents \
  -usk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -d "setup_future_usage"="off_session" \
  -d "amount"=1099 \
  -d "currency"="usd"

Paso 2: Recopilar los datos de pago del lado del cliente

Usa la función confirmCardPayment, que recopila la información de pago y la envía directamente a Stripe.

Antes

Después

stripe.createToken(
// or stripe.createSource
  cardElement
).then(function(token) {
  // Send token to server
});

stripe.confirmCardPayment(
  '{{INTENT_SECRET_FROM_STEP_1}}',
  {
    payment_method: {card: cardElement},
  }
).then(function(result) {
  if (result.error) {
    // Display error.message in your UI.
  } else {
    // The payment has succeeded
    // Display a success message
  }
});

Por último, adjunta el método de pago (paymentIntent.payment_method) al cliente.

Antes

Después

Command Line
curl https://api.stripe.com/v1/customers/{{CUSTOMER_ID}}/sources \
  -usk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -d "source"="{{TOKEN_OR_SOURCE}}"

Command Line
curl https://api.stripe.com/v1/payment_method/{{PAYMENT_METHOD_ID}}/attach \
  -usk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -d "customer"="{{CUSTOMER_ID}}"

Paso 3: Iniciar la creación del pago

Antes

Después

Command Line
curl https://api.stripe.com/v1/charges \
  -usk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -d "source"="{{FROM_PREVIOUS_STEP}}" \
  -d "customer"="{{CUSTOMER_ID}}" \
  -d "amount"=1099 \
  -d "currency"="usd"

Se completa en el paso anterior

Paso 4: Completar el pedido del cliente

Antes

Después

Si el cargo se efectúa con éxito, completa el pedido.

Suscríbete al webhook payment_intent.succeeded y procesa en el controlador de webhooks.

Ahora que has hecho la migración, usa las tarjetas de prueba en la siguiente sección para verificar si la integración actualizada gestiona la autenticación con 3D Secure.

Acceder a métodos de pago guardados

Para mostrar los objetos Cards, Sources y PaymentMethods ya guardados del cliente, indica los métodos de pago en lugar de leer la propiedad sources del objeto Customer. Esta acción es necesaria porque los nuevos PaymentMethods agregados a un cliente no se duplicarán en la propiedad sources del objeto Customer.

Antes

Después

Command Line

customer.sources

Command Line
curl https://api.stripe.com/v1/payment_methods?customer={{CUSTOMER_ID}}&type=card \
  -usk_test_4eC39HqLyjWDarjtT1zdp7dc
:

Probar la integración

Es importante que pruebes la integración a conciencia para asegurarte de estar gestionando correctamente las tarjetas que requieren otra autenticación y las que no. Usa estos números de tarjeta en modo de prueba con cualquier fecha de vencimiento futura y cualquier código CVC de tres dígitos para validar tu integración para ambos tipos de tarjeta.

Número	Autenticación	Descripción
	Exigido en la configuración o en la primera transacción	Esta tarjeta de prueba exige la autenticación de los pagos únicos. No obstante, si configuras la tarjeta con la API Setup Intents y usas la tarjeta guardada para pagos sucesivos, no es necesario hacer otra autenticación.
	Obligatorio	Esta tarjeta de prueba exige la autenticación en todas las transacciones.
	Obligatorio	Esta tarjeta de prueba exige la autenticación, pero los pagos serán rechazados con el código de error `insufficient_funds` después de completarse con éxito la autenticación.
	Aceptado	Esta tarjeta de prueba admite la autenticación mediante 3D Secure 2, pero no la exige. Los pagos efectuados con esta tarjeta no requieren otra autenticación en modo de prueba salvo que tus reglas de Radar en modo de prueba soliciten la autenticación.

Usa estas tarjetas en tu aplicación o en la demostración de pagos para ver la diferencia de comportamiento.

Cómo migrar a la API Payment Intents

¿Te interesa usar Stripe Billing, Tax, descuentos, envíos o conversión de moneda?

Actualiza tu versión de API y la biblioteca de cliente

Migra tus flujos para pagos puntuales

Paso 1: Registrar la intención de cobrar el pago del lado del servidor

Paso 2: Recopilar los datos de pago del lado del cliente

Paso 3: Iniciar la creación del pago

Paso 4: Completar el pedido del cliente

Migra la integración para guardar tarjetas en objetos Customer

Paso 1: Registrar la intención de cobrar el pago del lado del servidor

Paso 2: Recopilar los datos de pago del lado del cliente

Paso 3: Iniciar la creación del pago

Paso 4: Completar el pedido del cliente

Acceder a métodos de pago guardados

Probar la integración

Consulta también