# Migrer vers les API Payment Intents et Mode de paiement

Découvrez comment passer des API Sources et Tokens à l'API Payment Methods.

L’[API Payment Methods](https://docs.stripe.com/api/payment_methods.md) remplace les API [Tokens](https://docs.stripe.com/api/tokens.md) et [Sources](https://docs.stripe.com/api/sources.md) existantes en tant que moyen recommandé pour les intégrations pour collecter et stocker les informations de paiement. Elle fonctionne avec l’[API Payment Intents](https://docs.stripe.com/payments/payment-intents.md) pour créer des paiements pour un large éventail de moyens de paiement.

Nous prévoyons de désactiver la prise en charge d’API Sources pour les paiements par carte. Si vous gérez actuellement des modes de paiement par carte à l’aide d’API Sources, vous devez les migrer vers l’API Payment Intents. Nous vous enverrons un courriel contenant plus d’informations sur la fin de la prise en charge de l’API Sources.

## Migrer vers l’API Payment Intents

Pour migrer votre intégration, mettez à jour votre serveur et votre interface client pour utiliser l’[API Payment Intents](https://docs.stripe.com/api/payment_intents.md). Les options d’intégration courantes comprennent :

- Redirigez vers [Stripe Checkout](https://docs.stripe.com/payments/checkout.md) pour votre flux de paiement.
- Utilisez le Stripe [Paiement Element](https://docs.stripe.com/payments/payment-element.md) sur votre propre page de paiement.
- Créer un formulaire personnalisé et utiliser la trousse SDK Stripe JS pour finaliser le paiement.

Si vous utilisez Checkout ou Payment Element, vous pouvez ajouter et gérer la plupart des modes de paiement à partir du Dashboard Stripe sans apporter de modifications au code.

Pour obtenir des informations précises sur l’intégration d’un mode de paiement par carte à l’aide de l’API Payment Methods, consultez les instructions relatives à ce mode de paiement dans la [documentation sur les modes de paiement](https://docs.stripe.com/payments/payment-methods/overview.md). Le tableau suivant fournit une comparaison de haut niveau des différents types de paiement.

| Ancienne intégration | Stripe Checkout | Payment Element | Formulaire personnalisé |
| --- | --- | --- | --- |
|  | Faible complexité | Complexité moyenne | Complexité élevée |
| Créer une Source sur l’interface utilisateur ou sur le serveur. | Créer une `CheckoutSession` sur le serveur. | Créer un `PaymentIntent` sur le serveur. | Créer un `PaymentIntent` sur le serveur. |
| Autoriser le paiement en chargeant un gadget ou en redirigeant vers un tiers. | Non nécessaire | Transmettez la clé secrète du client à l’interface utilisateur et utilisez la trousse SDK Stripe JS pour afficher un composant Payment Element pour finaliser le paiement. | Transmettez la clé secrète du client à l’interface utilisateur, utilisez votre propre formulaire pour recueillir les renseignements de votre client, puis effectuez le paiement selon le mode de paiement sélectionné. |
| Confirmez que la source peut être débitée et débitez la Source. | Non nécessaire | Non nécessaire | Non nécessaire |
| Confirmez que le Paiement a réussi de manière asynchrone grâce au lien de rappel HTTP `charge.succeeded`. | Confirmez que la session Checkout a réussi grâce au lien de rappel HTTP `payment_intent.succeeded`. | Confirmez que le PaymentIntent a réussi grâce au lien de rappel HTTP `payment_intent.succeeded`. | Confirmez que le PaymentIntent a réussi grâce au lien de rappel HTTP `payment_intent.succeeded`. |

> #### Utilisation continue des objets Charge
> 
> Un objet `PaymentIntent` représente un paiement dans la nouvelle intégration, et il crée un `Charge` lorsque vous confirmez le paiement sur l’interface utilisateur. Si vous aviez sauvegardé des références au `Charge`, vous pouvez continuer de le faire en récupérant l’ID du `Charge` à partir du `PaymentIntent` une fois que le client a effectué le paiement. Cependant, nous vous recommandons également de sauvegarder l’ID du `PaymentIntent`.

### Vérification de l’état du paiement

Auparavant, votre intégration devait vérifier à la fois l’état de la `Source` et l’état du `Charge` après chaque appel à l’API. Vous n’avez plus besoin de vérifier deux objets : vous devez uniquement vérifier l’état du `PaymentIntent` ou de la `CheckoutSession` après l’avoir confirmé sur l’interface utilisateur.

| payment_intent.status | Signification |
| --- | --- |
| `succeeded` | Le paiement a été effectué. |
| `requires_payment_method` | Le paiement a échoué. |
| `requires_action` | Le client n’a pas terminé d’autoriser le paiement, potentiellement [en raison d’une exigence 3DS](https://docs.stripe.com/payments/3d-secure/authentication-flow.md#check-status). |

Confirmez toujours l’état du `PaymentIntent` en le récupérant sur votre serveur ou en écoutant les événements du lien de rappel HTTP sur votre serveur. Ne vous fiez pas uniquement au fait que l’utilisateur revienne sur le `return_url` fourni lorsque vous confirmez le `PaymentIntent`.

### Remboursements

Vous pouvez appeler l’API Refunds à l’aide de l’ID du `PaymentIntent` au lieu de l’ID du `Charge`.

Vous pouvez également continuer d’appeler l’API Refunds avec l’ID du `Charge` créé par le `PaymentIntent`. Vous pouvez obtenir l’ID du `Charge` à partir de la propriété [latest_charge](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-latest_charge).

### Gestion des erreurs

Auparavant, vous deviez gérer les erreurs sur la `Source`. Avec les `PaymentIntents`, vous vérifiez plutôt les erreurs sur le `PaymentIntent` lors de sa création et après que le client a autorisé le paiement. La plupart des erreurs sur le `PaymentIntent` sont de type `invalid_request_error`, renvoyées dans une requête non valide.

Lorsque vous migrez votre intégration, gardez à l’esprit que les codes d’erreur du `PaymentIntent` peuvent différer des codes d’erreur correspondants pour les `Sources`.

### Webhooks

Si vous écoutiez auparavant les événements de la `Source`, vous devrez peut-être mettre à jour votre intégration pour écouter plutôt les événements d’autres objets. Le tableau suivant présente quelques exemples.

| Ancien événement | Nouvel événement Checkout | Nouvel événement PaymentIntent | Instructions spéciales |
| --- | --- | --- | --- |
| `source.chargeable` | Sans objet | Sans objet |  |
| `source.failed` | Sans objet | Sans objet |  |
| `source.canceled` | Sans objet | Sans objet |  |
| `charge.succeeded` | `checkout.session.completed` | `payment_intent.succeeded` | L’événement `charge.succeeded` est également envoyé, vous pouvez donc continuer de l’écouter à la place des autres. |
| `charge.failed` | Sans objet - Le client peut tenter à nouveau d’effectuer le paiement dans la même session Checkout jusqu’à ce qu’elle [expire](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-expires_at), auquel cas vous recevez un événement `checkout.session.expired`. | `payment_intent.payment_failed` | L’événement `charge.failed` est également envoyé, vous pouvez donc continuer de l’écouter à la place des autres. |
| `charge.dispute.created` | `charge.dispute.created` | `charge.dispute.created` |  |

## Transition vers l’API Payment Methods

La principale différence entre les API Payment Methods et Sources réside dans le fait que l’API Sources décrit l’état de la transaction par l’intermédiaire de la propriété [d’état](https://docs.stripe.com/api/sources/object.md#source_object-status). Par conséquent, chaque objet `Source` doit passer à un état facturable pour que vous puissiez l’utiliser pour un paiement. En revanche, un objet `PaymentMethod` n’a pas d’état et repose sur l’objet PaymentIntent pour représenter l’état du paiement.

> Le tableau suivant n’est pas une liste exhaustive des moyens de paiement. Si vous intégrez d’autres moyens de paiement à API Sources, migrez-les également vers l’API Payment Methods.

| Flux | API Payment Methods et Payment Intents | API Tokens ou Sources avec API Charges |
| --- | --- | --- |
| Cartes | [Paiements par carte](https://docs.stripe.com/payments/cards.md) | Obsolète |
| Prélèvement automatique ACH | [Prélèvements automatiques de compte bancaire aux États-Unis](https://docs.stripe.com/payments/ach-direct-debit.md) | [Pris en charge avec l’API Tokens](https://docs.stripe.com/ach-deprecated.md); Non pris en charge avec l’API Sources |

Une fois que vous avez choisi l’API à 'intégrer, consultez le [guide des moyens de paiement](https://stripe.com/payments/payment-methods-guide) pour vous aider à déterminer les types de moyens de paiement que vous devez prendre en charge.

Ce guide décrit en détail chaque moyen de paiement et les différences dans les procédures pour le client, ainsi que [les régions géographiques](https://stripe.com/payments/payment-methods-guide#payment-methods-fact-sheets) dans lesquelles ils sont les plus pertinents. Vous pouvez activer tous les moyens de paiement qui figurent dans le [Dashboard](https://dashboard.stripe.com/account/payments/settings). De manière générale, l’activation est instantanée et ne nécessite pas de contrats supplémentaires.

## Migrer les Sources sauvegardées vers les PaymentMethods

Pour continuer d’utiliser les identifiants de vos clients existants sauvegardés sur des `Sources` ou sur des [cartes créées avec l’API Charges](https://docs.stripe.com/payments/charges-api.md), vous devez les convertir en `PaymentMethods` à l’aide de l’[outil de migration de données du Dashboard Stripe](https://dashboard.stripe.com/workbench/health/migrations).

Pour utiliser un `PaymentMethod` migré avec l’API Payment Intents, transmettez l’ID du `PaymentMethod` et l’ID du `Customer` lors de la création d’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

- [Guide des moyens de paiement](https://stripe.com/payments/payment-methods-guide)
- [Associer les paiements](https://docs.stripe.com/connect/charges.md)
- [Documentation sur l’API Payment Methods](https://docs.stripe.com/api/payment_methods.md)