Finaliser les paiements sur le serveur

Développez une intégration dans laquelle vous renvoyez le composant Mobile Payment Element avant de créer un PaymentIntent ou SetupIntent, puis confirmez l'Intent à partir de votre serveur.

iOS

Android

React Native

Le Payment Element permet d’accepter plusieurs moyens de paiement à l’aide d’une seule intégration. Dans cette intégration, vous créez un tunnel de paiement personnalisé dans lequel vous affichez le composant Payment Element, créez le PaymentIntent et confirmez le paiement sur votre serveur.

Configurer Stripe
Côté serveur
Côté client

Côté serveur

Cette intégration exige que votre serveur dispose de endpoints qui communiquent avec l’API Stripe. Utilisez nos bibliothèques officielles pour accéder à l’API Stripe depuis votre serveur :

Côté client

Le SDK iOS de Stripe est disponible en open source et fait l’objet d’une documentation complète. Il est également compatible avec les applications prenant en charge iOS 13 et les versions ultérieures.

Pour installer le SDK, veuillez suivre les étapes ci-dessous :

Dans Xcode, sélectionnez File > Add Package Dependencies… puis saisissez https://github.com/stripe/stripe-ios-spm en tant qu’URL du référentiel.
Sélectionnez le dernier numéro de version, visible sur notre page des versions.
Ajoutez le produit StripePaymentSheet à la cible de votre application.

Remarque

Pour obtenir de plus amples informations sur la version la plus récente du SDK et ses versions antérieures, consultez la page des versions sur GitHub. Pour recevoir une notification lors de la publication d’une nouvelle version, surveillez les versions à partir du référentiel.

Vous devez également définir votre clé publique pour que le SDK puisse effectuer des appels à l’API Stripe. Pour commencer, vous pouvez coder en dur la clé publique côté client pendant l’intégration, mais la récupérer sur votre serveur en mode production.

// Set your publishable key: remember to change this to your live publishable key in production
// See your keys here: https://dashboard.stripe.com/apikeys
STPAPIClient.shared.publishableKey = "pk_test_TYooMQauvdEDq54NiTphI7jx"

Activer des moyens de paiement

Affichez vos paramètres des moyens de paiement et activez les moyens de paiement que vous souhaitez prendre en charge. Vous devez activer au moins un moyen de paiement pour créer un PaymentIntent.

Par défaut, Stripe active les cartes bancaires et les autres moyens de paiement courants qui peuvent vous permettre d’atteindre davantage de clients. Nous vous recommandons toutefois d’activer d’autres moyens de paiement pertinents pour votre entreprise et vos clients. Consultez la page Prise en charge des moyens de paiement pour en savoir plus sur la prise en charge des produits et des moyens de paiement, et notre page des tarifs pour prendre connaissance des frais que nous appliquons.

Configurer une URL de redirection
Côté client

Le client peut quitter votre application pour s’authentifier (par exemple, dans Safari ou dans son application bancaire). Pour lui permettre de revenir automatiquement sur votre application après s’être authentifié, configurez un schéma d’URL personnalisé et configurez votre délégué d’application pour qu’il transmette l’URL au SDK. Stripe ne prend pas en charge les liens universels.

Définissez également le paramètre returnURL correspondant à votre objet PaymentSheet.Configuration sur l’URL de votre application.

var configuration = PaymentSheet.Configuration()
configuration.returnURL = "your-app://stripe-redirect"

Collecter les informations de paiement
Côté client

Nous proposons deux types d’intégration. Choisissez-en un pour continuer.

PaymentSheet	PaymentSheet.FlowController

Affiche un formulaire permettant de collecter les informations de paiement et de finaliser le paiement. Le bouton du formulaire indique Payer X $ et permet d’effectuer le paiement.	Affiche une feuille permettant de collecter uniquement les informations de paiement. Le bouton dans la feuille indique Continuer et redirige le client vers votre application, où votre propre bouton finalise le paiement.

Initialiser la PaymentSheet

