Migrationsleitfaden für die Beta-Version von Issuing
Stripe Issuing ist nun für alle US-Unternehmen verfügbar. Mit der Einstellung unserer Beta-Version haben wir die Preise und die Änderungen an unserer API veröffentlicht, die Funktionen und Aktualisierungen zur langfristigen Weiterentwicklung der API enthalten. Abhängig von Ihrer Integration sind einige dieser API-Änderungen von grundlegender Bedeutung. Schauen Sie sich daher die einzelnen Punkte in diesem Leitfaden genau an.
Wir werden die Beta-API zum 1. März 2021 einstellen. Zur Unterstützung bei der Migration haben wir im Folgenden alle Änderungen an der API aufgeführt. Bei Fragen wenden Sie sich bitte an den Support.
Kompatibilität
Vorsicht
Wie bereits in den einzelnen Abschnitten erwähnt, empfehlen wir, bis zur offiziellen Umstellung sowohl die alte als auch die neue API zu unterstützen. Außerdem sollten Sie vor der Umstellung auf Ihr Hauptkoto ein neues Issuing-Konto erstellen, um die neue API vorab zu testen.
Attribute
Für Beta-Nutzer/innen sind derzeit sowohl die älteren als auch die neuen Attribute für alle Issuing-Objekte verfügbar. Umbenannte Attribute beziehen sich auf den gleichen Backend-Wert wie ihre älteren Entsprechungen. Sobald die Beta-Version eingestellt wird, sind nur noch die neuen Attribute verfügbar.
Zur Vorbereitung empfehlen wir, den Lesemodus zu wechseln, um bis zum erfolgreichen Wechsel zur neuen API sowohl das alte als auch das neue Attribut zu unterstützen.
Parameter
Für umbenannte Parameter kann entweder der ältere oder der neue Name verwendet werden, jedoch nicht beide. Sobald die Beta-Version eingestellt wird, werden nur noch die neuen Parameter akzeptiert.
Zur Vorbereitung empfehlen wir, den Schreibmodus zu wechseln, um bis zum erfolgreichen Wechsel zur neuen API sowohl den alten als auch den neuen Parameter zu unterstützen.
Enum
Die Umstellung auf neue Enum-Werte gestaltet sich etwas komplizierter. Neue Werte können zwar geschrieben und zurückgelesen werden, aber alte, bestehende Werte werden bis zur offiziellen Einstellung der Beta-Version nach wie vor zurückgegeben.
Beispiel: Der Karteninhaber-Typ business_entity
wurde in company
umbenannt. Bestehende Karteninhaber-Objekte zeigen weiterhin den alten Wert business_entity
an. Neue Objekte können mit business_entity
oder company
erstellt werden, und der jeweils angegebene Wert wird beim Zurücklesen zurückgegeben.
Als Vorbereitung empfehlen wir, den Lesemodus auf den neuen Wert umzustellen (z. B. bei der Erstellung einer neuen Karteninhaberin/eines neuen Karteninhabers type
auf company
festlegen) und beide Werte im Lesemodus zu verarbeiten.
API-Änderungen
Autorisierung
held_amount
durchamount
ersetzt.amount
ist immer der autorisierte oder abgelehnte Gesamtbetrag zur Erfassung in der Währung der Karteninhaberin/des Karteninhabers. Im Gegensatz zuheld_amount
wird der Betrag bei der Erfassung nicht zu null.- Der von einer Autorisierung zurückgehaltene Betrag kann durch die Summe der Beträge der balance_transactions bestimmt werden.
held_currency
incurrency
umbenannt.authorized_amount
durchmerchant_amount
ersetzt.merchant_amount
ist immer der autorisierte oder abgelehnte Gesamtbetrag zur Erfassung in der Währung der Händler. Im Gegensatz zuauthorized_amount
kannmerchant_amount
durch Stornos reduziert werden.authorized_currency
inmerchant_currency
umbenannt.held_amount
inamount
umbenannt im Endpoint approve an authorization.- Hash pending_request hinzugefügt. Wird nur bei einer synchronen Webhook-Anfrage für Autorisierungen in Echtzeit ausgefüllt.
pending_held_amount
durchpending_request.amount
ersetzt.pending_authorized_amount
durchpending_request.merchant_amount
ersetzt.is_held_amount_controllable
durchpending_request.is_amount_controllable
ersetzt.
- Umbenannte Attribute von Hashes in request_history:
request_history.held_amount
inrequest_history.amount
umbenannt.request_history.held_currency
inrequest_history.currency
umbenannt.request_history.authorized_amount
inrequest_history.merchant_amount
umbenannt.request_history.authorized_currency
inrequest_history.merchant_currency
umbenannt.request_history.violated_authorization_controls
entfernt.
- Mehrere Werte für request_history.reason eingestellt.
authentication_failed
,incorrect_cvc
undincorrect_expiry
zuverification_failed
zusammengefasst. Mehr Details finden Sie unter authorization.verification_data.account_compliance_disabled
undaccount_inactive
durchaccount_disabled
ersetzt.authorization_controls
wurde inspending_controls
umbenannt, um die Konsistenz mit den umbenannten Attributen in den Ressourcen Card und Cardholder sicherzustellen.
- Die Enum
verification_data.authentication
wurde zu Gunsten des eindeutigeren Hashesverification_data.three_d_secure
eingestellt.three_d_secure.result
, dasauthentication
ersetzt, enthält mehr Werte als zuvor. Eine vollständige Übersicht der neuen Werte finden Sie hier.- Dieses Attribut ist nur für Nutzer/innen sichtbar, die für die Funktion „3D Secure“ registriert sind.
verification_data.address_zip_check
in verification_data.address_postal_code_check umbenannt.- Attribut
wallet_provider
inwallet
umbenannt.
Transaktion
- Die folgenden type-Werte wurden entfernt, da sie nicht häufig vorkommen und auch auf andere Weise dargestellt werden können:
cash_withdrawal
(jetztcapture
)refund_reversal
(jetztrefund
mit negativenamount
)dispute
unddispute_loss
. Eine Disputes API ist in Entwicklung.
- Es wird keine zweite
Transaction
vom Typdispute
mehr erstellt, die die Geldbewegungen einer positiv entschiedenenDispute
darstellt. Stattdessen werden wirbalance_transactions
direkt zuDispute
hinzufügen.- Dementsprechend wird es kein Ereignis vom Typ
issuing_transaction.created
für Geldbewegungen im Rahmen einerDispute
geben, sondern ein neues Ereignis, mit dem die aktualisierteDispute
mitbalance_transactions
übermittelt wird.
- Dementsprechend wird es kein Ereignis vom Typ
- Abfrageparameter
dispute
aus dem Endpoint zum Auflisten aller Transaktionen entfernt. - Abfrageparameter
settlement
vom Endpoint zum Auflisten aller Transaktionen auf Nutzer/innen der Funktion „Zahlungsabwicklung“ eingeschränkt. purchase_details
für erweiterte Transaktionsdaten hinzugefügt.
Karteninhaber/in
- Attribut
is_default
entfernt. Somit istcardholder
ein erforderlicher Parameter bei der Erstellung einer neuen Karte. Der Endpoint zum Auflisten aller Karteninhaber/innen akzeptiertis_default
nicht mehr als Abfrageparameter. - type von
business_entity
incompany
umbenannt, um Abgleich mit Hashes zu verbessern, die zusätzliche Informationen enthalten. billing.name
entfernt, da er immer mit dem übergeordneten Attributname
der Ressource identisch ist.authorization_controls
in spending_controls umbenannt.
Karte
- Kartenstatus
lost
undstolen
entfernt. Sie werden als canceled mit einem optionalen cancellation_reason dargestellt. authorization_controls
in spending_controls umbenannt.
- Werte für replacement_reason umbenannt:
loss
inlost
theft
instolen
damage
indamaged
expiration
inexpired
name
entfernt. Verwenden Sie stattdessen cardholder.name.- Enum
shipping.speed
in shipping.service umbenannt. Der Wertovernight
wurde inpriority
umbenannt. - replaced_by hinzugefügt, um auf die Karte zu verweisen, die die aktuelle Karte ersetzt hat.
authorization_controls
in spending_controls umbenannt undmax_approvals
,max_amount
undcurrency
entfernt. Wir empfehlen die Verwendung vonamount
-basierten Begrenzungen zur genaueren Kontrolle der Kartenausgaben.merchant_data.url
ist nur für Nutzer/innen verfügbar, die sich für die Funktion „3D Secure“ registriert haben.pin
ist nur für Nutzer/innen verfügbar, die sich für die Funktion „PIN-Verwaltung“ registriert haben.- Der Endpoint zum Auflisten aller Karten akzeptiert die Parameter
source
undname
nicht mehr. - Der Endpoint zum Abrufen der Kartendetails wurde eingestellt. Stattdessen können number und cvc über den Endpoint zum Abrufen erweitert werden.
Zahlungsanfechtungen
disputed_transaction
intransaction
umbenannt.balance_transactions
hinzugefügt. Enthält alle mit einerDispute
verknüpften BalanceTransactions.- Jede
BalanceTransaction
erhält entsprechend einerDispute
in Issuing neue Werte fürtype
,source
,description
undreporting_category
:type: "issuing_dispute"
source: "idp_1FMjf1GprvsjVv9gffmDmLGx"
description: "Issuing dispute"
reporting_category: "Issuing Dispute"
- Jede
- Wir übermitteln ein Ereignis vom Typ
issuing_dispute.funds_reinstated
mit der aktualisiertenDispute
und der neuenBalanceTransaction
, wenn dieDispute
positiv entschieden wurde.
Ereignisse
- Die folgenden Ereignisse sind auf Nutzer/innen beschränkt, die sich für die Funktion „Zahlungsabwicklung“ registriert haben.
issuing_settlement.created
issuing_settlement.updated
Guthaben
- Das
issuing.pending
-Guthaben wurde aus dem Balance-Objekt entfernt. Bitte verwenden Sie stattdessen das issuing.available-Guthaben.