Utiliser des portefeuilles électroniques avec Issuing

Demande d’accès pour iOS

Une mise en service de type push nécessite un droit Apple spécial appelé com.apple.developer.payment-pass-provisioning. Vous pouvez demander ce droit par e-mail à l’adresse support-issuing@stripe.com. Dans votre e-mail, veillez à inclure les informations suivantes :

• Réseau de cartes : Visa ou MasterCard.
• Nom de la carte : il s’agit du nom de la carte affichée dans le portefeuille numérique.
• Nom de l’application : le nom de votre application.
• ID de l’équipe de développeurs : disponible dans la section abonnement des paramètres de votre compte Apple Developer.
• ID ADAM : l’ID numérique unique de votre application, que vous trouverez sur l’App Store Connect ou dans le lien de l’App Store vers votre application (par exemple, https://apps.apple.com/app/id123456789).
• ID de groupe (bundle ID) : l’identifiant de groupe de votre application, également disponible sur l’App Store Connect (par exemple, com.example.yourapp).

Demande d’accès pour Android

Stripe fournit un wrapper SDK basé sur une bibliothèque Google privée pour la mise en service de type push. Pour publier votre application sur le Google Play Store via une mise en service de type push, vous devez demander un accès à cette bibliothèque :

• Demander un accès à Google Pay
• Téléchargez le SDK privé TapAndPay de Google (la version compatible actuelle est la 17.1.2)
• Demandez un accès à l’API de provisionnement push pour votre application. Vous devrez fournir votre ID d’application pour l’ajouter à la liste blanche de Google. Pour en savoir plus sur ce processus, consultez la documentation de Google.
• Envoyez le même ID d’application, le nom de votre application, le réseau de cartes et le nom de la carte à l’adresse support-issuing@stripe.com.

Le SDK React Native est disponible en open source et fait l’objet d’une documentation complète. En interne, il utilise des SDK Android et iOS natifs. Pour installer le SDK React Native de Stripe, exécutez l’une des commandes suivantes dans le répertoire de votre projet (selon le gestionnaire de paquets que vous utilisez) :

yarn add @stripe/stripe-react-native

Ensuite, installez les autres dépendances nécessaires :

• Pour iOS, accédez au répertoire ** ios** et exécutez pod install pour vous assurer d’installer également les dépendances natives requises.
• Pour Android, il n’y a plus de dépendances à installer.

Initialisation de Stripe

Pour initialiser Stripe dans votre application React Native, wrappez votre écran de paiement avec le composant StripeProvider ou utilisez la méthode d’initialisation initStripe. Seule la clé publiable de l’API dans publishableKey est nécessaire. L’exemple suivant montre comment initialiser Stripe à l’aide du composant StripeProvider.

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

Configuration pour Android

Pour activer le provisionnement de type push sur Android après avoir obtenu l’accès au SDK TapAndPay (voir ci-dessus), vous devez l’intégrer à votre projet Android natif.

Ensuite, vous devez importer la bibliothèque de provisionnement de type push pour Android de Stripe en ajoutant ce qui suit à votre fichier android/app/build.gradle :

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

Configuration pour iOS

Pour activer le provisionnement de type push sur iOS une fois que Stripe a octroyé le droit d’accès, vous devez ajouter les fonctionnalité à votre profil de provisionnement dans l’App Store Connect.

Ensuite, vous devez ajouter le nouveau droit d’accès à votre fichier ios/app.config.js :

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

L’implémentation de la mise en service de type push expose des méthodes qui requièrent que vous communiquiez avec votre back-end pour créer une clé éphémère Stripe et renvoyer un JSON de celle-ci à votre application. Cette clé est un identifiant éphémère de l’API que vous pouvez utiliser pour récupérer les informations de carte chiffrées d’une instance unique d’un objet Card.

Pour garantir que l’objet renvoyé par l’API Stripe est compatible avec la version du SDK que vous utilisez, vous devez explicitement transmettre la version d’API exportée par le SDK React Native à notre API lorsque vous créez la clé.

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

Vous devez également créer un endpoint pour récupérer les informations de la carte émise, qu’il vous faudra transmettre au composant <AddToWalletButton /> :

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

Tout d’abord, déterminez si l’appareil est admissible à l’approvisionnement push en vérifiant que la valeur de wallets.apple_pay.eligible dans la carte émise (récupérée à partir du deuxième endpoint que vous avez créé ci-dessus à l’étape 3) est true. Si tel est le cas, enregistrez les informations de la carte pour les utiliser ultérieurement dans notre composant, puis continuez. Si wallets.apple_pay.eligible est défini sur false, n’affichez pas le <AddToWalletButton /> sur iOS, car App Review pourrait rejeter votre application. Il en va de même pour wallets.google_pay.eligible sur 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 />;
}

