Verwendung digitaler Geldbörsen mit Issuing

Erfahren Sie, wie Sie mit Issuing Karten zu digitalen Geldbörsen hinzufügen können.

Mit Issuing können Nutzer/innen Karten sowohl manuell als auch über eine App zu digitalen Wallets wie Apple Pay und Google Pay hinzufügen. Stripe unterstützt das Hinzufügen von Karten über zwei Methoden:

Manuelle Bereitstellung: Karteninhaber/innen geben ihre Kartendaten in die digitale Geldbörse eines Smartphones ein, um diese zu ihrer digitalen Geldbörse hinzuzufügen.
Push-Bereitstellung: Mit mobilen Anwendungen können Nutzer/innen Karten direkt über die App in ihre digitalen Geldbörsen einzahlen.

Wenn eine Karte zu einer digitalen Geldbörse hinzugefügt wird, wird eine tokenisierte Darstellung dieser Karte erstellt. Netzwerk-Token werden getrennt von Karten verwaltet. Weitere Informationen zu Netzwerk-Token und ihrer Funktionsweise finden Sie unter Token-Verwaltung.

Manuelle Bereitstellung

Karteninhaber/innen können virtuelle Karten und physische Karten von Stripe Issuing manuell zu ihren Geldbörsen von Apple Pay, Google Pay und Samsung Pay hinzufügen.

Dazu öffnen die Karteninhaber/innen die Wallet-App auf ihrem Smartphone und geben ihre Kartendaten ein. Stripe sendet dann einen 6-stelligen Verifizierungscode an die phone_number oder email des/der Karteninhaber/in, der/die mit der Karte verknüpft ist.

Die Fehlermeldung Card not supported (Karte nicht unterstützt) wird angezeigt, wenn für den/die Karteninhaber/in bei der Bereitstellung der Karte keines der Felder festgelegt war.

Es ist kein Code erforderlich, um die manuelle Bereitstellung zu implementieren, aber der Einrichtungsprozess kann je nach Anbieter digitaler Geldbörsen und Land, in dem Sie ansässig sind, variieren:

USA

Geldbörsen für Apple Pay erfordern eine Genehmigung durch Apple. Überprüfen Sie die Einstellungen in Ihrer digitalen Geldbörse, um den Status von Apple Pay in Ihrem Konto anzuzeigen. Gegebenenfalls müssen Sie eine Berechtigung beantragen, bevor Sie Apple Pay verwenden können.

Für Google Pay und Samsung Pay sind keine zusätzlichen Schritte erforderlich.

EU/Vereinigtes Königreich

Digital Wallet-Integrationen erfordern eine zusätzliche Genehmigung des Stripe-Partnerschaftsteams. Kontaktieren Sie Ihre/n Kundenbetreuer/in oder wenden Sie sich an Stripe, um weitere Informationen zu erhalten.

Geldbörsen für Apple Pay erfordern eine zusätzliche Genehmigung. Überprüfen Sie die Einstellungen in Ihrer digitalen Geldbörse, um den Status von Apple Pay in Ihrem Konto anzuzeigen. Gegebenenfalls müssen Sie eine Berechtigung beantragen, bevor Sie Apple Pay verwenden können.

Push-Bereitstellung

Mit der Push-Bereitstellung können Karteninhaber/innen ihre Stripe Issuing-Karten über Ihre App zu ihren digitalen Geldbörsen hinzufügen, indem sie auf die Schaltflächen „ Zu Wallet hinzufügen“ klicken, wie unten abgebildet.

Nutzer/innen müssen zunächst manuelle Bereitstellungsschritte durchführen, um die Push-Bereitstellung in den USA zu aktivieren. Zusätzlich zur manuellen Genehmigung der Bereitstellung müssen Sie für die Push-Bereitstellung eine Integration mit dem Stripe SDK durchführen.

Dies erfordert sowohl den Genehmigungsprozess über Stripe als auch die Code-Integration mit dem Stripe SDK für jede Plattform, auf der Sie die Push-Bereitstellung unterstützen möchten. Plattformgenehmigungen werden an alle verbundenen Konten weitergegeben.

