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.

À compter du 1er mars 2021, nous ne prenons plus en charge la version bêta de l’API. Vous trouverez ci-dessous un résumé des changements apportés à l’API pour vous aider à migrer. Si vous avez des questions, merci de contacter le service Support.

Compatibilité

Mise en garde

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

Remplacement de held_amount par amount. amount sera toujours la somme totale de capture autorisée ou refusée dans la devise du titulaire de carte. Contrairement à held_amount, sa valeur ne sera pas de zéro lors de la capture.
- Le montant d’une autorisation peut être obtenu en calculant la somme de ses montants 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.
Ajout du hachage pending_request. Celui-ci sera uniquement rempli lors d’une requête de webhook synchrone 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 :
- 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.
- Consolidation de authentication_failed, incorrect_cvc et incorrect_expiry dans verification_failed. Pour plus d’informations, utilisez authorization.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 et Cardholder.
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.
- Augmentation du nombre de valeurs de three_d_secure.result, qui remplace authentication. Vous trouverez une présentation détaillée des nouvelles valeurs ici.
- 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.
Remplacement du nom de l’attribut wallet_provider par wallet.

Transaction

Suppression des valeurs 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.
Suppression de la création d’une deuxième Transaction de type dispute pour la représentation d’un transfert de fonds de Dispute abouti. balance_transactions sera dorénavant ajouté directement à 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.
Restriction du paramètre de requête settlement de l’endpoint énumérer toutes les transactions 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 n’accepte plus is_default comme paramètre de requête.
Remplacement du 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.

Carte

Suppression des états de carte lost et stolen. Ces états sont représentés par canceled accompagné d’une cancellation_reason facultative.
Remplacement du nom authorization_controls par spending_controls.

Avant

Après

Command Line
curl https://api.stripe.com/v1/issuing/cards/ic_1CoYuRKEl2ztzE5GIEDjQiUI \
  -usk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -d "status=lost"

Command Line
curl https://api.stripe.com/v1/issuing/cards/ic_1CoYuRKEl2ztzE5GIEDjQiUI \
  -usk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -d "status=canceled" \
  -d "cancellation_reason=lost"

Remplacement du nom des valeurs replacement_reason :
- loss devient lost
- theft devient stolen
- damage devient damaged
- expiration devient expired
Suppression de name. Consultez plutôt cardholder.name.
Remplacement du nom de l’énumération shipping.speed par shipping.service. Le nom de la valeur overnight est remplacé par priority.
Ajout de replaced_by pour désigner la carte ayant remplacé la carte actuelle.
Remplacement du nom de authorization_controls par 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 n’accepte plus les paramètres source et name.
L’endpoint récupérer les informations de la carte n’est plus pris en charge. Dorénavant, number et cvc peuvent être développés à partir de l’endpoint renvoyer.

Litiges

Remplacement du nom disputed_transaction par transaction.
Ajout de balance_transactions, qui contient l’ensemble des BalanceTransactions 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.pendinga été retiré de l’objet Balance. Veuillez consulter le solde issuing.available.