Ensuite, récupérez votre clé éphémère auprès du premier endpoint que vous avez créé à l’étape 3 ci-dessus et enregistrez-la.

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

Vous n’avez plus besoin de communiquer avec le serveur. Vous devez ensuite déterminer si la carte peut être ajoutée au portefeuille. Vous pouvez vérifier cela à l’aide de la méthode canAddCardToWallet, qui renvoie un objet contenant un champ booléen canAddCard. Si canAddCard est défini sur false, n’affichez pas le paramètre AddToWalletButton, car votre application pourrait être rejetée par Apple.

Sur Android, il se peut que la carte soit déjà présente dans le portefeuille, mais que son état soit bloqué. Pour résoudre ce problème, vous pouvez ajouter une logique permettant de vérifier la réponse token renvoyée par canAddCardToWallet dans l’objet details. Si cette réponse est non nulle et que token.status est "TOKEN_STATE_NEEDS_IDENTITY_VERIFICATION", transmettez ce token aux propriétés de <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 />;
}

Nous disposons désormais de toutes les informations nécessaires pour pouvoir afficher ce bouton :

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

Lorsqu’un utilisateur touche le bouton, il lance l’interface utilisateur permettant d’ajouter la carte au portefeuille. Implémentez ce rappel dans votre propriété onComplete. Si le champ error est non nul, une erreur se produit et la carte n’est pas ajoutée au portefeuille. Au contraire, si error est nul, la carte peut être ajoutée.

Apparence du bouton

Sur iOS, l’apparence du bouton est déterminée par la propriété iOSButtonStyle. Définissez-la sur :

• onLightBackground lorsque vous affichez le bouton sur un arrière-plan clair ou blanc.
• onDarkBackground lorsque vous affichez le bouton sur un arrière-plan sombre ou noir.

Sur Android, vous devez transmettre la ressource de l’image réelle à la propriété androidAssetSource. Vous pouvez télécharger toutes les options de ressources possibles directement depuis Google. Suivez les instructions de Google relatives à la marque lorsque vous implémentez votre bouton.

Pour transmettre le fichier PNG de votre choix au composant AddToWalletButton, ajoutez-le à votre projet, importez-le de la même manière que n’importe quelle ressource et résolvez la source avec Image.resolveAssetSource :

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

...

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

iOS

Sur iOS, vous pouvez tester le provisionnement push en développement sur des simulateurs ou à l’aide de cartes de test, du moment que vous transmettez le paramétrage testEnv={true} au composant AddToWalletButton. Cependant, notez que si la propriété testEnv est définie sur true, les cartes ne seront pas ajoutées au wallet de l’appareil. Dans les environnements de test, le droit d’accès com.apple.developer.payment-pass-provisioning n’est pas nécessaire.

Android

Sur Android, la propriété testEnv n’a aucun effet. Tous les tests doivent être réalisés en mode production, avec des cartes réelles et sur des appareils physiques.

Veillez à fournir votre ID d’application à Stripe avant de commencer les tests internes.