# 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 pensado desactivar el soporte de la API Sources para los pagos de tarjeta. Si actualmente manejas métodos de pago de tarjeta con la API Sources, debes migrarlos a la API Payment Intents. Enviaremos un correo electrónico con más información sobre el fin del soporte para las API Sources.

## Migrar a la API Payment Intents

Para migrar tu integración, actualiza tu servidor y el front-end para usar la [API Payment Intents](https://docs.stripe.com/api/payment_intents.md). Las opciones de integración típicas incluyen las siguientes:

- 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 un formulario personalizado y usa el SDK de JS de Stripe para completar el pago.

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

Para obtener información específica sobre cómo integrar un método de pago de tarjeta 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 personalizado |
| --- | --- | --- | --- |
|  | Complejidad baja | Complejidad media | Complejidad alta |
| Crea un Source en el front-end o en el servidor. | Crea una `CheckoutSession` 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 de cliente al front-end y usa el SDK de JS de Stripe para renderizar un Payment Element a fin de completar el pago. | Pasa el secreto de cliente al front-end, usa tu propio formulario para recopilar los datos de tu cliente y completa el pago en función del método de pago. |
| Confirma que se le pueda cobrar y cobra al objeto 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`. | Confirma que el PaymentIntent se realizó correctamente con el webhook `payment_intent.succeeded`. | Confirma que el PaymentIntent se realizó correctamente con el webhook `payment_intent.succeeded`. |

> #### Uso continuo de los objetos Charge
> 
> Un objeto `PaymentIntent` representa un pago en la nueva integración y crea un `Charge` cuando confirmas el pago en el front-end. Si antes almacenabas referencias al `Charge`, puedes seguir haciéndolo obteniendo el ID del `Charge` a partir del `PaymentIntent` una vez que el cliente complete el pago. Sin embargo, también te recomendamos que almacenes el ID del `PaymentIntent`.

### Comprobación del estado del pago

Anteriormente, tu integración debía comprobar tanto el estado del objeto `Source` como el estado del objeto `Charge` después de cada llamada a la API. Ya no necesitas comprobar dos objetos; solo debes comprobar el estado del `PaymentIntent` o de la `CheckoutSession` después de confirmarlo en el front-end.

| payment_intent.status | Significado |
| --- | --- |
| `succeeded` | El pago se realizó correctamente. |
| `requires_payment_method` | El pago falló. |
| `requires_action` | El cliente no terminó de autorizar el pago, posiblemente [debido a un requisito de 3DS](https://docs.stripe.com/payments/3d-secure/authentication-flow.md#check-status). |

Confirma siempre el estado del `PaymentIntent` recuperándolo en tu servidor o escuchando los eventos de webhook en tu servidor. No dependas únicamente de que el usuario regrese a la `return_url` que se proporciona cuando confirmas el `PaymentIntent`.

### Reembolsos

Puedes llamar a la API Refunds con el ID del `PaymentIntent` en lugar del ID del `Charge`.

De forma alternativa, puedes seguir llamando a la API Refunds con el ID del objeto `Charge` que crea el `PaymentIntent`. Puedes obtener el ID del `Charge` desde la propiedad [latest_charge](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-latest_charge).

### Manejo de errores

Anteriormente, tenías que gestionar los errores en el objeto `Source`. En cambio, con los `PaymentIntents`, verificas si hay errores en el `PaymentIntent` cuando se crea y después de que el cliente autorizó el pago. La mayoría de los errores del `PaymentIntent` son de tipo `invalid_request_error`, que se devuelven en una solicitud no vá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 de `Sources`.

### Webhooks

Si antes escuchabas los eventos del `Source`, es posible que debas actualizar tu integración para escuchar los eventos de otros objetos en su lugar. En la siguiente tabla se muestran algunos ejemplos.

| Evento antiguo | Nuevo evento de Checkout | Nuevo evento de PaymentIntent | 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 evento `charge.succeeded`, por lo que puedes seguir escuchándolo en lugar de los demás. |
| `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 evento `charge.failed`, por lo que puedes seguir escuchándolo en lugar de los demás. |
| `charge.dispute.created` | `charge.dispute.created` | `charge.dispute.created` |  |

## 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 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 | API Payment Methods y Payment Intents | Tokens o Sources con las API Charges |
| --- | --- | --- |
| Tarjetas | [Pagos con tarjeta](https://docs.stripe.com/payments/cards.md) | Obsoleto |
| 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 |

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.

## Migra las Sources existentes guardadas a PaymentMethods

Para seguir usando las credenciales de tus clientes actuales guardadas en `Sources` o en [tarjetas creadas con la API Charges](https://docs.stripe.com/payments/charges-api.md), debes convertirlas a `PaymentMethods` con la [herramienta de migración de datos del Dashboard de Stripe](https://dashboard.stripe.com/workbench/health/migrations).

Para usar un `PaymentMethod` migrado con la API Payment Intents, pasa el ID del `PaymentMethod` y el ID del `Customer` al crear un `PaymentIntent`:

```curl
curl https://api.stripe.com/v1/payment_intents \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d "automatic_payment_methods[enabled]=true" \
  -d amount=1099 \
  -d currency=usd \
  -d "customer={{CUSTOMER_ID}}" \
  -d "payment_method={{PAYMENTMETHOD_ID}}"
```

## 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)