Push-Bereitstellung von Samsung Pay wird von unseren SDKs nicht unterstützt.

Zugriff anfordern

Zugriff für iOS anfordern

Für Push-Provisioning ist eine gesonderte Berechtigung von Apple mit der Bezeichnung com.apple.developer.payment-pass-provisioning erforderlich. Sie können diese Berechtigung mit einer E-Mail an support-issuing@stripe.com anfordern. In Ihrer E-Mail sollten Sie Folgendes angeben:

Kartennetzwerk – Visa oder MasterCard.
Kartenname – Dies ist der Name der Karte, der in der Wallet angezeigt wird.
Name der Anwendung – Der Name Ihrer App.
Developer ID des Teams – Zu finden in Ihren Apple Developer Kontoeinstellungen unter Mitgliedschaft.
ADAM ID – Die eindeutige numerische ID Ihrer App, die Sie in App Store Connect oder im App-Store-Link zu Ihrer App finden (z. B. https://apps.apple.com/app/id123456789)
Bundle ID – Die Paket-ID Ihrer App, den Sie auch im App Store Connect finden (z. B. com.example.yourapp).

Zugriff für Android anfordern

Stripe stellt einen SDK-Wrapper für eine private Google-Bibliothek für das Push-Provisioning bereit. Fordern Sie Zugriff auf diese Bibliothek an, um Ihre App im Google Pay Store mithilfe von Push-Provisioning bereitstellen zu können:

Zugriff auf Google Pay anfordern
Privates TapAndPay SDK von Google herunterladen (die aktuell kompatible Version ist 17.1.2)
Fordern Sie Zugriff auf die Push-Provisioning API für Ihre App an. Sie müssen Ihre App-ID angeben, um zur Zulassungsliste von Google hinzugefügt zu werden. Einzelheiten zu diesem Vorgang finden Sie in der Dokumentation von Google.
Geben Sie dieselbe Anwendungs-ID, Ihren App-Namen, Ihr Kartennetzwerk und Ihren Kartennamen an support-issuing@stripe.com weiter.

Ihre App einrichten
Clientseitig

Das React Native SDK ist Open Source und vollständig dokumentiert. Intern werden native iOS und Android SDKs verwendet. Um das React Native SDK von Stripe zu installieren, führen Sie einen der folgenden Befehle im Verzeichnis Ihres Projekts aus (je nachdem, welchen Paket-Manager Sie verwenden):

Command Line
yarn add @stripe/stripe-react-native

Installieren Sie als Nächstes einige weitere erforderliche Abhängigkeiten:

Navigieren Sie für iOS zum Verzeichnis ios und führen Sie pod install aus, um sicherzustellen, dass Sie auch die erforderlichen nativen Abhängigkeiten installieren.
Für Android müssen keine Abhängigkeiten mehr installiert werden.

Stripe Initialisierung

Um Stripe in Ihrer React Native-App zu initialisieren, umschließen Sie entweder Ihren Zahlungsbildschirm mit der Komponente StripeProvider oder verwenden Sie die Initialisierungsmethode initStripe. Nur der veröffentlichbare API-Schlüssel in publishableKey ist erforderlich. Das folgende Beispiel zeigt, wie Stripe mithilfe der Komponente StripeProvider initialisiert wird.

import { StripeProvider } from '@stripe/stripe-react-native';

function App() {
  const [publishableKey, setPublishableKey] = useState('');

  const fetchPublishableKey = async () => {
    const key = await fetchKey(); // fetch key from your server here
    setPublishableKey(key);
  };

  useEffect(() => {
    fetchPublishableKey();
  }, []);

  return (
    <StripeProvider
      publishableKey={publishableKey}
      merchantIdentifier="merchant.identifier" // required for Apple Pay
      urlScheme="your-url-scheme" // required for 3D Secure and bank redirects
    >
      // Your app code here
    </StripeProvider>
  );
}

Notiz

Use your API test keys while you test and develop, and your live mode keys when you publish your app.

Android-spezifische Einrichtung

Um die Push-Bereitstellung auf Android zu aktivieren, nachdem Sie Zugriff auf das TapAndPay-SDK erhalten haben (siehe oben), müssen Sie diese in Ihr natives Android-Projekt einbeziehen.

Anschließend müssen Sie die native Android-Push-Bereitstellungsbibliothek von Stripe importieren, indem Sie Folgendes zu Ihrer Datei android/app/build.gradle hinzufügen:

iOS-spezifische Einrichtung

Um die Push-Bereitstellung unter iOS zu aktivieren, müssen Sie, nachdem Stripe bestätigt hat, dass die Berechtigung gewährt wurde, die Funktion zu Ihrem Bereitstellungsprofil auf App Store Connect hinzufügen.

Dann müssen Sie die neue Berechtigung Ihrer Datei ios/app.config.js hinzufügen:

app.config.js

"entitlements": {
  "com.apple.developer.payment-pass-provisioning": true
}

Backend aktualisieren
Serverseitig

Die Implementierung von Push-Provisioning sieht Methoden vor, bei denen Sie mit Ihrem eigenen Backend kommunizieren müssen, um einen temporären Stripe-Schlüssel zu erstellen und einen JSON-Code davon an Ihre App zurückzugeben. Bei diesen Schlüsseln handelt es sich um kurzlebige API-Zugangsdaten, die Sie zum Abrufen der verschlüsselten Kartendaten für eine einzelne Instanz eines Kartenobjekts verwenden können.

Um sicherzustellen, dass das von der Stripe-API zurückgegebene Objekt mit der von Ihnen verwendeten Version des SDK kompatibel ist, müssen Sie die vom React Nativ SDK exportierte API-Version bei der Erstellung des Schlüssels explizit an unsere API übergeben.

{
  "id": "ephkey_1G4V6eEEs6YsaMZ2P1diLWdj",
  "object": "ephemeral_key",
  "associated_objects": [
    {
      "id": "ic_1GWQp6EESaYspYZ9uSEZOcq9",
      "type": "issuing.card"
    }
  ],
  "created": 1586556828,
  "expires": 1586560428,
  "livemode": false,
  "secret": "ek_test_YWNjdF8xRmdlTjZFRHelWWxwWVo5LEtLWFk0amJ2N0JOa0htU1JzEZkd2RpYkpJdnM_00z2ftxCGG"
}

Sie sollten auch einen Endpoint erstellen, um die Details der Ausstellungskarte abzurufen, die Sie an die Komponente <AddToWalletButton /> übergeben müssen:

App aktualisieren
Clientseitig

Bestimmen Sie zunächst, ob das Gerät für Push-Provisioning geeignet ist, indem Sie prüfen, ob der Wert von wallets.apple_pay.eligible in der ausgestellten Karte (abgerufen vom zweiten Endpoint, den Sie oben in Schritt 3 erstellt haben) true ist. Wenn dies der Fall ist, speichern Sie die Kartendaten für die spätere Verwendung in unserer Komponente und fahren Sie fort. Wenn wallets.apple_pay.eligible den Wert false hat, lassen Sie den <AddToWalletButton /> unter iOS nicht anzeigen. Andernfalls wird Ihre App von App Review abgelehnt. Dasselbe gilt für wallets.google_pay.eligible für Android.

import React, {useEffect, useState} from 'react';
import {Constants} from '@stripe/stripe-react-native';
import {View} from 'react-native';

export default function MyScreen() {
  const [key, setKey] = useState(null);
  const [card, setCard] = useState(null);

  useEffect(() => {
    fetchEphemeralKey();
    fetchIssuingCard();
  }, []);

  const fetchIssuingCard = async () => {
    const response = await fetch(`${API_URL}/issuing-card`, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        ISSUING_CARD_ID: '{{ISSUING_CARD_ID}}',
      }),
    });

    const card = await response.json();

    if (!card.wallets.apple_pay.eligible) {
      // Do not show <AddToWalletButton /> component on iOS. See card.wallets.apple_pay.ineligible_reason for details
    } else if (!card.wallets.google_pay.eligible) {
      // Do not show <AddToWalletButton /> component on Android. See card.wallets.google_pay.ineligible_reason for details
    } else {
      setCard(card);
    }
  };

  const fetchEphemeralKey = async () => {
    // See above
  };

  return <View />;
}

