Encaisser des paiements, puis effectuer des virements

Installez les bibliothèques officielles de Stripe pour accéder à l’API depuis votre application :

# Available as a gem
sudo gem install stripe

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

Lorsqu’un utilisateur (vendeur ou fournisseur de services) s’inscrit sur votre place de marché, vous devez créer un compte correspondant à cet utilisateur (appelé compte connecté). Sans cela, vous ne pourrez pas accepter de paiements de la part du compte bancaire de cet utilisateur ni lui transférer de fonds. Les comptes connectés représentent vos utilisateurs dans l’API Stripe et collectent les informations nécessaires pour vérifier leur identité. Dans notre exemple de location immobilière, le compte connecté représente le propriétaire.

Créer un compte connecté et préremplir les informations

Utilisez l’API /v1/accounts pour créer un compte connecté en spécifiant les propriétés du compte connecté ou le type de compte.

curl https://api.stripe.com/v1/accounts \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -d "controller[losses][payments]"=application \
  -d "controller[fees][payer]"=application \
  -d "controller[stripe_dashboard][type]"=express

Si vous avez déjà collecté des informations pour vos comptes connectés, vous pouvez préremplir ces informations dans l’objet de compte. Vous pouvez pré-remplir n’importe quelle information de compte, y compris des informations personnelles et professionnelles, des informations relatives à un compte externe, etc.

Connect Onboarding ne demande pas les informations préremplies. Cependant, il demande au titulaire du compte de confirmer les informations préremplies avant d’accepter le contrat d’utilisation du service Connect.

Lorsque vous testez votre intégration, préremplissez les informations du compte à l’aide des données de test.

Créer un lien de compte

Vous pouvez créer un lien de compte en appelant l’API Account Links avec les paramètres suivants :

• account
• refresh_url
• return_url
• type = account_onboarding

curl https://api.stripe.com/v1/account_links \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -d account=
{{CONNECTED_ACCOUNT_ID}} \
  --data-urlencode refresh_url="https://example.com/reauth" \
  --data-urlencode return_url="https://example.com/return" \
  -d type=account_onboarding

Rediriger votre utilisateur vers l’URL du lien de compte

La réponse à votre requête Account Links inclut une valeur pour la clé url. Redirigez l’utilisateur vers ce lien pour le faire entrer dans le flux. Les URL provenant de l’API Account Links sont temporaires et ne peuvent être utilisées qu’une seule fois, car elles donnent accès aux informations personnelles de l’utilisateur du compte connecté. Procédez à l’authentification de l’utilisateur dans votre application avant de le rediriger vers cette URL. Si vous souhaitez préremplir les informations, vous devez le faire avant de générer le lien de compte. Une fois le lien de compte créé, les opérations de lecture comme d’écriture ne seront plus possibles pour ce compte connecté.

Gérer la redirection de l’utilisateur vers votre plateforme

Connect Onboarding vous demande de transmettre à la fois une return_url et une refresh_url afin de gérer tous les cas de redirection des utilisateurs vers votre plateforme. Il est important que vous les implémentiez correctement afin d’offrir à vos utilisateurs une expérience optimale.

return_url

Stripe déclenche une redirection vers cette URL une fois que l’utilisateur a terminé son inscription Connect Onboarding. Ceci ne veut pas dire que toutes les informations ont été recueillies ni qu’il ne reste pas des conditions à remplir pour le compte, mais simplement que l’entrée de votre client dans le flux et sa sortie se sont déroulées correctement.

Aucun état n’est transmis par cette URL. Une fois que l’utilisateur est redirigé vers votre return_url, vérifiez l’état du paramètre details_submitted sur son compte de l’une des manières suivantes :

• En écoutant les webhooks account.updated
• Appeler l’API Accounts et inspecter l’objet renvoyé

refresh_url

Stripe redirige votre utilisateur vers la refresh_url dans les cas suivants :

• Le lien a expiré (quelques minutes se sont écoulées depuis sa création).
• L’utilisateur a déjà utilisé l’URL (il a actualisé la page ou cliqué sur le bouton Précédent ou Suivant de son navigateur).
• Votre plateforme n’est plus en mesure d’accéder au compte.
• Le compte a été rejeté.

Pour une expérience optimale, votre URL refresh_url doit déclencher une méthode permettant à votre serveur d’appeler à nouveau Account Links avec les mêmes paramètres, et de rediriger l’utilisateur vers le flux Connect Onboarding.

Gérer les utilisateurs dont l’inscription n’est pas terminée

Un utilisateur redirigé vers votre return_url peut ne pas avoir terminé son inscription. Utilisez l’endpoint /v1/accounts pour récupérer ses données de compte et vérifier le paramètre charges_enabled. Si l’inscription du compte n’a pas été finalisée, affichez des invites pour encourager l’utilisateur à poursuivre son inscription. Il pourra achever l’activation de son compte grâce à un nouveau lien de compte (généré par votre intégration). Vous pourrez vérifier l’état du paramètre details_submitted sur son compte pour voir s’il a terminé son inscription.

Accédez aux paramètres des moyens de paiement de votre Dashboard et activez ceux que vous souhaitez prendre en charge. Les paiements par carte bancaire, Google Pay et Apple Pay sont activés par défaut, mais vous pouvez activer et désactiver les moyens de paiement de votre choix selon vos besoins.

