Utiliser des portefeuilles électroniques avec Issuing

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 (par exemple, 2A23JCNA5E).
• 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).

Si vous avez plusieurs applications (par exemple pour effectuer des tests), qui ont des champs différents pour les attributs ci-dessus, vous devrez demander l’accès pour chacune d’entre elles.

Une fois que nous avons approuvé et appliqué votre demande, votre application apparaît sur la page d’informations de la carte ajoutée dans l’app Cartes, et l’objet PKSecureElementPass est disponible dans votre application en appelant PKPassLibrary().passes(). Vous devrez peut-être supprimer et ajouter à nouveau la carte pour que les modifications soient effectives.

Assurez-vous d’avoir intégré à votre application la dernière version du SDK iOS de Stripe.

Déterminez si l’appareil est éligible à la mise en service de type push.

1. Vérifiez que la valeur wallets[apple_pay][eligible] de la carte émise est définie sur true.
2. Appelez PKPassLibrary().canAddSecureElementPass(primaryAccountIdentifier:) avec le wallets[primary_account_identifier] de votre carte et vérifiez que le résultat est true. Si le primary_account_identifier est vide, transmettez une chaîne vide à canAddSecureElementPass().

Récupérez ces valeurs sur votre back-end, puis transmettez-les à votre application pour la vérification de l’admissibilité.

import Stripe

class MyViewController: UIViewController {

  @IBOutlet weak var addPassButton: PKAddPassButton!
  // ...
  func handleEligibilityResponse(eligible: Bool, primaryAccountIdentifier: String?) {
    if eligible &&
    PKPassLibrary().canAddSecureElementPass(primaryAccountIdentifier: primaryAccountIdentifier ?? "") {
      addPassButton.isHidden = false
    } else {
      addPassButton.isHidden = true
    }
  }

}

Pour plus de contexte, consultez à chaque étape les extraits de code proposés et les renvois vers l’application test. Pour cette étape, observez comment l’application test vérifie l’admissibilité.

Lorsque l’utilisateur touche le bouton PKAddPassButton, créez et présentez un PKAddPaymentPassViewController contenant l’interface utilisateur d’Apple pour le flux de mise en service de type push.

import Stripe

class MyViewController: UIViewController {
  // ...
  func beginPushProvisioning() {
    let config = STPPushProvisioningContext.requestConfiguration(
      withName: "Jenny Rosen", // the cardholder's name
      description: "RocketRides Card", // optional; a description of your card
      last4: "4242", // optional; the last 4 digits of the card
      brand: .visa, // optional; the brand of the card
      primaryAccountIdentifier: self.primaryAccountIdentifier // the primary_account_identifier value from the previous step
    )
    let controller = PKAddPaymentPassViewController(requestConfiguration: config, delegate: self)
    self.present(controller!, animated: true, completion: nil)
  }
}

Pour plus de contexte, observez comment l’application test utilise un PKAddPaymentPassViewController.

L’initialiseur du PKAddPaymentPassViewController nécessite un délégué que vous devez implémenter. Généralement, il s’agit simplement du contrôleur d’affichage à partir duquel vous le présentez. Nous fournissons une classe nommée STPPushProvisioningContext pour vous aider à implémenter ces méthodes.

class MyViewController: UIViewController {
  var pushProvisioningContext: STPPushProvisioningContext? = nil
  // ...
}

extension MyViewController: PKAddPaymentPassViewControllerDelegate {
  func addPaymentPassViewController(_ controller: PKAddPaymentPassViewController, generateRequestWithCertificateChain certificates: [Data], nonce: Data, nonceSignature: Data, completionHandler handler: @escaping (PKAddPaymentPassRequest) -> Void) {
    self.pushProvisioningContext = STPPushProvisioningContext(keyProvider: self)
    // STPPushProvisioningContext implements this delegate method for you, by retrieving encrypted card details from the Stripe API.
    self.pushProvisioningContext?.addPaymentPassViewController(controller, generateRequestWithCertificateChain: certificates, nonce: nonce, nonceSignature: nonceSignature, completionHandler: handler);
  }

  func addPaymentPassViewController(_ controller: PKAddPaymentPassViewController, didFinishAdding pass: PKPaymentPass?, error: Error?) {
    // Depending on if `error` is present, show a success or failure screen.
    self.dismiss(animated: true, completion: nil)
  }
}

Pour plus de contexte, observez comment l’application test met en œuvrePKAddPaymentPassViewControllerDelegate.

Vous pouvez constater que l’initialiseur du STPPushProvisioningContext requiert un keyProvider. Il s’agit d’une instance d’une classe qui implémente le protocole STPIssuingCardEphemeralKeyProvider.

Ce protocole définit une seule méthode obligatoire, createIssuingCardKeyWithAPIVersion:completion. Pour implémenter cette méthode, effectuez un appel à l’API vers votre back-end. Votre back-end crée un objet Ephemeral Key à l’aide de l’API Stripe et le renvoie à votre application. Votre application appelle ensuite le gestionnaire d’exécution fourni avec la réponse API de votre back-end.

extension MyViewController: STPIssuingCardEphemeralKeyProvider {
    func createIssuingCardKey(withAPIVersion apiVersion: String, completion: @escaping STPJSONResponseCompletionBlock) {
        // This example uses Alamofire for brevity, but you can make the request however you want
        AF.request("https://myapi.com/ephemeral_keys",
                   method: .post,
                   parameters: ["api_version": apiVersion])
        .responseJSON { response in
            switch response.result {
            case .success:
                if let data = response.data {
                    do {
                        let obj = try JSONSerialization.jsonObject(with: data, options: []) as! [AnyHashable: Any]
                        completion(obj, nil)
                    } catch {
                        completion(nil, error)
                    }
                }
            case .failure(let error):
                completion(nil, error)
            }
        }
    }
}

Pour plus de contexte, observez comment l’application test met en œuvreSTPIssuingCardEphemeralKeyProvider.

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 iOS ou Android que vous utilisez, le SDK Stripe vous indique quelle version d’API il privilégie. Vous devez explicitement transmettre cette version d’API à 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"
}

Pour plus de contexte, observez comment l’exemple de backend créée une clé Stripe éphémère.

Le droit com.apple.developer.payment-pass-provisioning fonctionne uniquement avec des profils de mise en service en mode distribution, ce qui signifie que, même après l’avoir obtenu, la seule façon de tester le flux de mise en service de bout en bout est de distribuer votre application avec TestFlight ou avec l’App Store.

Pour vous aider concernant les tests, nous fournissons une version fictive du PKAddPaymentPassViewController nommée STPFakeAddPaymentPassViewController qui peut être utilisée de façon interchangeable durant les tests.

import Stripe

class MyViewController: UIViewController {
  // ...
  func beginPushProvisioning() {
    let config = STPPushProvisioningContext.requestConfiguration(
      withName: "Jenny Rosen", // the cardholder's name
      description: "RocketRides Card", // optional; a description of your card
      last4: "4242", // optional; the last 4 digits of the card
      brand: .visa // optional; the brand of the card
    )
    let controller = STPFakeAddPaymentPassViewController(requestConfiguration: config, delegate: self)
    self.present(controller!, animated: true, completion: nil)
  }
}