Rufen Sie als Nächstes Ihren vergänglichen Schlüssel vom ersten Endpoint ab, den Sie in Schritt 3 oben erstellt haben, und speichern Sie ihn.

import React, {useEffect, useState} from 'react';
import {Constants} from '@stripe/stripe-react-native';
import {View} from 'react-native';

export default function MyScreen() {
  const [key, setKey] = useState(null);

  useEffect(() => {
    fetchEphemeralKey();
  }, []);

  const fetchEphemeralKey = async () => {
    const response = await fetch(`${API_URL}/ephemeral-key`, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        ISSUING_CARD_ID: '{{ISSUING_CARD_ID}}',
        API_VERSION: Constants.API_VERSIONS.ISSUING,
      }),
    });
    const myKey = await response.json();
    setKey(myKey);
  };

  return <View />;
}

Sie benötigen keine Serverkommunikation mehr. Als Nächstes müssen Sie ermitteln, ob die Karte zur Geldbörse hinzugefügt werden kann. Sie können dies mit der Methode canAddCardToWallet überprüfen, die ein Objekt zurückgibt, das das boolesche Feld canAddCard enthält. Wenn canAddCard auf false festgelegt ist, wird AddToWalletButton nicht gerendert, da Ihre App ansonsten möglicherweise von Apple abgelehnt wird.