Avant que le formulaire de paiement ne s’affiche, Stripe évalue la devise, les restrictions relatives aux moyens de paiement ainsi que d’autres paramètres pour dresser la liste des moyens de paiement pris en charge. Ceux qui augmentent le taux de conversion et qui sont les plus pertinents selon la devise et le lieu de résidence du client sont automatiquement présentés en priorité. Les moyens de paiement de moindre priorité ne sont visibles qu’au sein d’un menu de débordement.

Utilisez Stripe Checkout pour accepter des paiements. Checkout prend en charge de nombreux moyens de paiement et affiche automatiquement les plus pertinents pour votre client. Vous pouvez accepter des paiements avec Checkout à l’aide d’une page hébergée par Stripe ou ajouter un formulaire de paiement intégré préconfiguré directement sur votre site Web. Vous pouvez également créer un flux personnalisé (à l’aide du Payment Element) pour accepter plusieurs moyens de paiement avec une seule intégration front-end.

Page hébergée par Stripe

Formulaire intégré

Flux personnalisé

Créer une session Checkout Client and Server

Une session Checkout détermine ce que votre client voit sur la page de paiement hébergée par Stripe, tel que les postes de la facture, le montant et la devise de la commande, ainsi que les moyens de paiement acceptés.

Ajoutez à votre site Web un bouton de paiement qui appelle un endpoint côté serveur afin de créer une session Checkout.

checkout.html

<html>
  <head>
    <title>Checkout</title>
  </head>
  <body>
    <form action="/create-checkout-session" method="POST">
      <button type="submit">Checkout</button>
    </form>
  </body>
</html>

Sur votre serveur, effectuez l’appel suivant à l’API Stripe. Après avoir créé une session Checkout, redirigez votre client vers l’URL renvoyée dans la réponse.

Command Line

cURL

curl https://api.stripe.com/v1/checkout/sessions \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -d mode=payment \
  -d "line_items[0][price]"=
{{PRICE_ID}} \
  -d "line_items[0][quantity]"=1 \
  -d "payment_intent_data[application_fee_amount]"=123 \
  -d "payment_intent_data[transfer_data][destination]"=
{{CONNECTED_ACCOUNT_ID}} \
  --data-urlencode success_url="https://example.com/success" \
  --data-urlencode cancel_url="https://example.com/cancel"

• line_items : cet argument spécifie les articles achetés par votre client. Ces articles sont affichés dans l’interface utilisateur hébergée par Stripe.
• success_url : cet argument assure la redirection de l’utilisateur une fois le paiement effectué.
• cancel_url : cet argument assure la redirection de l’utilisateur dès lors qu’il annule l’opération.
• payment_intent_data[application_fee_amount] : cet argument précise le montant que votre plateforme prévoit de prélever sur la transaction. Une fois le paiement capturé, le montant total du paiement est immédiatement transféré depuis la plateforme vers le compte connecté spécifié par le paramètre transfer_data[destination]. Ensuite, le montant application_fee_amount est à nouveau transféré vers la plateforme, et les frais Stripe sont déduits de ce montant.
• payment_intent_data[transfer_data][destination] : cet argument indique qu’il s’agit d’un paiement indirect. Un paiement indirect désigne un paiement traité sur la plateforme et pour lequel les fonds sont ensuite immédiatement et automatiquement transférés vers le solde en attente du compte connecté. Dans le cadre de notre exemple de location immobilière, nous voulons créer les conditions permettant au client de payer via la plateforme, et au propriétaire d’être payé par la plateforme.

Checkout utilise les paramètres de marque du compte de votre plateforme pour les paiements indirects. Pour en savoir plus, consultez Personnaliser l’image de marque.

Cette session crée un paiement indirect. Si vous souhaitez choisir à quel moment les transferts ont lieu ou transférer des fonds vers plusieurs bénéficiaires, utilisez plutôt des paiements et transferts distincts. Pour utiliser des paiements distincts, consultez Permettre à d’autres entreprises d’accepter directement des paiements.

Gérer les événements après le paiement Server-side

Stripe envoie un événement checkout.session.completed à l’issue du paiement. Utilisez un webhook pour recevoir ces événements et exécuter des actions en conséquence, comme l’envoi d’un e-mail de confirmation de commande à votre client, l’enregistrement de la vente dans une base de données ou le lancement d’un flux de livraison.

Nous vous conseillons d’écouter ces événements plutôt que d’attendre un rappel du client. 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. Avec certains moyens de paiement, la confirmation du paiement peut par ailleurs prendre entre 2 et 14 jours. Configurer votre intégration de manière à ce qu’elle écoute les événements asynchrones vous permettra d’accepter plusieurs moyens de paiement avec une seule intégration.

En plus de gérer l’événement checkout.session.completed, nous vous recommandons de gérer deux autres événements lorsque vous encaissez des paiements avec Checkout :

Événement	Description	Étapes suivantes
checkout.session.completed	Le client a autorisé le paiement en envoyant le formulaire Checkout.	Attendez que le paiement aboutisse ou échoue.
checkout.session.async_payment_succeeded	Le paiement du client a abouti.	Traitez la commande de biens ou de services de votre client.
checkout.session.async_payment_failed	Le paiement a été refusé, ou il a échoué pour une autre raison.	Contactez votre client par e-mail et demandez-lui de passer une nouvelle commande.

Ces événements incluent tous l’objet Checkout Session. Une fois le paiement effectué, l’état sous-jacent du PaymentIntent passe de processing à succeeded.

Testez votre flux de création de comptes en créant des comptes et en utilisant OAuth.

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