Guide de migration de 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 d’assistance.
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
paramount
.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
parcurrency
. - Remplacement de
authorized_amount
parmerchant_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
parmerchant_currency
. - Remplacement du nom
held_amount
paramount
dans l’endpoint approuver une authorization. - 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
parpending_request.amount
. - Remplacement de
pending_authorized_amount
parpending_request.merchant_amount
. - Remplacement de
is_held_amount_controllable
parpending_request.is_amount_controllable
.
- Remplacement de
- Changement du nom des attributs des hachages de request_history :
- Remplacement du nom
request_history.held_amount
parrequest_history.amount
. - Remplacement du nom
request_history.held_currency
parrequest_history.currency
. - Remplacement du nom
request_history.authorized_amount
parrequest_history.merchant_amount
. - Remplacement du nom
request_history.authorized_currency
parrequest_history.merchant_currency
. - Suppression de
request_history.violated_authorization_controls
.
- Remplacement du nom
- Fin de la prise en charge de plusieurs valeurs pour request_history.reason.
- Consolidation de
authentication_failed
,incorrect_cvc
etincorrect_expiry
dansverification_failed
. Pour plus d’informations, utilisez authorization.verification_data. - Remplacement de
account_compliance_disabled
et deaccount_inactive
paraccount_disabled
. - Remplacement de
authorization_controls
parspending_controls
à des fins de cohérence avec les nouveaux noms des attributs des ressources Card et Cardholder.
- Consolidation de
- Fin de la prise en charge de l’énumération
verification_data.authentication
au profit du hachageverification_data.three_d_secure
, plus précis.- Augmentation du nombre de valeurs de
three_d_secure.result
, qui remplaceauthentication
. 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.
- Augmentation du nombre de valeurs de
- Remplacement du nom
verification_data.address_zip_check
par verification_data.address_postal_code_check. - Remplacement du nom de l’attribut
wallet_provider
parwallet
.
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ésormaiscapture
)refund_reversal
(désormaisrefund
avec unamount
négatif)dispute
etdispute_loss
. Une API Disputes est en cours de développement.
- Suppression de la création d’une deuxième
Transaction
de typedispute
pour la représentation d’un transfert de fonds deDispute
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 fondsDispute
. Cela sera remplacé par un nouvel événement qui envoieDispute
mis à jour avecbalance_transactions
.
- Par conséquent, aucun événement
- Suppression du paramètre de requête
dispute
du endpoint énumérer toutes les transactions. - Restriction du paramètre de requête
settlement
du 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 plusis_default
comme paramètre de requête. - Remplacement du type
business_entity
parcompany
par souci de cohérence avec les hachages qui contiennent des informations supplémentaires. - Suppression de
billing.name
, qui est toujours identique à l’attributname
de niveau supérieur dans la ressource. - Remplacement du nom
authorization_controls
par spending_controls.
Carte
- Suppression des états de carte
lost
etstolen
. Ces états sont représentés par canceled accompagné d’une cancellation_reason facultative. - Remplacement du nom
authorization_controls
par spending_controls.
- Remplacement du nom des valeurs replacement_reason :
loss
devientlost
theft
devientstolen
damage
devientdamaged
expiration
devientexpired
- Suppression de
name
. Consultez plutôt cardholder.name. - Remplacement du nom de l’énumération
shipping.speed
par shipping.service. Le nom de la valeurovernight
est remplacé parpriority
. - 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 demax_approvals
,max_amount
etcurrency
. Nous vous conseillons d’ajouter des limites basées suramount
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
etname
. - 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 du endpoint renvoyer.
Litiges
- Remplacement du nom
disputed_transaction
partransaction
. - Ajout de
balance_transactions
, qui contient l’ensemble des BalanceTransactions associées à unDispute
.- Chaque
BalanceTransaction
dispose d’objetstype
,source
,description
etreporting_category
correspondant auDispute
sur Issuing, comme suit :type: "issuing_dispute"
source: "idp_1FMjf1GprvsjVv9gffmDmLGx"
description: "Issuing dispute"
reporting_category: "Issuing Dispute"
- Chaque
- Lorsqu’un
Dispute
aboutit, nous envoyons un nouvel événement,issuing_dispute.funds_reinstated
, accompagné duDispute
mis à jour et de la nouvelleBalanceTransaction
.
É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é retiré de l’objet Balance. Veuillez consulter le solde issuing.available.