Bei Android besteht die Möglichkeit, dass sich die Karte bereits im Wallet befindet, aber in einem schlechten Status feststeckt. Sie können für einen solchen Fall Logik hinzufügen, indem Sie nach einer token-Antwort details von canAddCardToWallet suchen. Wenn diese Antwort nicht null ist und der token.status "TOKEN_STATE_NEEDS_IDENTITY_VERIFICATION" ist, übergeben Sie diesen token an die Props von <AddToWalletButton />.

import React, {useEffect, useState} from 'react';
import {Constants, canAddCardToWallet, GooglePayCardToken} from '@stripe/stripe-react-native';
import {View} from 'react-native';

export default function MyScreen() {
  const [key, setKey] = useState(null);
  const [card, setCard] = useState(null);
  const [showAddToWalletButton, setShowAddToWalletButton] = useState(false);
  const [androidCardToken, setAndroidCardToken] = useState(null);

  useEffect(() => {
    fetchEphemeralKey();
    fetchIssuingCard();
  }, []);

  const checkIfCanAddCard = async () => {
    const { canAddCard, details, error } = await canAddCardToWallet({
      primaryAccountIdentifier: card?.wallets?.primary_account_identifier,
      cardLastFour: card.last4,
      hasPairedAppleWatch: // Pass a boolean indicating whether or not the device has a paired Apple Watch. iOS only.
    });

    if (error) {
      Alert.alert(error.code, error.message);
    } else {
      setShowAddToWalletButton(canAddCard);
      if (details?.token?.status === 'TOKEN_STATE_NEEDS_IDENTITY_VERIFICATION') {
        setAndroidCardToken(details.token);
      }
    }
  };

  const fetchIssuingCard = async () => {
    // See above
    await checkIfCanAddCard();
  };

  const fetchEphemeralKey = async () => {
    // See above
  };

  return <View />;
}

Jetzt haben wir alle Informationen, die wir brauchen, um die Schaltfläche anzuzeigen:

import React, {useEffect, useState} from 'react';
import {
  Constants,
  canAddCardToWallet,
  AddToWalletButton,
  GooglePayCardToken,
} from '@stripe/stripe-react-native';
import {View, Image, Alert, StyleSheet} from 'react-native';

import AddToGooglePayPNG from '../assets/Add-to-Google-Pay-Button-dark-no-shadow.png';

