Verwendung digitaler Geldbörsen mit Issuing

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:

• Card network—Visa or MasterCard.
• Card name—This is the name of the card displayed in the wallet.
• 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.
• Provide the same application ID, your app name, card network, and card name to support-issuing@stripe.com.

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):

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>
  );
}

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:

dependencies {
    // ...
    implementation 'com.stripe:stripe-android-issuing-push-provisioning:1.1.0'
}

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:

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

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.

curl https://api.stripe.com/v1/ephemeral_keys \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -d "issuing_card"="{{ISSUING_CARD_ID}}" \
  -H "Stripe-Version: {{API_VERSION}}"

{
  "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:

curl https://api.stripe.com/v1/issuing/cards/ISSUING_CARD_ID \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:"

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)}
  ...
/>

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.