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.

Tenemos previsto desactivar la compatibilidad con la API Sources para los métodos de pago locales. Si actualmente gestionas métodos de pago locales utilizando la API Sources, debes migrarlos a la API Payment Methods. Enviaremos comunicaciones por correo electrónico con más información sobre el fin de la compatibilidad con las API Sources y Tokens.

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.

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.

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.

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

La principal diferencia entre las API 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 de cobro antes de poder usarlo para un pago. Por el contrario, un PaymentMethod no tiene estado, ya que se basa en el objeto PaymentIntent para representar el estado del pago.

Después de elegir la API con la que integrarte, utiliza la guía de métodos de pago para ayudarte a determinar los tipos de métodos de pago adecuados 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 más relevantes. Puedes activar cualquier método de pago disponible en el Dashboard. La activación es generalmente 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, las fuentes guardadas existentes no migran automáticamente:

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

Para conservar los métodos de pago guardados de tus clientes existentes, debes convertir esas fuentes en métodos de pago utilizando 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 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:

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}}

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.

{
  "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, 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.