Lorsque vous êtes prêt à accepter un paiement (par exemple, lorsqu’un client appuie sur votre bouton de paiement), initialisez le PaymentSheet avec un PaymentSheet.Configuration et un PaymentSheet.IntentConfiguration. L’objet Configuration contient la configuration générale de la PaymentSheet qui ne change généralement pas d’un paiement à l’autre, comme returnURL. L’objet IntentConfiguration contient des informations sur le paiement concerné, comme le montant et la devise, ainsi qu’un rappel confirmHandler. Pour l’instant, laissez son implémentation vide.

import StripePaymentSheet

class MyCheckoutVC: UIViewController {
  func didTapCheckoutButton() {
    let intentConfig = PaymentSheet.IntentConfiguration(
      mode: .payment(amount: 1099, currency: "USD", )
    ) { [weak self] paymentMethod, shouldSavePaymentMethod, intentCreationCallback in
      self?.handleConfirm(paymentMethod, shouldSavePaymentMethod, intentCreationCallback)
    }
    var configuration = PaymentSheet.Configuration()
    configuration.returnURL = "your-app://stripe-redirect" // Use the return url you set up in the previous step
    let paymentSheet = PaymentSheet(intentConfiguration: intentConfig, configuration: configuration)
  }

  func handleConfirm(_ paymentMethod: STPPaymentMethod, _ shouldSavePaymentMethod: Bool, _ intentCreationCallback: @escaping (Result<String, Error>) -> Void) {
    // ...explained later
  }
}

Présenter la PaymentSheet

Présentez ensuite la PaymentSheet. La méthode present s’appuie sur un bloc d’exécution qui est appelé lorsque le client a finalisé le paiement et que la feuille est fermée. Implémentez le bloc d’exécution pour gérer le résultat (par exemple, en affichant un reçu ou un écran de confirmation dans le cas d’un paiement .completed).

class MyCheckoutVC: UIViewController {
  func didTapCheckoutButton() {
    // ...
    paymentSheet.present(from: self) { result in
      switch result {
        case .completed:
          // Payment completed - show a confirmation screen.
        case .failed(let error):
          print(error)
          // PaymentSheet encountered an unrecoverable error. You can display the error to the user, log it, etc.
        case .canceled:
          // Customer canceled - you should probably do nothing.
      }
    }
  }
}

Confirmer les du paiement

Lorsque le client appuie sur le bouton Payer de la PaymentSheet, il appelle le rappel que vous avez transmis à PaymentSheet.IntentConfiguration avec un objet STPPaymentMethod représentant les informations de paiement du client.

Implémentez ce rappel pour envoyer une requête à votre serveur, en transmettant paymentMethod.stripeIdet shouldSavePaymentMethod. Votre serveur crée et confirme un PaymentIntent et renvoie sa clé secrète du client.

Lorsque la requête est renvoyée, appelez le rappel intentCreationCallback en transmettant la clé secrète du client ou une erreur. Le PaymentSheet effectue toutes les actions suivantes requises pour finaliser le PaymentIntent à l’aide de la clé secrète du client ou affiche un message d’erreur localisé dans son interface utilisateur (soit errorDescription, soit localizedDescription).

class MyCheckoutVC: UIViewController {
  // ...

  func handleConfirm(_ paymentMethod: STPPaymentMethod, _ shouldSavePaymentMethod: Bool, _ intentCreationCallback: @escaping (Result<String, Error>) -> Void) {
    // Make a request to your own server, passing paymentMethod.stripeId and shouldSavePaymentMethod, and receive a client secret or an error..
    let myServerResponse: Result<String, Error> = ...
    switch myServerResponse {
    case .success(let clientSecret):
      // Call the `intentCreationCallback` with the client secret
      intentCreationCallback(.success(clientSecret))
    case .failure(let error):
      // Call the `intentCreationCallback` with the error
      intentCreationCallback(.failure(error))
    }
  }
}

Créer et envoyer le paiement à Stripe
Côté serveur

Sur votre serveur, créez et confirmez un a PaymentIntent en indiquant un montant et une devise. Vous pouvez gérer les moyens de paiement depuis le Dashboard. Stripe gère le l’affichage des moyens de paiement admissibles en fonction de facteurs tels que le montant de la transaction, la devise et le tunnel de paiement. Pour éviter que des clients malveillants ne choisissent eux-mêmes leurs tarifs, décidez toujours du montant à débiter côté serveur (un environnement sécurisé) plutôt que côté client.

