# Guide de migration de la version bêta d'Issuing Comment migrer depuis la version bêta d'Issuing Stripe Issuing est proposé depuis peu à toutes les entreprises aux États-Unis. Au terme du programme bêta, nous avons publié la tarification et les changements qui s’appliquent à notre API, laquelle comprend des fonctionnalités et des mises à jour pour lui permettre d’évoluer sur le long terme. En fonction de votre intégration, certaines des modifications apportées aux API peuvent les faire dysfonctionner. À ce titre, nous vous recommandons de lire attentivement tous les éléments du présent guide. Nous cesserons de proposer l’API en version bêta à partir du 1er mars 2021. Vous trouverez ci-dessous un résumé de toutes les modifications apportées à l’API pour vous aider dans votre migration. Contactez le [support](mailto:support-issuing@stripe.com) pour toute question. ## Compatibilité > Comme indiqué dans chaque section, nous vous recommandons de prendre en charge l’ancienne et la nouvelle API jusqu’à ce vous soyez passé à la nouvelle. Nous vous recommandons également de créer un compte Issuing afin de tester la nouvelle API avant de passer à la nouvelle sur votre compte principal. ### Attributs Les utilisateurs de la version bêta ont accès aux anciens et aux nouveaux attributs disponibles sur tous les objets Issuing. Les attributs renommés redirigent vers la même valeur backend que les anciens attributs. À la fin de la version bêta, seuls les nouveaux attributs seront disponibles. Pour faciliter la préparation, nous vous recommandons de configurer la lecture pour qu’elle prenne en charge l’ancien et le nouvel attribut jusqu’à ce que vous soyez passé à la nouvelle API. ### Paramètres En ce qui concerne les paramètres renommés, vous pouvez utiliser soit l’ancien nom, soit le nouveau, mais pas les deux en même temps. À la fin de la version bêta, seuls les nouveaux paramètres seront acceptés. Pour faciliter la préparation, nous vous recommandons de configurer l’écriture pour qu’elle prenne en charge l’ancien et le nouveau paramètre jusqu’à ce que vous soyez passé à la nouvelle API. ### Énumérations En ce qui concerne les nouvelles valeurs d’énumération, la transition sera plus complexe. Il sera possible d’accéder aux nouvelles valeurs en écriture et en lecture, mais les valeurs existantes continueront d’être renvoyées jusqu’à la fin de la version bêta. Par exemple, le [type](https://docs.stripe.com/api/issuing/cardholders/object.md#issuing_cardholder_object-type) Cardholder de `business_entity` s’appelle désormais `company`. Les objets Cardholder existants continueront d’afficher l’ancienne valeur `business_entity`. De nouveaux objets peuvent être créés avec `business_entity` ou `company` : la valeur fournie sera celle qui sera renvoyée lors de la lecture. Pour faciliter la préparation, nous vous recommandons de faire basculer les écritures vers la nouvelle valeur (par exemple, lors de la création d’un nouveau titulaire de carte, définissez `type` sur `company`), et de gérer l’une ou l’autre des valeurs en lecture. ## Modifications des API ### Autorisation - `held_amount` a été remplacé par `amount`. `amount` correspondra toujours au montant total autorisé ou refusé pour la capture, dans la devise du titulaire de la carte. Contrairement à `held_amount`, il ne sera pas remis à zéro lors de la capture. - Le montant d’une autorisation peut être obtenu en calculant la somme de ses montants [balance_transactions](https://docs.stripe.com/api/issuing/authorizations/object.md#issuing_authorization_object-balance_transactions). - Remplacement du nom `held_currency` par `currency`. - Remplacement de `authorized_amount` par `merchant_amount`. `merchant_amount` sera toujours la somme totale de capture autorisée ou refusée dans la devise du marchand. Contrairement à `authorized_amount`, `merchant_amount` peut être réduit par une annulation. - Remplacement du nom `authorized_currency` par `merchant_currency`. - Remplacement du nom `held_amount` par `amount` dans l’endpoint [approuver une autorisation](https://docs.stripe.com/api/issuing/authorizations/approve.md). - Ajout du hachage [pending_request](https://docs.stripe.com/api/issuing/authorizations/object.md#issuing_authorization_object-pending_request). Celui-ci sera uniquement rempli lors d’une requête de [webhook synchrone](https://docs.stripe.com/issuing/controls/real-time-authorizations.md) pour les autorisations en temps réel. - Remplacement de `pending_held_amount` par `pending_request.amount`. - Remplacement de `pending_authorized_amount` par `pending_request.merchant_amount`. - Remplacement de `is_held_amount_controllable` par `pending_request.is_amount_controllable`. - Renommer les attributs des hachages dans [request_history](https://docs.stripe.com/api/issuing/authorizations/object.md#issuing_authorization_object-request_history) : - Remplacement du nom `request_history.held_amount` par `request_history.amount`. - Remplacement du nom `request_history.held_currency` par `request_history.currency`. - Remplacement du nom `request_history.authorized_amount` par `request_history.merchant_amount`. - Remplacement du nom `request_history.authorized_currency` par `request_history.merchant_currency`. - Suppression de `request_history.violated_authorization_controls`. - Fin de la prise en charge de plusieurs valeurs pour [request_history.reason](https://docs.stripe.com/api/issuing/authorizations/object.md#issuing_authorization_object-request_history-reason). - Consolidation de `authentication_failed`, `incorrect_cvc` et `incorrect_expiry` dans `verification_failed`. Pour plus d’informations, utilisez [authorization.verification_data](https://docs.stripe.com/api/issuing/authorizations/object.md#issuing_authorization_object-verification_data). - Remplacement de `account_compliance_disabled` et de `account_inactive` par `account_disabled`. - Remplacement de `authorization_controls` par `spending_controls` à des fins de cohérence avec les nouveaux noms des attributs des ressources [Card](https://docs.stripe.com/api/issuing/cards/object.md#issuing_card_object-spending_controls) et [Cardholder](https://docs.stripe.com/api/issuing/cardholders/object.md#issuing_cardholder_object-spending_controls). - Fin de la prise en charge de l’énumération `verification_data.authentication` au profit du hachage `verification_data.three_d_secure`, plus précis. - `three_d_secure.result`, qui remplace l’`authentification`, contient plus de valeurs qu’auparavant. Consultez un aperçu complet des [nouvelles valeurs](https://docs.stripe.com/issuing/3d-secure.md#prevent-fraud). - Cet attribut n’est visible que par les utilisateurs disposant de la fonctionnalité 3D Secure. - Remplacement du nom `verification_data.address_zip_check` par [verification_data.address_postal_code_check](https://docs.stripe.com/api/issuing/authorizations/object.md#issuing_authorization_object-verification_data-address_postal_code_check). - Remplacement du nom de l’attribut `wallet_provider` par `wallet`. ### Transaction - Suppression des valeurs [type](https://docs.stripe.com/api/issuing/transactions/object.md#issuing_transaction_object-type) suivantes en raison de leur caractère peu courant et de la possibilité de les représenter autrement : - `cash_withdrawal` (désormais `capture`) - `refund_reversal` (désormais `refund` avec un `amount` négatif) - `dispute` et `dispute_loss`. Une API Disputes est en cours de développement. - Nous avons cessé de créer une seconde `Transaction` de type `dispute` pour représenter le mouvement d’argent d’un `Dispute` abouti. À la place, nous ajoutons directement les `balance_transactions` au `Dispute`. - Par conséquent, aucun événement `issuing_transaction.created` ne sera créé pour un transfert de fonds `Dispute`. Cela sera remplacé par un nouvel événement qui envoie `Dispute` mis à jour avec `balance_transactions`. - Suppression du paramètre de requête `dispute` de l’endpoint [énumérer toutes les transactions](https://docs.stripe.com/api/issuing/transactions/list.md). - Restriction du paramètre de requête `settlement` de l’endpoint [énumérer toutes les transactions](https://docs.stripe.com/api/issuing/transactions/list.md) aux utilisateurs de la fonctionnalité Settlement. - Ajout de `purchase_details` pour les données de transaction détaillées. ### Titulaire de la carte - Suppression de l’attribut `is_default`. Par conséquent, `cardholder` devient un paramètre obligatoire lors de la création de carte. L’endpoint [énumérer tous les titulaires de carte](https://docs.stripe.com/api/issuing/cardholders/list.md) n’accepte plus `is_default` comme paramètre de requête. - Remplacement du [type](https://docs.stripe.com/api/issuing/cardholders/object.md#issuing_cardholder_object-type) `business_entity` par `company` par souci de cohérence avec les hachages qui contiennent des informations supplémentaires. - Suppression de `billing.name`, qui est toujours identique à l’attribut `name` de niveau supérieur dans la ressource. - Remplacement du nom `authorization_controls` par [spending_controls](https://docs.stripe.com/api/issuing/cardholders/object.md#issuing_cardholder_object-spending_controls). ### Carte - Suppression des états de carte `lost` et `stolen`. Ces états sont représentés par [canceled](https://docs.stripe.com/api/issuing/cards/object.md#issuing_card_object-status) accompagné d’une [cancellation_reason](https://docs.stripe.com/api/issuing/cards/object.md#issuing_card_object-cancellation_reason) facultative. - Remplacement du nom `authorization_controls` par [spending_controls](https://docs.stripe.com/api/issuing/cards/object.md#issuing_card_object-spending_controls). - Remplacement du nom des valeurs [replacement_reason](https://docs.stripe.com/api/issuing/cards/object.md#issuing_card_object-replacement_reason) : - `loss` devient `lost` - `theft` devient `stolen` - `damage` devient `damaged` - `expiration` devient `expired` - `name` supprimé. Reportez-vous plutôt à [cardholder.name](https://docs.stripe.com/api/issuing/cards/object.md#issuing_card_object-cardholder). - Remplacement du nom de l’énumération `shipping.speed` par [shipping.service](https://docs.stripe.com/api/issuing/cards/object.md#issuing_card_object-shipping-service). Le nom de la valeur `overnight` est remplacé par `priority`. - Ajout de [replaced_by](https://docs.stripe.com/api/issuing/cards/object.md#issuing_card_object-replaced_by) pour désigner la carte ayant remplacé la carte actuelle. - Remplacement du nom de `authorization_controls` par [spending_controls](https://docs.stripe.com/api/issuing/cards/object.md#issuing_card_object-spending_controls) et suppression de `max_approvals`, `max_amount` et `currency`. Nous vous conseillons d’ajouter des limites basées sur `amount` pour contrôler les dépenses de manière plus précise. - `merchant_data.url` n’est disponible que pour les utilisateurs disposant de la fonctionnalité 3D Secure. - `pin` n’est disponible que pour les utilisateurs disposant de la fonctionnalité de gestion du code PIN. - L’endpoint [énumérer toutes les cartes](https://docs.stripe.com/api/issuing/cards/list.md) n’accepte plus les paramètres `source` et `name`. - L’endpoint [récupérer les informations de la carte](https://docs.stripe.com/api/issuing/cards/retrieve_details.md) n’est plus pris en charge. Dorénavant, [number](https://docs.stripe.com/api/issuing/cards/object.md#issuing_card_object-number) et [cvc](https://docs.stripe.com/api/issuing/cards/object.md#issuing_card_object-cvc) peuvent être développés à partir de l’endpoint [renvoyer](https://docs.stripe.com/api/issuing/cards/retrieve.md). ### Litiges - Remplacement du nom `disputed_transaction` par `transaction`. - Ajout de `balance_transactions`, qui contient l’ensemble des [BalanceTransactions](https://docs.stripe.com/api/balance_transactions.md) associées à un `Dispute`. - Chaque `BalanceTransaction` dispose d’objets `type`, `source`, `description` et `reporting_category` correspondant au `Dispute` sur Issuing, comme suit : - `type: "issuing_dispute"` - `source: "idp_1FMjf1GprvsjVv9gffmDmLGx"` - `description: "Issuing dispute"` - `reporting_category: "Issuing Dispute"` - Lorsqu’un `Dispute` aboutit, nous envoyons un nouvel événement, `issuing_dispute.funds_reinstated`, accompagné du `Dispute` mis à jour et de la nouvelle `BalanceTransaction`. ### Événements - Les événements ne sont visibles que par les utilisateurs disposant de la fonctionnalité de règlement : - `issuing_settlement.created` - `issuing_settlement.updated` ### Soldes - Le solde `issuing.pending` a été supprimé de l’objet [Balance](https://docs.stripe.com/api/balance/balance_object.md#balance_object). Reportez-vous plutôt au solde [issuing.available](https://docs.stripe.com/api/balance/balance_object.md#balance_object-issuing-available).