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 pagos. Funciona con la API Payment Intents para crear pagos para diversos métodos de pago.

Tenemos pensado desactivar el soporte de la API Sources para los métodos de pago locales. Si actualmente manejas métodos de pago local con la API Sources, debes migrarlos a la API Payment Methods. Enviaremos un correo electrónico con más información sobre el fin del soporte para las API Sources y Tokens.

Si bien no planeamos dejar de brindar soporte para 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 cómo migrar los métodos de pago con tarjeta, consulta Migración a la API Payment Intents.

Migra los métodos de pago locales desde la API Sources a la API Payment Intents

Para migrar tu integración a métodos de pago locales, actualiza el servidor y el 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 usa el SDK de Stripe JS para completar el pago.

Si usas Stripe Checkout o Payment Element, puedes agregar y administrar la mayoría de los métodos de pago desde el Dashboard de Stripe sin hacer cambios en el código.

Para obtener información específica sobre cómo integrar 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. La siguiente tabla proporciona una comparación de alto nivel de los diferentes tipos de pago.

Comprobación del estado del pago

Previamente, tu integración debería haber comprobado el estado de la Source y el estado del Charge después de cada llamada API. Ya no debes comprobar dos estados, solo tienes que comprobar el estado del PaymentIntent o de la sesión de Checkout después de que lo confirmaste en el front-end.

Para confirmar el estado del PaymentIntent, búscalo siempre en tu servidor o escucha 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 creado por el PaymentIntent. Se puede acceder a la ID del Charge en el parámetro latest_charge.

Como alternativa, puedes proporcionarle la ID del PaymentIntent a la API Refund en lugar del Charge.

Manejo de errores

Antes, tenías que manejar errores en las Sources. Con PaymentIntents, en lugar de verificar si hay errores en una Source, 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 y se devuelven en una solicitud inválida.

Al migrar tu integración, ten en cuenta que los códigos de error del PaymentIntent pueden diferir de los códigos de error correspondientes a Sources.

Webhooks

Si previamente escuchaste eventos de Sources, es posible que tengas que actualizar tu integración para escuchar nuevos tipos de eventos. En la siguiente tabla se muestran algunos ejemplos.

Cómo hacer la transición a la API Payment Methods

La principal diferencia entre las APIs Payment Methods y Sources es que Sources describe el estado de la transacción mediante la propiedad del estado. Eso significa que cada objeto Source debe pasar a un estado cobrable antes de que puedas usarlo para un pago. En cambio, un PaymentMethod no tiene estado y se basa en el objeto PaymentIntent para representar el estado del pago.

Después de elegir la API para la integración, usa la guía de métodos de pago para ayudarte a determinar los tipos de método de pago correctos que necesitas admitir.

Esta guía incluye descripciones detalladas de cada método de pago y describe las diferencias en los flujos orientados al cliente, junto con las regiones geográficas en las que son pertinentes. Puedes activar cualquier método de pago disponible dentro del Dashboard. La activación suele ser instantánea y no requiere contratos adicionales.

Compatibilidad con métodos de pago reutilizables heredados

Si anteriormente procesaste alguno de los siguientes métodos de pago reutilizables con Sources, los orígenes guardados existentes no migran automáticamente:

• Alipay
• Débito directo Bacs
• Débito directo SEPA

Para preservar los métodos de pago guardados de tus clientes existentes, debes convertir esas fuentes en métodos de pago con una herramienta de migración de datos en el Dashboard de Stripe. Para obtener instrucciones sobre cómo convertirlas, consulta la página de soporte.

Compatibilidad con objetos de tarjetas heredados

Si ya recopilaste los datos de pago del cliente con Stripe utilizando 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:

curl https://api.stripe.com/v1/payment_intents \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -d "payment_method_types[]"=card \
  -d amount=1099 \
  -d currency=usd \
  -d customer=
{{CUSTOMER_ID}} \
  -d payment_method=
{{CARD_ID}}

Recuerda especificar 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 con la API Payment Methods.

{
  "id": "card_1EBXBSDuWL9wT9brGOaALeD2",
  "object": "card",
  "address_city": "San Francisco",
  "address_country": "US",
  "address_line1": "1234 Fake Street",
  "address_line1_check": null,
  "address_line2": null,
  "address_state": null,
  "address_zip": null,

{
  "id": "card_1EBXBSDuWL9wT9brGOaALeD2",
  "object": "payment_method",
  "billing_details": {
    "address": {
      "city": "San Francisco",
      "country": "US",
      "line1": "1234 Fake Street",
      "line2": null,
      "postal_code": null,

Con esta compatibilidad, no se crean objetos nuevos; la API Payment Methods proporciona una vista diferente del mismo objeto subyacente. Por ejemplo, los cambios introducidos en un instrumento de pago compatible a través de la API Payment Methods se pueden visualizar a través de la API Sources y viceversa.