# Migración a las API Payment Intents y Payment Methods Descubre cómo 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 los 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 gestionas métodos de pago locales utilizando la API Sources, debes [migrarlos a la API Payment Methods](https://docs.stripe.com/payments/payment-methods/transitioning.md#migrate-local-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](https://docs.stripe.com/payments/payment-intents/migration.md). ## 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](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 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](https://docs.stripe.com/payments/payment-methods/overview.md). 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` | > 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. ### 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 | Instrucciones especiales | | ------------------------- | ----------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `succeeded` | El pago se ha efectuado correctamente. | No aplicable | | `requires_payment_method` | El pago ha fallado. | No aplicable | | `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 | Instrucciones especiales | | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | `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](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`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 Payment Methods y Sources es que Sources describe el estado de la transacción a través de la propiedad [status](https://docs.stripe.com/api/sources/object.md#source_object-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* (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. > 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](https://docs.stripe.com/payments/cards.md) | [Aceptado en Tokens](https://docs.stripe.com/payments/charges-api.md); no recomendado para Sources | | Adeudo directo ACH | [Adeudos directos de cuentas bancarias de EE. UU.](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 de EPS](https://docs.stripe.com/payments/eps.md) | Obsoleto | | giropay | [Pagos de giropay](https://docs.stripe.com/payments/giropay.md) | [Obsoleto](https://docs.stripe.com/sources/giropay.md) | | iDEAL | [Pagos de 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 con multibanco](https://docs.stripe.com/payments/multibanco.md) | [Beta obsoleta](https://docs.stripe.com/sources/multibanco.md) | | Przelewy24 | [Pagos de 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 | [Adeudos 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 con la que integrarte, utiliza la [guía de métodos de pago](https://stripe.com/payments/payment-methods-guide) 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](https://stripe.com/payments/payment-methods-guide#payment-methods-fact-sheets) en las que son más relevantes. Puedes activar cualquier método de pago disponible en el [Dashboard](https://dashboard.stripe.com/account/payments/settings). 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](https://docs.stripe.com/sources.md), 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](https://support.stripe.com/questions/reusable-object-migration). ## Compatibilidad con objetos de tarjetas heredados If you previously collected card customer payment details with Stripe using [cards](https://docs.stripe.com/payments/charges-api.md) or [Sources](https://docs.stripe.com/sources.md), you can start using the Payment Methods API immediately without migrating any payment information. Los métodos de pago compatibles que se han guardado 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 un objeto *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}}" ``` No olvides indicar el ID del cliente que en el que se guarda tu 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 a través de la API Payment Methods. #### 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, las actualizaciones realizadas en un método de pago compatible a través de la API Payment Methods se pueden ver 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) - [Conectar pagos](https://docs.stripe.com/connect/charges.md) - [Referencia de la API Payment Methods](https://docs.stripe.com/api/payment_methods.md)