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

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 durch amount ersetzt.amount ist immer der autorisierte oder abgelehnte Gesamtbetrag zur Erfassung in der Währung der Karteninhaberin/des Karteninhabers. Im Gegensatz zu held_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 in currency umbenannt.
• authorized_amount durch merchant_amount ersetzt. merchant_amount ist immer der autorisierte oder abgelehnte Gesamtbetrag zur Erfassung in der Währung der Händler. Im Gegensatz zu authorized_amount kann merchant_amount durch Stornos reduziert werden.
• authorized_currency in merchant_currency umbenannt.
• held_amount in amount umbenannt im Endpoint zum Genehmigen einer Autorisierung.
• Hash pending_request hinzugefügt. Wird nur bei einer synchronen Webhook-Anfrage für Autorisierungen in Echtzeit ausgefüllt.
  • pending_held_amount durch pending_request.amount ersetzt.
  • pending_authorized_amount durch pending_request.merchant_amount ersetzt.
  • is_held_amount_controllable durch pending_request.is_amount_controllable ersetzt.
• Attribute von Hashes in request_history wurden umbenannt:
  • request_history.held_amount in request_history.amount umbenannt.
  • request_history.held_currency in request_history.currency umbenannt.
  • request_history.authorized_amount in request_history.merchant_amount umbenannt.
  • request_history.authorized_currency in request_history.merchant_currency umbenannt.
  • request_history.violated_authorization_controls entfernt.
• Mehrere Werte für request_history.reason eingestellt.
  • authentication_failed, incorrect_cvc und incorrect_expiry zu verification_failed zusammengefasst. Mehr Details finden Sie unter authorization.verification_data.
  • account_compliance_disabled und account_inactive durch account_disabled ersetzt.
  • authorization_controls wurde in spending_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 Hashes verification_data.three_d_secure eingestellt.
  • three_d_secure.result, das authentication 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 in wallet 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 (jetzt capture)
  • refund_reversal (jetzt refund mit negativen amount)
  • dispute und dispute_loss. Eine Disputes API ist in Entwicklung.
• Es wird keine zweite Transaction vom Typ dispute mehr erstellt, die die Geldbewegungen einer positiv entschiedenen Dispute darstellt. Stattdessen werden wir balance_transactions direkt zu Dispute hinzufügen.
  • Dementsprechend wird es kein Ereignis vom Typ issuing_transaction.created für Geldbewegungen im Rahmen einer Dispute geben, sondern ein neues Ereignis, mit dem die aktualisierte Dispute mit balance_transactions übermittelt wird.
• 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 ist cardholder ein erforderlicher Parameter bei der Erstellung einer neuen Karte. Der Endpoint zum Auflisten aller Karteninhaber/innen akzeptiert is_default nicht mehr als Abfrageparameter.
• type von business_entity in company umbenannt, um Abgleich mit Hashes zu verbessern, die zusätzliche Informationen enthalten.
• billing.name entfernt, da er immer mit dem übergeordneten Attribut name der Ressource identisch ist.
• authorization_controls in spending_controls umbenannt.

Karte

• Kartenstatus lost und stolen entfernt. Sie werden als canceled mit einem optionalen cancellation_reason dargestellt.
• authorization_controls wurden in spending_controls umbenannt.

curl https://api.stripe.com/v1/issuing/cards/ic_1CoYuRKEl2ztzE5GIEDjQiUI \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -d "status=lost"

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

• Werte für replacement_reason umbenannt:
  • loss in lost
  • theft in stolen
  • damage in damaged
  • expiration in expired
• name wurde entfernt. Verwenden Sie stattdessen cardholder.name.
• Enum shipping.speed wurde in shipping.service umbenannt. Der Wert overnight wurde in priority umbenannt.
• replaced_by wurde hinzugefügt, um auf die Karte zu verweisen, die die aktuelle Karte ersetzt hat.
• authorization_controls wurde in spending_controls umbenannt und max_approvals, max_amount und currency wurden entfernt. Wir empfehlen die Verwendung von amount-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 und name 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 in transaction umbenannt.
• balance_transactions hinzugefügt. Enthält alle mit einer Dispute verknüpften BalanceTransactions.
  • Jede BalanceTransaction erhält entsprechend einer Dispute in Issuing neue Werte für type, source, description und reporting_category:
    • type: "issuing_dispute"
    • source: "idp_1FMjf1GprvsjVv9gffmDmLGx"
    • description: "Issuing dispute"
    • reporting_category: "Issuing Dispute"
• Wir übermitteln ein Ereignis vom Typ issuing_dispute.funds_reinstated mit der aktualisierten Dispute und der neuen BalanceTransaction, wenn die Dispute 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.