# Migrationsleitfaden für die Beta-Version von Issuing

Erfahren Sie, wie Sie von der Beta-Version von Issuing migrieren können.

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 der Migration haben wir im Folgenden alle Änderungen an der API aufgeführt. Bei Fragen wenden Sie sich an den [Support](mailto:support-issuing@stripe.com).

## Kompatibilität

> 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](https://docs.stripe.com/api/issuing/cardholders/object.md#issuing_cardholder_object-type) `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](https://docs.stripe.com/api/issuing/authorizations/object.md#issuing_authorization_object-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](https://docs.stripe.com/api/issuing/authorizations/approve.md).
- Hash [pending_request](https://docs.stripe.com/api/issuing/authorizations/object.md#issuing_authorization_object-pending_request) hinzugefügt. Wird nur bei einer [synchronen Webhook](https://docs.stripe.com/issuing/controls/real-time-authorizations.md)-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](https://docs.stripe.com/api/issuing/authorizations/object.md#issuing_authorization_object-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](https://docs.stripe.com/api/issuing/authorizations/object.md#issuing_authorization_object-request_history-reason) eingestellt.
  - `authentication_failed`, `incorrect_cvc` und `incorrect_expiry` zu `verification_failed` zusammengefasst. Mehr Details finden Sie unter [authorization.verification_data](https://docs.stripe.com/api/issuing/authorizations/object.md#issuing_authorization_object-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](https://docs.stripe.com/api/issuing/cards/object.md#issuing_card_object-spending_controls) und [Cardholder](https://docs.stripe.com/api/issuing/cardholders/object.md#issuing_cardholder_object-spending_controls) 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 über die [neuen Werte](https://docs.stripe.com/issuing/3d-secure.md#prevent-fraud) 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](https://docs.stripe.com/api/issuing/authorizations/object.md#issuing_authorization_object-verification_data-address_postal_code_check) umbenannt.
- Attribut `wallet_provider` in `wallet` umbenannt.

### Transaktion

- Die folgenden [type](https://docs.stripe.com/api/issuing/transactions/object.md#issuing_transaction_object-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](https://docs.stripe.com/api/issuing/transactions/list.md) entfernt.
- Abfrageparameter `settlement` vom Endpoint zum [Auflisten aller Transaktionen](https://docs.stripe.com/api/issuing/transactions/list.md) 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](https://docs.stripe.com/api/issuing/cardholders/list.md) akzeptiert `is_default` nicht mehr als Abfrageparameter.
- [type](https://docs.stripe.com/api/issuing/cardholders/object.md#issuing_cardholder_object-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](https://docs.stripe.com/api/issuing/cardholders/object.md#issuing_cardholder_object-spending_controls) umbenannt.

### Karte

- Kartenstatus `lost` und `stolen` entfernt. Sie werden als [canceled](https://docs.stripe.com/api/issuing/cards/object.md#issuing_card_object-status) mit einem optionalen [cancellation_reason](https://docs.stripe.com/api/issuing/cards/object.md#issuing_card_object-cancellation_reason) dargestellt.
- `authorization_controls` wurden in [spending_controls](https://docs.stripe.com/api/issuing/cards/object.md#issuing_card_object-spending_controls) umbenannt.

- Werte für [replacement_reason](https://docs.stripe.com/api/issuing/cards/object.md#issuing_card_object-replacement_reason) umbenannt:
  - `loss` in `lost`
  - `theft` in `stolen`
  - `damage` in `damaged`
  - `expiration` in `expired`
- `name` wurde entfernt. Verwenden Sie stattdessen [cardholder.name](https://docs.stripe.com/api/issuing/cards/object.md#issuing_card_object-cardholder).
- Enum `shipping.speed` wurde in [shipping.service](https://docs.stripe.com/api/issuing/cards/object.md#issuing_card_object-shipping-service) umbenannt. Der Wert `overnight` wurde in `priority` umbenannt.
- [replaced_by](https://docs.stripe.com/api/issuing/cards/object.md#issuing_card_object-replaced_by) wurde hinzugefügt, um auf die Karte zu verweisen, die die aktuelle Karte ersetzt hat.
- `Authorization_controls` wurde in [spending_controls](https://docs.stripe.com/api/issuing/cards/object.md#issuing_card_object-spending_controls) umbenannt und `max_approvals`, `max_amount` und `Währung` wurden entfernt. Wir empfehlen die Verwendung von `betragsbasierten` Limits für eine genauere 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](https://docs.stripe.com/api/issuing/cards/list.md) akzeptiert die Parameter `source` und `name` nicht mehr.
- Der Endpoint zum [Abrufen der Kartendetails](https://docs.stripe.com/api/issuing/cards/retrieve_details.md) wurde eingestellt. Stattdessen können [number](https://docs.stripe.com/api/issuing/cards/object.md#issuing_card_object-number) und [cvc](https://docs.stripe.com/api/issuing/cards/object.md#issuing_card_object-cvc) über den Endpoint zum [Abrufen](https://docs.stripe.com/api/issuing/cards/retrieve.md) erweitert werden.

### Zahlungsanfechtungen

- `disputed_transaction` in `transaction` umbenannt.
- `balance_transactions` hinzugefügt. Enthält alle mit einer `Dispute` verknüpften [BalanceTransactions](https://docs.stripe.com/api/balance_transactions.md).
  - 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](https://docs.stripe.com/api/balance/balance_object.md#balance_object)-Objekt entfernt. Beziehen Sie sich stattdessen auf das [issuing.available](https://docs.stripe.com/api/balance/balance_object.md#balance_object-issuing-available)-Guthaben.