Si l’appel réussit, renvoyez la clé secrète du client du PaymentIntent. Si l’appel échoue, traitez l’erreur et renvoyez un message d’erreur avec une courte explication à l’intention de votre client.

Gestion des arguments côté client :

payment_method_id : vous pouvez utiliser cet ID pour récupérer l’objet PaymentMethod afin de procéder à votre propre validation ou logique métier.

should_save_payment_method : cet indicateur précise si le client vous a ou non demandé d’enregistrer son moyen de paiement dans l’interface utilisateur de PaymentSheet. Si sa valeur est true, définissez l’attribut setup_future_usage sur « off_session ».

Remarque

Lors de la confirmation d’un PaymentIntent côté serveur, transmettez le paramètre mandate_data pour confirmer que vous avez présenté au client les conditions applicables à la collecte de ses informations de paiement. Pour afficher les conditions appropriées, veillez à ce que toutes les propriétés IntentConfiguration correspondent à votre PaymentIntent (par exemple, setup_future_usage, amount, and currency).

Gérer les événements post-paiement
Côté serveur

Stripe envoie un événement payment_intent.succeeded à l’issue du paiement. Utilisez l’outil de webhook du Dashboard ou suivez le guide consacré aux webhooks pour recevoir ces événements et exécuter des actions, comme envoyer une confirmation de commande par e-mail à votre client, enregistrer la vente dans une base de données ou lancer un flux de livraison.

Plutôt que d’attendre un rappel de votre client, écoutez ces événements. Côté client, il arrive en effet que l’utilisateur ferme la fenêtre de son navigateur ou quitte l’application avant l’exécution du rappel. Certains clients malintentionnés peuvent d’autre part tenter de manipuler la réponse. En configurant votre intégration de manière à ce qu’elle écoute les événements asynchrones, vous pourrez accepter plusieurs types de moyens de paiement avec une seule et même intégration.

En plus de l’événement payment_intent.succeeded, nous vous recommandons de gérer ces autres événements lorsque vous encaissez des paiements à l’aide de l’Element Payment :

Événement	Description	Action
payment_intent.succeeded	Envoyé lorsqu’un client effectue un paiement avec succès.	Envoyez au client une confirmation de commande et traitez sa commande.
payment_intent.processing	Envoyé lorsqu’un client initie un paiement, mais qu’il ne l’a pas encore finalisé. Dans la plupart des cas, cet événement est envoyé lorsque le client initie un prélèvement bancaire. Il est suivi par un événement `payment_intent.succeeded` ou `payment_intent.payment_failed`.	Envoyez au client une confirmation de commande qui indique que son paiement est en attente. Pour des marchandises dématérialisées, vous pourrez traiter la commande sans attendre que le paiement soit effectué.
payment_intent.payment_failed	Envoyé lorsqu’un client effectue une tentative de paiement qui se solde par un échec.	Si un paiement passe de l’état `processing` à `payment_failed`, proposez au client de retenter le paiement.

Tester l'intégration

Numéro de carte	Scénario	Méthode de test
	Le paiement par carte bancaire aboutit et ne nécessite pas d’authentification.	Remplissez le formulaire de paiement par carte bancaire en saisissant le numéro de carte ainsi que la date d’expiration, le CVC et le code postal de votre choix.
	Le paiement par carte bancaire requiert une authentification.	Remplissez le formulaire de paiement par carte bancaire en saisissant le numéro de carte ainsi que la date d’expiration, le CVC et le code postal de votre choix.
	La carte est refusée avec un code de refus de type `insufficient_funds`.	Remplissez le formulaire de paiement par carte bancaire en saisissant le numéro de carte ainsi que la date d’expiration, le CVC et le code postal de votre choix.
	La carte UnionPay a un numéro d’une longueur variable, allant de 13 à 19 chiffres.	Remplissez le formulaire de paiement par carte bancaire en saisissant le numéro de carte ainsi que la date d’expiration, le CVC et le code postal de votre choix.

