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 leicht zu behebende Fehler in Ihren Adressen korrigiert werden.

Beispiele für die Normalisierung sind:

Adressstandardisierung zur Sicherstellung der korrekten Formatierung

// 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

// 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 enthalten, der nach erfolgreicher Erstellung einer physischen Karte oder Aktualisierung der Versandadresse einer Karte bei aktivierter Adressnormalisierung zurückgegeben wird.

Validierung der Musteradresse

"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 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.

"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 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.

"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.

# Example response
{
  "id":  "ic_test1CDR9auHsQKan42gGK34",
  "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.

// Example response
{
  "id":  "ic_test1CDR9auHsQKan42gGK34",
  "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.

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.

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.

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.

Adressvalidierung testen

Geben Sie einen magischen Wert für line1 an, um bestimmte Validierungsbedingungen im Test-Modus auszulösen. Für die Argumente city, state und postal_code müssen Sie gültige Werte angeben.

Wert	Typ
`address_valid`	Senden Sie eine Anfrage für den Test-Modus unter Verwendung einer zustellungsfähigen Versandadresse.
`address_invalid`	Senden Sie eine Anfrage für den Test-Modus unter Verwendung einer nicht zustellungsfähigen Versandadresse.