Création de paiements et de transferts distincts

Pour commencer, vous devez créer un compte Stripe. S’inscrire.

Côté serveur

Cette intégration nécessite des endpoints sur votre serveur qui communiquent avec l’API Stripe. Utilisez nos bibliothèques officielles pour accéder à l’API Stripe depuis votre serveur :

# Available as a gem
sudo gem install stripe

# If you use bundler, you can add this line to your Gemfile
gem 'stripe'

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.

Configurez le SDK avec votre clé publiable Stripe au démarrage de votre application. Cela lui permet d’envoyer des requêtes à l’API Stripe.

import UIKit
import StripePaymentSheet

@main
class AppDelegate: UIResponder, UIApplicationDelegate {

    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        StripeAPI.defaultPublishableKey = 
"pk_test_TYooMQauvdEDq54NiTphI7jx"
        // do any other necessary launch configuration
        return true
    }
}

Cette intégration utilise trois objets de l’API Stripe :

1. Un PaymentIntent. Pour représenter votre intention d’encaisser le paiement d’un client, Stripe utilise un objet PaymentIntent qui suit vos tentatives de débit et les changements d’état du paiement tout au long du processus.
2. Un objet Customer (facultatif). Pour configurer un moyen de paiement en vue de paiements futurs, vous devez l’associer à un client. Créez un objet Customer lorsque votre client crée un compte chez vous. Si votre client effectue un paiement en tant qu’invité, vous pouvez créer un objet Customer avant le paiement, puis l’associer ultérieurement à votre représentation interne du compte client.
3. Un objet Customer Ephemeral Key (facultatif). L’objet Customer contient des informations sensibles qu’il n’est pas possible de récupérer directement depuis une application. Une clé éphémère permet d’accorder au SDK un accès temporaire à l’objet Customer.

Si vous souhaitez enregistrer des cartes et autoriser vos clients réguliers à réutiliser les cartes enregistrées, vous avez besoin des objets Customer et Customer Ephemeral Key pour votre intégration. Sinon, vous pouvez ignorer ces objets.

Pour des raisons de sécurité, votre application ne peut pas créer ces objets. À la place, ajoutez sur votre serveur un endpoint qui :

1. Récupère l’objet Customer ou en crée un nouveau.
2. Crée une clé éphémère pour le client.
3. Crée un objet PaymentIntent, en précisant le montant, la devise, le client, ainsi qu’un groupe de transfert à associer ultérieurement au transfert de fonds.
4. Renvoie la clé secrète du client du composant Payment Intent, le secret de la clé éphémère, l’ID du client et votre clé publiable à votre application.

Les moyens de paiement présentés aux clients lors du processus de paiement sont également inclus dans le PaymentIntent. Vous pouvez laisser Stripe extraire les moyens de paiement des paramètres du Dashboard, ou bien les répertorier manuellement.

À moins que votre intégration ne nécessite du code pour la présentation des moyens de paiement, ne listez pas les moyens de paiement manuellement. En effet, Stripe évalue la devise, les restrictions sur les moyens de paiement ainsi que d’autres paramètres pour dresser la liste des moyens de paiement pris en charge. Les moyens de paiement qui augmentent le taux de conversion et qui sont les plus pertinents pour la devise et le lieu de résidence du client sont automatiquement priorisés par Stripe. Ceux de moindre priorité ne sont accessibles que via un menu de débordement.

# Create a Customer (use an existing Customer ID if this is a returning customer)
curl https://api.stripe.com/v1/customers \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -X "POST"

# Create an Ephemeral Key for the Customer
curl https://api.stripe.com/v1/ephemeral_keys \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -H "Stripe-Version: 2025-05-28.basil" \
  -X "POST" \
  -d "customer"=
{{CUSTOMER_ID}} \

# Create a PaymentIntent
curl https://api.stripe.com/v1/payment_intents \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -X "POST" \
  -d "customer"=
{{CUSTOMER_ID}} \
  -d "amount"=10000 \
  -d "currency"="usd" \
  # In the latest version of the API, specifying the `automatic_payment_methods` parameter
  # is optional because Stripe enables its functionality by default.
  -d "automatic_payment_methods[enabled]"=true \
  -d transfer_group="ORDER100" \

Pour afficher le composant Payment Element sur votre page de paiement, veillez à :

• Afficher les produits commandés et le montant total des achats
• Utiliser le composant Address Element pour collecter toutes les informations de livraison requises auprès du client
• Ajouter un bouton de paiement pour afficher l’interface utilisateur de Stripe

import UIKit
import StripePaymentSheet

class CheckoutViewController: UIViewController {
  @IBOutlet weak var checkoutButton: UIButton!
  var paymentSheet: PaymentSheet?
  let backendCheckoutUrl = URL(string: "Your backend endpoint/payment-sheet")! // Your backend endpoint