Consultez la section consacrée aux tests pour obtenir des informations supplémentaires sur la manière de tester votre intégration.

FacultatifActiver les cartes sauvegardées
Côté serveur
Côté client

PaymentSheet peut afficher une case à cocher Enregistrer cette carte pour une utilisation ultérieure qui enregistre la carte du client, ainsi que les cartes enregistrées du client. Pour activer cette case à cocher, créez un objet Customer sur votre serveur et une clé éphémère associée.

const stripe = require('stripe')('sk_test_your_secret_key');

app.post('/mobile-payment-element', async (req, res) => {
  // Use an existing Customer ID if this is a returning customer.
  const customer = await stripe.customers.create();
  const ephemeralKey = await stripe.ephemeralKeys.create(
    {customer: customer.id},
    {apiVersion: '2020-08-27'}
  );

  res.json({
    ephemeralKey: ephemeralKey.secret,
    customer: customer.id,
  });
});

Ensuite, configurez la PaymentSheet avec l’ID et la clé éphémère secrète du client.

var configuration = PaymentSheet.Configuration()
configuration.customer = .init(id: customerId, ephemeralKeySecret: customerEphemeralKeySecret)

self.paymentSheet = PaymentSheet(..., configuration: configuration)

FacultatifAutoriser les moyens de paiement à notification différée
Côté client

Les moyens de paiement différés ne garantissent pas non plus que vous recevrez les fonds de votre client à la fin du paiement, à cause du délai de versement (par exemple, comptes bancaires aux États-Unis, prélèvements SEPA, iDEAL et Bancontact) ou parce qu’ils nécessitent une intervention du client (par exemple, OXXO, Konbini et Boleto).

Par défaut, PaymentSheet n’affiche pas les moyens de paiement différés. Pour activer cette option, définissez allowsDelayedPaymentMethods sur true dans votre PaymentSheet.Configuration. Cette étape ne suffit pas à activer des moyens de paiement spécifiques, elle permet simplement d’indiquer que votre application est capable de les gérer. Par exemple, bien qu’OXXO ne soit pas pris en charge par PaymentSheet, s’il devient pris en charge et que vous avez installé la dernière version du SDK, votre application pourra afficher OXXO comme option de paiement sans modification supplémentaire de l’intégration.

var configuration = PaymentSheet.Configuration()
configuration.allowsDelayedPaymentMethods = true

self.paymentSheet = PaymentSheet(..., configuration: configuration)

Si le client utilise l’un de ces moyens de paiement différé dans la PaymentSheet, le résultat du paiement renvoyé est .completed.

FacultatifActiver Apple Pay

Remarque

Si votre écran de paiement comporte un bouton Apple Pay dédié, suivez le guide Apple Pay et utilisez ApplePayContext pour encaisser le paiement à partir de votre bouton Apple Pay. Vous pouvez utiliser PaymentSheet pour gérer d’autres types de moyens de paiement.

Demander un ID de marchand Apple

Pour obtenir un ID de marchand Apple, demandez un nouvel identifiant sur le site Web Apple Developer.

Renseignez le formulaire en indiquant une description et un identifiant. La description n’est destinée qu’à votre propre information et vous pourrez la modifier ultérieurement au besoin. En ce qui concerne l’identifiant, Stripe vous recommande d’utiliser le nom de votre application (par exemple, merchant.com.{{YOUR_APP_NAME}}).

Créer un nouveau certificat Apple Pay

Créez un certificat permettant à votre application de chiffrer les données de paiement.

Accédez aux paramètres des certificats iOS dans le Dashboard, cliquez sur Ajouter une nouvelle application et suivez le guide.

Téléchargez un fichier CSR (Certificate Signing Request) pour obtenir d’Apple un certificat sécurisé vous autorisant à utiliser Apple Pay.

Un fichier CSR peut émettre exactement un certificat. Si vous changez d’ID de marchand Apple, vous devez accéder aux paramètres des certificats iOS dans le Dashboard pour obtenir un nouveau fichier CSR et un nouveau certificat.

Réaliser une intégration avec Xcode