export default function MyScreen() {
  const [key, setKey] = useState(null);
  const [card, setCard] = useState(null);
  const [showAddToWalletButton, setShowAddToWalletButton] = useState(false);
  const [androidCardToken, setAndroidCardToken] = useState<null | GooglePayCardToken>(null);

  useEffect(() => {
    fetchEphemeralKey();
    fetchIssuingCard();
  }, []);

  const canAddCard = async () => {
    // See above
  };

  const fetchIssuingCard = async () => {
    // See above
  };

  const fetchEphemeralKey = async () => {
    // See above
  };

  return (
    <View>
      {showAddToWalletButton && (
        <AddToWalletButton
          token={androidCardToken}
          androidAssetSource={Image.resolveAssetSource(AddToGooglePayPNG)}
          testEnv={true}
          style={styles.payButton}
          iOSButtonStyle="onLightBackground"
          cardDetails={{
            name: card?.cardholder?.name,
            primaryAccountIdentifier:
              card?.wallets?.primary_account_identifier, // This can be null, but should still always be passed. Failing to pass the primaryAccountIdentifier can result in a failure to provision the card.
            lastFour: card?.last4,
            description: 'Added by Stripe',
          }}
          ephemeralKey={key}
          onComplete={({error}) => {
            Alert.alert(
              error ? error.code : 'Success',
              error
                ? error.message
                : 'Card was successfully added to the wallet.',
            );
          }}
        />
      )}
    </View>
  );
}

const styles = StyleSheet.create({
  payButton: {
    // You may add custom styles to your button, but make sure it complies
    // with the relevant platform guidelines:
    // iOS : https://developer.apple.com/wallet/add-to-apple-wallet-guidelines/
    // Android : https://developers.google.com/pay/issuers/apis/push-provisioning/android/branding-guidelines
  },
});

Wenn ein/e Nutzer/in auf die Schaltfläche tippt, wird die Benutzeroberfläche gestartet, um die Karte zum Wallet hinzuzufügen. Implementieren Sie den Callback in Ihrem onComplete-Prop. Ist das error-Feld nicht null, ist ein Fehler aufgetreten und die Karte wurde nicht Wallet hinzugefügt. Wenn der error null ist, wurde die Karte erfolgreich bereitgestellt.

Stil der Schaltfläche

In iOS wird der Stil der Schaltfläche durch die Eigenschaft iOSButtonStyle festgelegt. Setzen Sie dieses Prop auf:

onLightBackground, wenn Sie die Schaltfläche auf einem hellen oder weißen Hintergrund anzeigen.
onDarkBackground, wenn Sie die Schaltfläche auf einem dunklen oder schwarzen Hintergrund anzeigen.

Unter Android müssen Sie das tatsächliche Bild-Asset an die Eigenschaft androidAssetSource übergeben. Sie können alle möglichen Asset-Optionen direkt von Google herunterladen. Befolgen Sie bei der Implementierung Ihrer Schaltfläche die Markenrichtlinien von Google.

Um Ihr ausgewähltes PNG an die Komponente AddToWalletButton zu übergeben, fügen Sie es Ihrem Projekt hinzu, importieren Sie es wie jedes andere Asset und lösen Sie dann die Quelle mit Image.resolveAssetSource auf:

import {Image} from 'react-native';
import AddToGooglePayPNG from '../assets/Add-to-Google-Pay-Button-dark-no-shadow.png';

...

<AddToWalletButton
  ...
  androidAssetSource={Image.resolveAssetSource(AddToGooglePayPNG)}
  ...
/>

Tests

iOS

In iOS können Sie das Push-Provisioning in der Entwicklung, auf Simulatoren und mit Testkarten testen, solange testEnv={true} an die AddToWalletButton-Komponente übergeben wird. Wenn das testEnv-Prop auf true gesetzt ist, können Karten nicht zum Wallet des Geräts hinzugefügt werden. In Testumgebungen ist die Berechtigung com.apple.developer.payment-pass-provisioning nicht erforderlich.

Android

In Android hat das testEnv-Prop keine Auswirkung. Alle Tests müssen im Live-Modus mit Live-Karten und auf physischen Geräten durchgeführt werden.

Vergessen Sie nicht, Stripe Ihre Anwendungs-ID mitzuteilen, bevor Sie mit internen Tests beginnen.