# Adressvalidierung physischer Karten Erfahren Sie, wie Sie Funktionen zur Adressvalidierung für physische Karten aktivieren und verwalten. Stripe Issuing benötigt genaue und korrekt formatierte Versandadressen, um eine erfolgreiche Zustellung physischer Karten an den/die vorgesehene/n Empfänger/in zu gewährleisten. An ungültige Adressen gesendete Karten werden an Stripe zurückgesendet. Der Zustellungsversuch und die endgültige Rückgabe können mehr als 2 Wochen in Anspruch nehmen. Zurückgegebene Karten können zu betrieblichen Belastungen führen, Ihre Gesamtkosten erhöhen und den Erhalt Ihrer physischen Karten durch Ihre Karteninhaber/innen verzögern. Um Ihren Zustellungserfolg zu maximieren, verfügt die Cards API von Stripe über eine integrierte Adressnormalisierung und -validierung. Stripe vergleicht die von Ihnen angegebene Versandadresse mit der Adressdatenbank eines Drittanbieters und ermittelt oder behebt Probleme mit der Adresse. ## Normalisierung der Adresse Durch die Normalisierung wird sichergestellt, dass Ihre Adressen den Standards des Landes der Sendung entsprechen, wobei gleichzeitig offensichtliche Fehler in Ihren Adressen korrigiert werden. Beispiele für die Normalisierung sind: ### Adressstandardisierung zur Sicherstellung der korrekten Formatierung ```json // Before "shipping": { "address": { "line1": "354 Oyster Point Blvd South San Francisco, CA 94080", // incorrectly formatted line1 "city": "South San Francisco", "postal_code": "94080", "state": "CA", "country": "US" } } // After "shipping": { "address": { "line1": "354 OYSTER POINT BLVD", "city": "SOUTH SAN FRANCISCO", "postal_code": "94080", "state": "CA", "country": "US" } } ``` ### Adresskorrektur, um Korrekturen anzuwenden, die durch den Abgleich mit einer bestehenden validierten Adresse entstanden sind ```json // Before "shipping": { "address": { "line1": "354 Oyster Point", "city": "South San Francisco", "postal_code": "94080", "state": "NM", // incorrect state with an available correction "country": "US" } } // After "shipping": { "address": { "line1": "354 OYSTER POINT BLVD", // added BLVD suffix "city": "SOUTH SAN FRANCISCO", "postal_code": "94080", "state": "CA", // corrected state "country": "US" } } ``` Die normalisierte Adresse ist im Hash der [Adressvalidierung](https://docs.stripe.com/api/issuing/cards/object.md#issuing_card_object-shipping-address_validation) enthalten, der nach erfolgreicher Erstellung einer physischen Karte oder Aktualisierung der Versandadresse einer Karte bei aktivierter Adressnormalisierung zurückgegeben wird. ### Validierung der Musteradresse ```json "shipping": { // address supplied during card creation "address": { "line1": "354 Oyster Point Blvd South San Francisco, TX 94080", "city": "South San Francisco", "postal_code": "94080", "state": "TX", "country": "US" }, // address validation hash "address_validation": { // the normalized address"normalized_address": { "line1": "354 OYSTER POINT BLVD", "city": "SOUTH SAN FRANCISCO", "state": "CA", "postal_code": "94080", "country": "US" }, "mode": "validation_and_normalization", "result": "likely_deliverable" } } ``` ## Adressvalidierung Die Validierung bestimmt, ob Ihre Adresse zustellungsfähig ist, indem versucht wird, einen Abgleich mit einer bestehenden, validierten Adresse durchzuführen. Dieser wird nach der Normalisierung durchgeführt. Das Ergebnis dieser Validierung ist im Adressvalidierungs-Hash enthalten. Je nach verwendetem [Adressvalidierungsmodus](https://docs.stripe.com/api/issuing/cards/object.md#issuing_card_object-shipping-address_validation-mode) kann dies zu einem API-Fehler führen. | Ergebnis | Beschreibung | | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `likely_deliverable` | Wenn eine teilweise oder vollständig übereinstimmende Adresse in unserer Drittanbieter-Datenbank gefunden wird, wird Ihre Adresse als wahrscheinlich zustellungsfähig angesehen. | | `likely_undeliverable` | Wenn in unserer Drittanbieter-Datenbank keine übereinstimmende oder teilweise übereinstimmende Adresse gefunden wird, wird Ihre Adresse als wahrscheinlich nicht zustellungsfähig angesehen. | | `indeterminate` | Die Zustellungsfähigkeit der Adresse konnte nicht ermittelt werden. | Im vorherigen Beispiel wurde beispielsweise das Validierungsergebnis `likely_deliverable` angezeigt. ```json "address_validation": { // the normalized address "normalized_address": { "line1": "354 OYSTER POINT BLVD", "city": "SOUTH SAN FRANCISCO", "state": "CA", "postal_code": "94080", "country": "US" }, "mode": "validation_and_normalization", // the result showing that address was validated to be likely deliverable"result": "likely_deliverable" } ``` ## Verwalten von Adressvalidierungsfunktionen mit Adressvalidierungsmodi Die Cards API unterstützt drei Adressvalidierungsmodi, die optional im Parameter [address_validation](https://docs.stripe.com/api/issuing/cards/create.md#create_issuing_card-shipping-address_validation) beim Erstellen einer physischen Karte oder beim Aktualisieren der Versandoptionen einer Karte angegeben werden können. | Modus | Beschreibung | | ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `validation_and_normalization` | Überprüft und normalisiert die Versandadresse Ihrer Karte, bevor sie zur Abwicklung gesendet wird. Stripe versucht, automatisch alle entsprechenden Korrekturen und Formatierungen an Ihrer Adresse vorzunehmen, bevor die Zustellbarkeit ermittelt wird. Wenn die Versandadresse der Karte wahrscheinlich nicht zustellbar ist, erhalten Sie einen API-Anfragefehler. | | `normalization_only` | Normalisiert die Versandadresse Ihrer Karte vor der Übermittlung an die Abwicklung und wendet alle entsprechenden Korrekturen und Formatierungen an Ihrer Adresse an. Die Zustellbarkeit der Adresse wird nicht erzwungen und Sie erhalten keinen API-Anfragefehler. | | `disabled` | Ihre Karte wird an die angegebene Adresse versendet, ohne dass eine Normalisierung vorgenommen oder die Zustellbarkeit überprüft wird. Dies wird nur empfohlen, wenn eine Adresse als korrekt oder anderweitig validiert bekannt ist. | Verwenden Sie `validation_and_normalization` für den Adressvalidierungsmodus. Abhängig von Ihrem Szenario bieten wir auch alternative Optionen an: - `disabled`: Wenn Sie glauben, dass eine Karte fälschlicherweise gesperrt wurde. - `normalization only`: wenn Sie API-Fehler minimieren, aber dennoch die Vorteile der Normalisierung nutzen möchten (Modus: `normalization_only`). Falls nicht angegeben ist der Standardwert `normalization_only`. ### Validierung und Normalisierung Ihre Karte wird mit der validierten, normalisierten Adresse versendet. Die Zustellungsfähigkeit der Adresse wird erzwungen, und die API gibt eine Fehlermeldung aus, wenn die Adresse wahrscheinlich nicht zustellungsfähig ist. Stripe empfiehlt dringend, diesen Modus zu verwenden, um die Zustellungsfähigkeit der Adresse zu gewährleisten. ```curl curl https://api.stripe.com/v1/issuing/cards \ -u "<>:" \ -d cardholder="{{ISSUINGCARDHOLDER_ID}}" \ -d type=physical \ -d currency=usd \ -d "shipping[name]"="Jenny Rosen" \ -d "shipping[address][line1]"="1234 Fake St" \ -d "shipping[address][city]"="Fake City" \ -d "shipping[address][state]"=NY \ -d "shipping[address][country]"=US \ -d "shipping[address][postal_code]"=94111 \ -d "shipping[address_validation][mode]"=validation_and_normalization ``` ```json "error": { "message": { "The address is undeliverable based on given inputs. Please ensure that the address was inputted correctly and can be delivered to." } } ``` ### Nur Normalisierung Ihre Karte wird mit der normalisierten Adresse versendet. Die Zustellungsfähigkeit der Adresse wird nicht erzwungen, und Sie erhalten keinen API-Anfragefehler, wenn die Adresse wahrscheinlich nicht zustellungsfähig ist. ```curl curl https://api.stripe.com/v1/issuing/cards \ -u "<>:" \ -d cardholder="{{ISSUINGCARDHOLDER_ID}}" \ -d type=physical \ -d currency=usd \ -d "shipping[name]"="Jenny Rosen" \ -d "shipping[address][line1]"="1234 Fake St" \ -d "shipping[address][city]"="Fake City" \ -d "shipping[address][state]"=NY \ -d "shipping[address][country]"=US \ -d "shipping[address][postal_code]"=94111 \ -d "shipping[address_validation][mode]"=normalization_only ``` ```json # Example response { "id": "{{CARD_ID}}", "object": "issuing.card", "shipping": { // address supplied during card creation "address": { "line1": "1234 Fake Street", "city": "Fake city", "postal_code": "94111", "state": "NY", "country": "US" }, // address validation information "address_validation": { // the card will be shipped with this address "normalized_address": { "line1": "1234 FAKE ST", "city": "FAKE CITY", "state": "NY", "postal_code": "94111", "country": "US" }, "mode": "normalization_only", "result": "likely_undeliverable" }, // other fields... }, // other fields... } ``` ### Deaktiviert In diesem Modus wird Ihre Karte unter Verwendung der angegebenen Adresse versendet, ohne dass eine Normalisierung angewendet oder die Zustellungsfähigkeit überprüft wird. Es werden keine normalisierte Adresse und kein Validierungsergebnis zurückgegeben. Dies wird nur empfohlen, wenn eine Adresse als korrekt oder anderweitig validiert bekannt ist. ```curl curl https://api.stripe.com/v1/issuing/cards \ -u "<>:" \ -d cardholder="{{ISSUINGCARDHOLDER_ID}}" \ -d type=physical \ -d currency=usd \ -d "shipping[name]"="Jenny Rosen" \ -d "shipping[address][line1]"="1234 Fake St" \ -d "shipping[address][city]"="Fake City" \ -d "shipping[address][state]"=NY \ -d "shipping[address][country]"=US \ -d "shipping[address][postal_code]"=94111 \ -d "shipping[address_validation][mode]"=disabled ``` ```json // Example response { "id": "{{CARD_ID}}", "object": "issuing.card", "shipping": { // address supplied during card creation "address": { "line1": "1234 Fake Street", "city": "Fake city", "postal_code": "94111", "state": "NY", "country": "US" }, // address validation information "address_validation": { "mode": "disabled" }, // other fields... }, // other fields... } ``` ## Adressvalidierung in Ihren Kartenerstellungsablauf integrieren Nachfolgend finden Sie mehrere Beispiele für die Integration von Adressvalidierungsfunktionen in Ihren eigenen Ablauf. Diese Beispiele sind nicht vollständig, sollen Ihnen aber bei Ihrer Integration helfen. #### Synchrone Kartenerstellung ### Strikte Adressvalidierung Am besten erhöhen Sie die Zustellbarkeit, indem Sie die Adressvalidierung nie umgehen, sodass Ihre Kundinnen/Kunden immer zustellbare Adressen übermitteln müssen. Strikter Ablauf der Adressvalidierung (See full diagram at https://docs.stripe.com/issuing/cards/physical/address-validation) ### Adressvorschläge Ein gängiges Verfahren, das Nutzer/innen dazu, auffordert zwischen einer vorgeschlagenen und der von ihnen eingegebenen Adresse auszuwählen. Dieses Verfahren können Sie mithilfe unserer Funktionen zur Adressvalidierung selbst erstellen. Ablauf für Adressvorschläge (See full diagram at https://docs.stripe.com/issuing/cards/physical/address-validation) ### Lockere Adressvalidierung Sie können nicht zustellbare Adressfehler problemlos handhaben, indem Sie Nutzer/innen auffordern, ihre angegebene Adresse zu bestätigen. Durch Aktivieren des Adressvalidierungsmodus `disabled` stellen Sie sicher, dass Ihre Kundinnen/Kunden problemlos Karten bestellen können, wenn ihre Adresse als korrekt bekannt ist. Lockerer Ablauf der Adressvalidierung (See full diagram at https://docs.stripe.com/issuing/cards/physical/address-validation) #### Asynchrone Kartenerstellung ### Asynchrone Adressvalidierung Im Folgenden wird beschrieben, wie Sie mit unzustellbaren Adressen umgehen können, ohne Ihre Integration zu unterbrechen. Wenn Sie den Modus `normalization_only` verwenden, wird die Karte dennoch erfolgreich erstellt und die Ergebnisse der Adressvalidierung werden Ihnen in der Antwort angezeigt. Sie können diese Ergebnisse dann optional separat verwenden, um die Kundinnen/Kunden über mögliche Unklarheiten bei der Adresse zu informieren. Ablauf der asynchronen Adresskorrektur (See full diagram at https://docs.stripe.com/issuing/cards/physical/address-validation) ## Adressvalidierung testen Sie können einen magischen Wert für `line1` angeben, um bestimmte Validierungsbedingungen in Testumgebungen auszulösen. Sie müssen gültige Werte für die Argumente `city`, `state` und `postal_code` übergeben. | Wert | Typ | | ----------------- | ------------------------------------------------------------------------------------------------ | | `address_valid` | Senden Sie eine Anfrage unter Verwendung einer zu Testzwecken zustellbaren Versandadresse. | | `address_invalid` | Senden Sie eine Anfrage unter Verwendung einer zu Testzwecken nicht zustellbaren Versandadresse. | ```curl curl https://api.stripe.com/v1/issuing/cards \ -u "<>:" \ -d cardholder="{{ISSUINGCARDHOLDER_ID}}" \ -d type=physical \ -d currency=usd \ -d "shipping[name]"="Jenny Rosen" \ -d "shipping[address][line1]"=address_invalid \ -d "shipping[address][city]"="San Francisco" \ -d "shipping[address][state]"=CA \ -d "shipping[address][country]"=US \ -d "shipping[address][postal_code]"=94111 \ -d "shipping[address_validation][mode]"=validation_and_normalization ```