Ajoutez la fonctionnalité Apple Pay à votre application. Dans Xcode, ouvrez vos paramètres de projet, cliquez sur l’onglet Signature et fonctionnalités, puis ajoutez Apple Pay. Vous serez peut-être alors invité(e) à vous connecter à votre compte développeur. Sélectionnez l’ID du marchand créé plus tôt. Il est désormais possible d’utiliser Apple Pay sur votre application.

Activez la fonctionnalité Apple Pay dans Xcode

Ajouter Apple Pay

Pour ajouter Apple Pay à PaymentSheet, définissez applePay après avoir initialisé PaymentSheet.Configuration avec votre ID de marchand Apple et le code pays de votre entreprise.

var configuration = PaymentSheet.Configuration()
configuration.applePay = .init(
  merchantId: "merchant.com.your_app_name",
  merchantCountryCode: "US"
)

Suivi de commande

Pour ajouter des informations de suivi de commande dans iOS 16 ou version ultérieure, configurez un authorizationResultHandler dans votre PaymentSheet.ApplePayConfiguration.Handlers. Stripe effectue un appel vers votre implémentation une fois le paiement effectué, mais avant qu’iOS ne ferme la fiche Apple Pay.

Dans votre implémentation authorizationResultHandler, récupérez les détails de la commande dans votre serveur pour la commande terminée. Ajoutez les détails au PKPaymentAuthorizationResult fourni et appelez le gestionnaire d’achèvement fourni.

Pour en savoir plus sur le suivi des commandes, consultez la documentation Apple’s Wallet Orders.

let customHandlers = PaymentSheet.ApplePayConfiguration.Handlers(
    authorizationResultHandler: { result, completion in
        // Fetch the order details from your service
        MyAPIClient.shared.fetchOrderDetails(orderID: orderID) { myOrderDetails
            result.orderDetails = PKPaymentOrderDetails(
                orderTypeIdentifier: myOrderDetails.orderTypeIdentifier, // "com.myapp.order"
                orderIdentifier: myOrderDetails.orderIdentifier, // "ABC123-AAAA-1111"
                webServiceURL: myOrderDetails.webServiceURL, // "https://my-backend.example.com/apple-order-tracking-backend"
                authenticationToken: myOrderDetails.authenticationToken) // "abc123"
            // Call the completion block on the main queue with your modified PKPaymentAuthorizationResult
            completion(result)
        }
    }
)
var configuration = PaymentSheet.Configuration()
configuration.applePay = .init(merchantId: "merchant.com.your_app_name",
                               merchantCountryCode: "US",
                               customHandlers: customHandlers)

FacultatifActiver la numérisation de carte

Pour que vous puissiez utiliser la numérisation des cartes, définissez le paramètre NSCameraUsageDescription (Confidentialité – Description de l’utilisation de l’appareil photo) dans le fichier Info.plist de votre application et expliquez la raison pour laquelle vous devez accéder à l’appareil photo (« Pour numériser des cartes », par exemple). Les appareils équipés d’iOS 13 ou version ultérieure prennent en charge la numérisation des cartes.

FacultatifPersonnaliser le formulaire

Pour personnaliser le formulaire de paiement, vous devez obligatoirement utiliser l’objet PaymentSheet.Configuration.

Appearance

Personnalisez les couleurs, les polices et plus encore afin de vous adapter à l’apparence de votre application à l’aide de l’API Appearance.

Mise en page des moyens de paiement

Configurez la mise en page des moyens de paiement dans la feuille à l’aide de paymentMethodLayout. Vous pouvez les afficher horizontalement, verticalement ou laisser Stripe optimiser la mise en page automatiquement.

var configuration = PaymentSheet.Configuration()
configuration.paymentMethodLayout = .automatic

Recueillir les adresses des utilisateurs

Recueillez les adresses de livraison ou de facturation de vos clients locaux et internationaux à l’aide du composant Address Element.

Nom d’affichage du marchand

Spécifiez un nom d’entreprise à afficher pour le client en définissant merchantDisplayName. Par défaut, il s’agit du nom de votre application.

var configuration = PaymentSheet.Configuration()
configuration.merchantDisplayName = "My app, Inc."

Mode sombre

