# Migración a las API Payment Intents y Payment Methods Aprende a pasar de las API Sources y Tokens a la API Payment Methods. La [API Payment Methods](https://docs.stripe.com/api/payment_methods.md) reemplaza a las API [Tokens](https://docs.stripe.com/api/tokens.md) y [Sources](https://docs.stripe.com/api/sources.md) actuales y es la forma recomendada de integración para recopilar y guardar información de pagos. Funciona con la [API Payment Intents](https://docs.stripe.com/payments/payment-intents.md) 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* (Payment methods used in specific countries or regions, such as bank transfers, vouchers, and digital wallets. Examples include Pix (Brazil, bank transfers), Konbini (Japan, vouchers), and WeChat Pay (China, digital wallet)). Si actualmente utilizas algún método de pago local con la API Sources, debes [migrarlo a la API Payment Methods](https://docs.stripe.com/payments/payment-methods/transitioning.md#migrate-local-payment-methods). Te enviaremos un correo electrónico con más información sobre el fin de la compatibilidad con 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](https://docs.stripe.com/payments/payment-intents/migration.md). ## 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](https://docs.stripe.com/api/payment_intents.md). Hay tres opciones de integración típicas: - Redirige a [Stripe Checkout](https://docs.stripe.com/payments/checkout.md) para tu flujo de pagos. - Usa el [Payment Element](https://docs.stripe.com/payments/payment-element.md) 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](https://docs.stripe.com/payments/payment-methods/overview.md). La siguiente tabla 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 | | Crea una Source en el front-end o en el servidor. | Crea una sesión de Checkout en el servidor. | Crea un PaymentIntent en el servidor. | Crea un PaymentIntent en el servidor. | | Autoriza el pago cargando un widget o redirigiendo a un tercero. | No se necesita. | Pasa el secreto del cliente al front-end y usa el SDK de Stripe JS para procesar un Payment Element a fin de completar el pago. | Pasa el secreto del cliente al front-end, usa tu propio formulario para recopilar los datos de tu cliente y completa el pago de acuerdo con el método de pago. | | Confirma que la fuente admita cargos y carga la Source. | No se necesita. | No se necesita. | No se necesita. | | Confirma que el Charge se realizó correctamente de forma asincrónica con el webhook `charge.succeeded`. | Confirma que la sesión de Checkout se realizó correctamente con el webhook `payment_intent.succeeded`. | Confirmar que el PaymentIntent se realizó correctamente con el webhook `payment_intent.succeeded`. | Confirmar que el PaymentIntent se realizó correctamente con el webhook `payment_intent.succeeded`. | > Un objeto PaymentIntent representa un pago en la nueva integración y crea un Charge cuando confirmas el pago en el front-end. Si previamente almacenaste referencias en el Charge, puedes seguir haciéndolo obteniendo la ID de Charge del PaymentIntent después de que el cliente complete el pago. Sin embargo, también te recomendamos que guardes la ID del PaymentIntent. ### 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. | payment_intent.status | Significado | Instrucciones especiales | | ------------------------- | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `succeeded` | El pago se realizó correctamente. | No aplica | | `requires_payment_method` | El pago falló. | No aplica | | `requires_action` | El cliente no completó la autorización del pago. | Si el cliente no completa el pago en un plazo de 48 horas, el PaymentIntent pasa a `requires_payment_method` y puedes volver a intentar la confirmación. | 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. | Webhook anterior | Nuevo webhook en Checkout | Nuevo webhook en PaymentIntents | Instrucciones especiales | | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | | `source.chargeable` | No aplica | No aplica | | | `source.failed` | No aplica | No aplica | | | `source.canceled` | No aplica | No aplica | | | `charge.succeeded` | `checkout.session.completed` | `payment_intent.succeeded` | También se envía el webhook `charge.succeeded` para que no tengas que actualizar tu integración a fin de escuchar el nuevo webhook. | | `charge.failed` | No aplicable: el cliente puede volver a intentar el pago en la misma sesión de Checkout hasta que [venza](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-expires_at), momento en el que recibirás un evento `checkout.session.expired`. | `payment_intent.payment_failed` | También se envía el webhook `charge.failed` para que no tengas que actualizar tu integración a fin de 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 APIs Payment Methods y Sources es que Sources describe el estado de la transacción mediante la propiedad del [estado](https://docs.stripe.com/api/sources/object.md#source_object-status). 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* (The Payment Intents API tracks the lifecycle of a customer checkout flow and triggers additional authentication steps when required by regulatory mandates, custom Radar fraud rules, or redirect-based payment methods) para representar el estado del pago. > La siguiente tabla no es una lista completa de métodos de pago. Si integras otros métodos de pago con la API Sources, mígralos también a la API Payment Methods. | Flujos | Integra el método de pago con la API Payment Intents | Tokens o Sources con la API Charges | | ----------------------------- | --------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | | Tarjetas | [Pagos con tarjeta](https://docs.stripe.com/payments/cards.md) | [Aceptado en Tokens](https://docs.stripe.com/payments/charges-api.md); no recomendado para Sources | | Débito directo ACH | [Débitos directos en cuentas bancarias estadounidenses](https://docs.stripe.com/payments/ach-direct-debit.md) | [Aceptado en Tokens](https://docs.stripe.com/ach-deprecated.md). No aceptado en Sources | | Transferencia de crédito ACH | [Transferencias bancarias en USD](https://docs.stripe.com/payments/customer-balance/migrating-from-sources.md) | [Obsoleto](https://docs.stripe.com/sources/ach-credit-transfer.md) | | Alipay | [Pagos de Alipay](https://docs.stripe.com/payments/alipay.md) | [Obsoleto](https://docs.stripe.com/sources/alipay.md) | | Bancontact | [Pagos de Bancontact](https://docs.stripe.com/payments/bancontact.md) | [Obsoleto](https://docs.stripe.com/sources/bancontact.md) | | EPS | [Pagos con EPS](https://docs.stripe.com/payments/eps.md) | Obsoleto | | giropay | [pagos con giropay](https://docs.stripe.com/payments/giropay.md) | [Obsoleto](https://docs.stripe.com/sources/giropay.md) | | iDEAL | [pagos iDEAL](https://docs.stripe.com/payments/ideal.md) | [Obsoleto](https://docs.stripe.com/sources/ideal.md) | | Klarna | [Pagos de Klarna](https://docs.stripe.com/payments/klarna.md) | Obsoleto | | Multibanco | [Pagos multibanco](https://docs.stripe.com/payments/multibanco.md) | [Beta obsoleta](https://docs.stripe.com/sources/multibanco.md) | | Przelewy24 | [Pagos Przelewy24](https://docs.stripe.com/payments/p24.md) | [Obsoleto](https://docs.stripe.com/sources/p24.md) | | Transferencia de crédito SEPA | [Transferencias bancarias en EUR](https://docs.stripe.com/payments/customer-balance/migrating-from-sepa-credit-transfer.md) | [Obsoleto](https://docs.stripe.com/sources/sepa-credit-transfer.md) | | Débito directo SEPA | [Débitos directos de la zona única de pagos en euros](https://docs.stripe.com/payments/sepa-debit.md) | [Obsoleto](https://docs.stripe.com/sources/sepa-debit.md) | | WeChat Pay | [Pagos de WeChat Pay](https://docs.stripe.com/payments/wechat-pay.md) | [Obsoleto](https://docs.stripe.com/sources/wechat-pay.md) | Después de elegir la API para la integración, usa la [guía de métodos de pago](https://stripe.com/payments/payment-methods-guide) 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](https://stripe.com/payments/payment-methods-guide#payment-methods-fact-sheets) en las que son pertinentes. Puedes activar cualquier método de pago disponible dentro del [Dashboard](https://dashboard.stripe.com/account/payments/settings). 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](https://docs.stripe.com/sources.md), 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](https://support.stripe.com/questions/reusable-object-migration). ## Compatibilidad con objetos de tarjetas heredados Si ya recopilaste los datos de pago del cliente con Stripe utilizando [tarjetas](https://docs.stripe.com/payments/charges-api.md) o [Sources](https://docs.stripe.com/sources.md), puedes empezar a usar la API Payment Methods de inmediato sin migrar ninguna información de pago. Los métodos de pago compatibles que están guardados en un objeto *Customer* (Customer objects represent customers of your business. They let you reuse payment methods and give you the ability to track multiple payments) se pueden utilizar en cualquier API que acepte objetos *PaymentMethod* (PaymentMethods represent your customer's payment instruments, used with the Payment Intents or Setup Intents APIs). Por ejemplo, puedes usar una tarjeta guardada como PaymentMethod al crear un PaymentIntent: ```curl curl https://api.stripe.com/v1/payment_intents \ -u "<>:" \ -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 método de pago compatible al asociar el objeto con el PaymentIntent. Puedes [recuperar](https://docs.stripe.com/api/payment_methods/retrieve.md) todos los métodos de pago compatibles guardados mediante la API de métodos de pago. #### Tarjeta ```json { "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, "address_zip_check": null, "brand": "Visa", "country": "US", "customer": "{{CUSTOMER_ID}}", "cvc_check": null, "dynamic_last4": null, "exp_month": 8, "exp_year": 2024, "fingerprint": "53v265akSHAnIk1X", "funding": "credit", "last4": "4242", "metadata": { }, "name": null, "tokenization_method": null } ``` ```json { "id": "card_1EBXBSDuWL9wT9brGOaALeD2", "object": "payment_method", "billing_details": { "address": { "city": "San Francisco", "country": "US", "line1": "1234 Fake Street", "line2": null, "postal_code": null, "state": null }, "name": null, "phone": null, "email": null }, "card": { "brand": "visa", "checks": { "address_line1_check": null, "address_postal_code_check": null, "cvc_check": null }, "country": "US", "exp_month": 8, "exp_year": 2024, "fingerprint": "53v265akSHAnIk1X", "funding": "credit", "last4": "4242", "three_d_secure_usage": { "supported": true }, "wallet": null }, "created": 123456789, "customer": "cus_EepWxEKrgMaywv", "livemode": false, "metadata": { }, "type": "card" } ``` #### Fuente de tarjeta ```json { "id": "src_1AhIN74iJb0CbkEwmbRYPsd4", "object": "source", "amount": null, "client_secret": "src_client_secret_sSPHZ17iQG6j9uKFdAYqPErO", "created": 1500471469, "currency": null, "flow": "none", "livemode": false, "metadata": { }, "owner": { "address": { "city": "Berlin", "country": "DE", "line1": "Nollendorfstraße 27", "line2": null, "postal_code": "10777", "state": null }, "email": "jenny.rosen@example.com", "name": "Jenny Rosen", "phone": null, "verified_address": null, "verified_email": null, "verified_name": null, "verified_phone": null }, "status": "chargeable", "type": "card", "usage": "reusable", "card": { "exp_month": 4, "exp_year": 2024, "address_line1_check": "unchecked", "address_zip_check": "unchecked", "brand": "Visa", "country": "US", "cvc_check": "unchecked", "funding": "credit", "last4": "4242", "three_d_secure": "optional", "tokenization_method": null, "dynamic_last4": null } } ``` ```json { "id": "card_1EBXBSDuWL9wT9brGOaALeD2", "object": "payment_method", "billing_details": { "address": { "city": "Berlin", "country": "DE", "line1": "Nollendorfstraße 27", "line2": null, "postal_code": "10777", "state": null }, "name": "Jenny Rosen", "phone": null, "email": "jenny.rosen@example.com" }, "card": { "brand": "visa", "checks": { "address_line1_check": null, "address_postal_code_check": null, "cvc_check": null }, "country": "US", "exp_month": 4, "exp_year": 2024, "fingerprint": "53v265akSHAnIk1X", "funding": "credit", "last4": "4242", "three_d_secure_usage": { "supported": true }, "wallet": null }, "created": 1500471469, "customer": "{{CUSTOMER_ID}}", "livemode": false, "metadata": { }, "type": "card" } ``` 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 método de pago compatible a través de la API Payment Methods se pueden visualizar a través de la API Sources y viceversa. ## See also - [Guía de métodos de pago](https://stripe.com/payments/payment-methods-guide) - [Pagos de Connect](https://docs.stripe.com/connect/charges.md) - [Referencia de la API Payment Methods](https://docs.stripe.com/api/payment_methods.md)