Transición a las API Payment Intents y Payment Methods
La API Payment Methods reemplaza a las API Tokens y Sources actuales y es la forma recomendada de integración para recopilar y guardar información de los pagos. Funciona con la API Payment Intents para crear pagos para diversos métodos de pago.
Planeamos desactivar el soporte de la API Sources para los métodos de pago locales. Si en la actualidad manejas métodos de pago locales utilizando la API Sources, debes migrarlos a la API Payment Methods. Te enviaremos un correo electrónico con más información sobre este fin del soporte.
Aunque no planeamos desactivar la compatibilidad con los métodos de pago con tarjeta, te recomendamos que los migres a las API Payment Methods y Payment Intents. Para obtener más información sobre la migración de métodos de pago con tarjeta, consulta Migración a la API Payment Intents.
Migra los métodos de pago locales de la API Sources a la API Payment Intents
Para migrar tu integración a métodos de pago locales, actualiza tu servidor y tu front end para usar la API PaymentIntents. Hay tres opciones de integración típicas:
- Redirige a Stripe Checkout para tu flujo de pagos.
- Usa el Payment Element de Stripe en tu propia página de pago.
- Crea tu propio formulario y utiliza el SDK de Stripe JS para efectivizar el pago.
Si utilizas Stripe Checkout o Payment Element, puedes añadir y gestionar la mayoría de los métodos de pago desde el Dashboard de Stripe sin realizar cambios en el código.
Para obtener información específica sobre la integración de un método de pago local mediante la API Payment Methods, consulta las instrucciones para ese método de pago en la documentación de los métodos de pago. En la siguiente tabla se proporciona una comparación de alto nivel de los diferentes tipos de pago.
Integración anterior | Stripe Checkout | Payment Element | Formulario propio |
---|---|---|---|
Complejidad baja | Complejidad media | Complejidad alta | |
Crear una Source en el front-end o en el servidor | Crear una sesión de Checkout en el servidor | Crea un PaymentIntent en el servidor | Crea un PaymentIntent en el servidor |
Autorizar el pago cargando un widget o redirigiendo a un tercero | No es necesario | Pasa el secreto de cliente al front-end y usa el SDK de Stripe JS para renderizar un Payment Element con el fin de efectivizar el pago | Pasa el secreto de cliente al front-end, utiliza tu propio formulario para recoger los datos de tu cliente y efectiviza el pago de acuerdo con el método de pago |
Confirmar que la fuente acepta pagos y cobrar a Source | No es necesario | No es necesario | No es necesario |
Confirmar que el Charge se ha realizado correctamente de forma asíncrona con el webhook charge.succeeded | Confirmar que la sesión de Checkout se ha realizado correctamente con el webhook payment_intent.succeeded | Confirmar que el PaymentIntent se ha realizado correctamente con el webhook payment_intent.succeeded | Confirmar que el PaymentIntent se ha realizado correctamente con el webhook payment_intent.succeeded |
Precaución
Un objeto PaymentIntent representa un pago en la nueva integración y crea un Charge cuando confirmas el pago en el front-end. Si has almacenado previamente referencias al Charge, puedes continuar haciéndolo obteniendo el ID de Charge del PaymentIntent después de que el cliente efectivice el pago. Sin embargo, también te recomendamos que guardes el ID de PaymentIntent.
Campos de mapeo
Si utilizas el Payment Element o tu propio formulario, debes volver a asignar los campos Source a los campos del PaymentIntent. Los campos específicos dependen del método de pago.
Comprobación del estado del pago
Anteriormente, tu integración debería haber verificado tanto el estado de Source como el estado de Charge después de cada llamada a la API. Ya no necesitas comprobar dos estados; solo necesitas comprobar el estado del PaymentIntent o de la sesión de Checkout después de confirmarlo en el front-end.
payment_intent.status | Significado | Nota |
---|---|---|
succeeded | El pago se ha efectuado correctamente. | |
requires_payment_method | El pago ha fallado. | |
requires_action | El cliente no ha completado la autorización del pago. | Si el cliente no efectiviza el pago en el transcurso de 48 horas, el PaymentIntent pasará a requires_payment_method y podrás volver a intentar la confirmación. |
Siempre confirma el estado del PaymentIntent buscándolo en tu servidor o escuchando los webhooks en tu servidor. No confíes únicamente en que el usuario regrese a la return_url
que se proporciona cuando confirmas el PaymentIntent.
Reembolsos
Puedes seguir llamando a la API Refunds con un Charge que cree el PaymentIntent. Se puede acceder al ID de Charge en el parámetro latest_charge
.
Como alternativa, puedes proporcionar el ID de PaymentIntent a la API Refunds en lugar del Charge.
Administración de errores
Anteriormente, tenías que manejar los errores en Sources. Con PaymentIntents, en lugar de verificar si hay errores en Sources, verificas si hay errores en el PaymentIntent cuando se crea y después de que el cliente haya autorizado el pago. La mayoría de los errores en el PaymentIntent son del tipo invalid_request_error
, devueltos en una petición inválida.
Cuando migres tu integración, ten en cuenta que los códigos de error de PaymentIntent pueden diferir de los códigos de error correspondientes de Sources.
Webhooks
Si anteriormente has escuchado eventos Source, es posible que tengas que actualizar la integración para escuchar nuevos tipos de eventos. En la siguiente tabla se muestran algunos ejemplos.
Webhook antiguo | Nuevo webhook en Checkout | Nuevo webhook en PaymentIntents | Nota |
---|---|---|---|
source.chargeable | No aplicable | No aplicable | |
source.failed | No aplicable | No aplicable | |
source.canceled | No aplicable | No aplicable | |
charge.succeeded | checkout.session.completed | payment_intent.succeeded | También se envía el webhook charge.succeeded para que no tengas que actualizar la integración para escuchar el nuevo webhook. |
charge.failed | No se aplica: el cliente puede volver a intentar el pago en la misma sesión de Checkout hasta que caduque, momento en el que recibirás un evento checkout.session.expired . | payment_intent.payment_failed | También se envía el webhook charge.failed charge.failed’ para que no tengas que actualizar la integración para escuchar el nuevo webhook. |
charge.dispute.created | charge.dispute.created | charge.dispute.created |
Cómo hacer la transición a la API Payment Methods
La principal diferencia entre las API de Payment Methods y Sources es que Sources describe el estado de la transacción a través de la propiedad status. Eso significa que cada objeto Source
debe pasar a un estado cobrable antes de que pueda usarse para un pago. Por el contrario, un PaymentMethod
no tiene estado y se basa en el objeto PaymentIntent para representar el estado del pago.
Nota
En la siguiente tabla, no se presenta una lista completa de métodos de pago. Si integras otros métodos de pago con la API Sources, debes migrarlos también a la API Payment Methods.
Flujos | Integra Payment Method con la API Payment Intents | Tokens o Sources con la API Charges |
---|---|---|
Tarjetas | Pagos con tarjeta | Aceptado en Tokens; no recomendado para Sources |
Adeudo directo ACH | Adeudos directos de cuentas bancarias de EE. UU. | Aceptado en Tokens. No aceptado en Sources |
Alipay | Pagos de Alipay | Obsoleto |
Bancontact | Pagos de Bancontact | Obsoleto |
EPS | Pagos de EPS | Obsoleto |
giropay | Pagos de giropay | Obsoleto |
iDEAL | Pagos de iDEAL | Obsoleto |
Klarna | Pagos de Klarna | Obsoleto |
Multibanco | Planificado | Beta obsoleta |
Przelewy24 | Pagos de Przelewy24 | Obsoleto |
Débito directo SEPA | Adeudos directos de la Zona Única de Pagos en Euros | Obsoleto |
Sofort | Pagos de Sofort | Obsoleto |
WeChat Pay | Pagos de WeChat Pay | Obsoleto |
Después de elegir la API con la que quieres realizar la integración, nuestra guía de métodos de pago puede ayudarte a determinar los tipos de métodos de pago adecuados para tus clientes.
En esta guía se incluyen descripciones detalladas de cada método de pago y se describen las diferencias en los flujos que ve el cliente, además de las regiones geográficas donde más se utilizan. Puedes activar cualquier método de pago disponible dentro del Dashboard. La activación suele ser instantánea y no requiere contratos adicionales ni implica procesos extensos.
Compatibilidad con métodos de pago reutilizables heredados
Si anteriormente procesaste alguno de los siguientes métodos de pago reutilizables con Sources, las fuentes guardadas existentes no migran automáticamente. Para conservar los métodos de pago guardados de tus clientes actuales, debes convertir esas fuentes en métodos de pago mediante una herramienta de migración de datos en el Dashboard de Stripe. Para obtener instrucciones sobre cómo convertirlos, consulta la página de soporte.
- Alipay
- Adeudo directo Bacs
- Débito directo SEPA
Compatibilidad con objetos de tarjetas heredados
Si anteriormente recopilaste datos de pago de clientes con tarjeta con Stripe usando tarjetas o Sources, puedes empezar a usar la API Payment Methods de inmediato sin migrar ninguna información de pago.
Los instrumentos de pago compatibles que están guardados en un objeto Customer se pueden utilizar en cualquier API que acepte objetos PaymentMethod. Por ejemplo, puedes utilizar una tarjeta guardada como PaymentMethod al crear el PaymentIntent:
No olvides indicar el ID del cliente que tiene guardado el instrumento de pago compatible al asociar el objeto con el PaymentIntent.
Puedes recuperar todos los instrumentos de pago compatibles guardados a través de la API Payment Methods.
Ten en cuenta que con esta compatibilidad, no se crean objetos nuevos; la API Payment Methods proporciona una vista diferente del mismo objeto subyacente. Por ejemplo, las actualizaciones realizadas en un instrumento de pago compatible a través de la API Payment Methods se pueden ver a través de la API Sources y viceversa.