PaymentSheet s’ajuste automatiquement en fonction des paramètres d’affichage du système de l’utilisateur (mode clair et foncé). Si votre application ne prend pas en charge le mode sombre, vous pouvez définir style sur le mode alwaysLight ou alwaysDark.

var configuration = PaymentSheet.Configuration()
configuration.style = .alwaysLight

Informations de facturation par défaut

Si vous souhaitez définir des valeurs par défaut pour les informations de facturation collectées dans le formulaire de paiement, configurez la propriété defaultBillingDetails. Le PaymentSheet préremplit les champs avec les valeurs que vous fournissez.

var configuration = PaymentSheet.Configuration()
configuration.defaultBillingDetails.address.country = "US"
configuration.defaultBillingDetails.email = "foo@bar.com"

Collecte des informations de facturation

Utilisez billingDetailsCollectionConfiguration pour spécifier la manière dont vous souhaitez collecter les informations de facturation dans le Payment Sheet.

Vous pouvez collecter le nom, l’adresse e-mail, le numéro de téléphone et l’adresse de votre client.

Si vous souhaitez uniquement indiquer les informations de facturation requises par le moyen de paiement, définissez la valeur de billingDetailsCollectionConfiguration.attachDefaultsToPaymentMethod sur « true ». Dans ce cas, les PaymentSheet.Configuration.defaultBillingDetails sont définis comme les informations de facturation du moyen de paiement.

Si vous souhaitez collecter des informations de facturation supplémentaires qui ne sont pas nécessairement requises par le moyen de paiement, définissez la valeur de billingDetailsCollectionConfiguration.attachDefaultsToPaymentMethod sur false. Dans ce cas, les informations de facturation collectées depuis la PaymentSheet sont définies comme les informations de facturation du moyen de paiement.

var configuration = PaymentSheet.Configuration()
configuration.defaultBillingDetails.email = "foo@bar.com"
configuration.billingDetailsCollectionConfiguration.name = .always
configuration.billingDetailsCollectionConfiguration.email = .never
configuration.billingDetailsCollectionConfiguration.address = .full
configuration.billingDetailsCollectionConfiguration.attachDefaultsToPaymentMethod = true

Remarque

Consultez votre conseiller juridique au sujet des lois qui s’appliquent à la collecte d’informations. Ne collectez les numéros de téléphone que si vous en avez besoin pour la transaction.

Finaliser les paiements sur le serveur

Développez une intégration dans laquelle vous renvoyez le composant Mobile Payment Element avant de créer un PaymentIntent ou SetupIntent, puis confirmez l'Intent à partir de votre serveur.

Configurer StripeCôté serveurCôté client

Côté serveur

Côté client

Remarque

Activer des moyens de paiement

Configurer une URL de redirectionCôté client

Collecter les informations de paiementCôté client

Initialiser la PaymentSheet

Présenter la PaymentSheet

Confirmer les du paiement

Créer et envoyer le paiement à StripeCôté serveur

Gestion des arguments côté client :

Remarque

Gérer les événements post-paiementCôté serveur

Tester l'intégration

FacultatifActiver les cartes sauvegardéesCôté serveurCôté client

FacultatifAutoriser les moyens de paiement à notification différéeCôté client

FacultatifActiver Apple Pay

Remarque

Demander un ID de marchand Apple

Créer un nouveau certificat Apple Pay

Réaliser une intégration avec Xcode

Ajouter Apple Pay

Suivi de commande

FacultatifActiver la numérisation de carte

FacultatifPersonnaliser le formulaire

Appearance

Mise en page des moyens de paiement

Recueillir les adresses des utilisateurs

Nom d’affichage du marchand

Mode sombre

Informations de facturation par défaut

Collecte des informations de facturation

Remarque

Configurer Stripe
Côté serveur
Côté client

Configurer une URL de redirection
Côté client

Collecter les informations de paiement
Côté client

Créer et envoyer le paiement à Stripe
Côté serveur

Gérer les événements post-paiement
Côté serveur

FacultatifActiver les cartes sauvegardées
Côté serveur
Côté client

FacultatifAutoriser les moyens de paiement à notification différée
Côté client