  override func viewDidLoad() {
    super.viewDidLoad()

    checkoutButton.addTarget(self, action: #selector(didTapCheckoutButton), for: .touchUpInside)
    checkoutButton.isEnabled = false

    // MARK: Fetch the PaymentIntent client secret, Ephemeral Key secret, Customer ID, and publishable key
    var request = URLRequest(url: backendCheckoutUrl)
    request.httpMethod = "POST"
    let task = URLSession.shared.dataTask(with: request, completionHandler: { [weak self] (data, response, error) in
      guard let data = data,
            let json = try? JSONSerialization.jsonObject(with: data, options: []) as? [String : Any],
            let customerId = json["customer"] as? String,
            let customerEphemeralKeySecret = json["ephemeralKey"] as? String,
            let paymentIntentClientSecret = json["paymentIntent"] as? String,
            let publishableKey = json["publishableKey"] as? String,
            let self = self else {
        // Handle error
        return
      }

      STPAPIClient.shared.publishableKey = publishableKey
      // MARK: Create a PaymentSheet instance
      var configuration = PaymentSheet.Configuration()
      configuration.merchantDisplayName = "Example, Inc."
      configuration.customer = .init(id: customerId, ephemeralKeySecret: customerEphemeralKeySecret)
      // Set `allowsDelayedPaymentMethods` to true if your business handles
      // delayed notification payment methods like US bank accounts.
      configuration.allowsDelayedPaymentMethods = true
      self.paymentSheet = PaymentSheet(paymentIntentClientSecret: paymentIntentClientSecret, configuration: configuration)

      DispatchQueue.main.async {
        self.checkoutButton.isEnabled = true
      }
    })
    task.resume()
  }

}

@objc
func didTapCheckoutButton() {
  // MARK: Start the checkout process
  paymentSheet?.present(from: self) { paymentResult in
    // MARK: Handle the payment result
    switch paymentResult {
    case .completed:
      print("Your order is confirmed")
    case .canceled:
      print("Canceled!")
    case .failed(let error):
      print("Payment failed: \(error)")
    }
  }
}

Si la valeur de PaymentSheetResult est .completed, informez l’utilisateur (par exemple, en affichant un écran de confirmation de commande).

Si vous définissez allowsDelayedPaymentMethods sur true, les moyens de paiement à notification différée, comme les comptes bancaires étasuniens, seront acceptés. Pour ces moyens de paiement, l’état final du paiement n’est pas connu une fois le processus du PaymentSheet achevé, et le paiement peut plus tard aboutir comme échouer. Si vous prenez en charge ces types de moyens de paiement, informez votre client que sa commande est confirmée et ne la traitez (en lui expédiant son produit, par exemple) qu’une fois le paiement reçu.

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.

// This method handles opening custom URL schemes (for example, "your-app://stripe-redirect")
func scene(_ scene: UIScene, openURLContexts URLContexts: Set<UIOpenURLContext>) {
    guard let url = URLContexts.first?.url else {
        return
    }
    let stripeHandled = StripeAPI.handleURLCallback(with: url)
    if (!stripeHandled) {
        // This was not a Stripe url – handle the URL normally as you would
    }
}

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 :

Sur votre serveur, envoyez des fonds de votre compte vers un compte connecté en créant un transfert et en précisant le transfer_group utilisé.

curl https://api.stripe.com/v1/transfers \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d amount=7000 \
  -d currency=usd \
  -d destination=
{{CONNECTED_ACCOUNT_ID}} \
  -d transfer_group=ORDER100

Les montants des transferts et des paiements ne doivent pas nécessairement correspondre. Vous pouvez fractionner un paiement en plusieurs transferts ou inclure plusieurs paiements dans un même transfert. L’exemple suivant illustre la création d’un transfert supplémentaire associé au même transfer_group.

curl https://api.stripe.com/v1/transfers \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d amount=2000 \
  -d currency=usd \
  -d destination={{OTHER_CONNECTED_ACCOUNT_ID}} \
  -d transfer_group=ORDER100

Options de transfert

Vous pouvez attribuer n’importe quelle valeur à la chaîne transfer_group, mais elle doit représenter une seule action commerciale. Vous pouvez également effectuer un transfert sans paiement associé ou sans transfer_group, par exemple, lorsque vous devez payer un fournisseur, mais qu’il n’y a pas de paiement client associé.

Par défaut, une demande de transfert échoue lorsque le montant dépasse le solde de compte disponible de la plateforme. Stripe ne relance pas automatiquement les demandes de transfert en échec.

Vous pouvez éviter les échecs des demandes de transfert pour les transferts associés à des paiements. Lorsque vous précisez le paiement associé comme source_transaction du transfert, la demande de transfert aboutit automatiquement. Cependant, nous n’exécutons pas le transfert tant que les fonds provenant de ce paiement ne sont pas disponibles sur le compte de la plateforme.

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