Créer des paiements indirects

Créez des paiements indirects lorsque les clients effectuent des transactions sur votre plateforme pour des produits ou des services proposés par vos comptes connectés et transférez immédiatement des fonds vers vos comptes connectés. Avec ce type de paiement :

• Vous créez un paiement sur le compte de votre plateforme.
• Vous déterminez si ces fonds sont à transférer partiellement ou en totalité dans votre compte connecté.
• Le solde de votre compte sera débité du coût de la commission Stripe, des remboursements et des contestations de paiement.

Ce type de paiement est le mieux adapté aux places de marché telles qu’Airbnb (location de logements) ou Lyft (covoiturage).

Les paiements indirects ne sont pris en charge que si votre plateforme et le compte connecté se trouvent dans le même pays. Pour la prise en charge des paiements transfrontaliers, vous devez indiquer le marchand de règlement au compte connecté en utilisant le paramètre on_behalf_of sur le Payment Intent ou d’autres scénarios de transferts transfrontaliers valides. Nous vous recommandons d’utiliser les paiements indirects pour les comptes connectés qui ont accès au Dashboard Express ou aucun accès au Dashboard.

Créez une intégration de paiement personnalisée en intégrant des composants d’interface utilisateur sur votre site à l’aide de Stripe Elements. Le code côté client et côté serveur permet de créer un formulaire de paiement qui accepte différents moyens de paiement. Comparez les différents types d’intégration proposés par Stripe.

Pays du client

United States (USD)

Taille

Desktop

Thème

Default

Disposition

Accordion

Pour voir le fonctionnement de Link avec un utilisateur récurrent, saisissez l'adresse e-mail demo@stripe.com. Pour voir le fonctionnement de Link avec une nouvelle inscription, saisissez toute autre adresse e-mail et remplissez le reste du formulaire. Cette démo affiche uniquement Google Pay ou Apple Pay si vous disposez d'une carte active sur l'un de ces portefeuilles.

Effort d'intégration

Code

Type d'intégration

Combinez des composants d’interface utilisateur dans un tunnel de paiement personnalisé

Personnalisation de l'interface utilisateur

Personnalisation au niveau CSS avec l’API Appearance

Tout d’abord, inscrivez-vous pour créer un Compte Stripe.

Utilisez nos bibliothèques officielles pour accéder à l’API Stripe depuis votre application :

Command Line

Ruby

# Available as a gem
sudo gem install stripe

Gemfile

Ruby

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

Créer un PaymentIntent

Côté serveur

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.

Les moyens de paiement présentés à votre client lors du processus de paiement sont également inclus dans ce PaymentIntent. Vous pouvez laisser Stripe extraire automatiquement (depuis les paramètres de votre Dashboard) les moyens de paiement à présenter, ou bien les répertorier manuellement.

À moins que votre intégration ne nécessite un code pour proposer des moyens de paiement, ne listez pas les moyens de paiement manuellement. Stripe évalue la devise, les restrictions des moyens de paiement et d’autres paramètres pour en déterminer la liste de ceux pris en charge. Stripe privilégie les moyens de paiement qui contribuent à augmenter la conversion et qui sont les plus pertinents par rapport à la devise et à l’emplacement du client. Stripe masque les moyens de paiement moins prioritaires dans un menu de débordement.

Gérer les moyens de paiement dans le Dashboard

Répertorier manuellement les moyens de paiement

Créez un PaymentIntent sur votre serveur avec un montant et une devise activés. Dans la dernière version de l’API, le paramètre automatic_payment_methods est facultatif, car Stripe active déjà cette fonctionnalité par défaut. Vous pouvez gérer les moyens de paiement depuis le Dashboard. Stripe gère le renvoi des moyens de paiement admissibles en fonction de facteurs tels que le montant de la transaction, la devise et le tunnel de paiement.

Command Line

cURL

curl https://api.stripe.com/v1/payment_intents \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d amount=1000 \
  -d currency=usd \
  -d "automatic_payment_methods[enabled]"=true \
  -d application_fee_amount=123 \
  -d "transfer_data[destination]"=
{{CONNECTED_ACCOUNT_ID}}

Récupérer la clé secrète du client

Le PaymentIntent contient une clé secrète à utiliser côté client pour finaliser le processus de paiement en toute sécurité. Vous pouvez adopter différentes approches pour transmettre cette clé secrète côté client.

Application monopage

Rendu côté serveur

Récupérez la clé secrète du client à partir d’un endpoint sur votre serveur, à l’aide de la fonction fetch du navigateur. Cette approche est recommandée si votre côté client est une application d’une seule page, en particulier si elle repose sur un framework front-end moderne tel que React. Créez l’endpoint de serveur qui gère la clé secrète du client :

main.rb

Ruby

get '/secret' do
  intent = # ... Create or retrieve the PaymentIntent
  {client_secret: intent.client_secret}.to_json
end

Récupérez ensuite la clé secrète du client à l’aide JavaScript côté client :

(async () => {
  const response = await fetch('/secret');
  const {client_secret: clientSecret} = await response.json();
  // Render the form using the clientSecret
})();

Collecter les informations de paiement

Côté client

Collectez les informations de paiement du client avec le Payment Element. Le Payment Element est un composant d’interface utilisateur préconfiguré qui simplifie la collecte des informations pour de nombreux moyens de paiement.

Le Payment Element contient un iframe qui envoie les informations de paiement à Stripe de manière sécurisée via une connexion HTTPS. Évitez de placer le Payment Element dans un autre iframe, car certains moyens de paiement nécessitent une redirection vers une autre page pour la confirmation du paiement.

Si vous choisissez d’utiliser un iframe et que vous souhaitez accepter Apple Pay ou Google Pay, l’attribut allow de l’iframe doit être égal à "payment *".

Pour que votre intégration fonctionne, l’adresse de la page de paiement doit commencer par https:// et non par http://. Vous pouvez tester votre intégration sans utiliser le protocole HTTPS, mais n’oubliez pas de l’activer lorsque vous souhaitez commencer à accepter des paiements réels.

HTML + JS

React

Configurer Stripe.js

Le composant Element Payment est automatiquement disponible en tant que fonctionnalité de Stripe.js. Intégrez le script Stripe.js à votre page de paiement en l’ajoutant entre les balises head de votre fichier HTML. Chargez toujours Stripe.js directement à partir de js.stripe.com pour maintenir votre conformité PCI. Vous ne devez pas inclure le script dans une offre groupée ni en héberger de copie.

checkout.html

<head>
  <title>Checkout</title>
  <script src="https://js.stripe.com/basil/stripe.js"></script>
</head>

Créez une instance de Stripe avec le code JavaScript suivant sur votre page de paiement :

checkout.js

// Set your publishable key: remember to change this to your live publishable key in production
// See your keys here: https://dashboard.stripe.com/apikeys
const stripe = Stripe(
'pk_test_TYooMQauvdEDq54NiTphI7jx');

Ajouter le Payment Element à votre page de paiement

Le composant Element Payment doit avoir un emplacement dédié dans votre page de paiement. Créez un nœud DOM (conteneur) vide doté d’un ID unique dans votre formulaire de paiement :

checkout.html

<form id="payment-form">
  <div id="payment-element">
    <!-- Elements will create form elements here -->
  </div>
  <button id="submit">Submit</button>
  <div id="error-message">
    <!-- Display error message to your customers here -->
  </div>
</form>

Lors du chargement du formulaire précédent, créez une instance du composant Payment Element et intégrez-la au nœud DOM conteneur. Lorsque vous créez l’instance Elements, transmettez la clé secrète du client définie à l’étape précédente dans les options :

Utilisez la clé secrète du client avec prudence, car elle peut servir à finaliser le paiement. Ne l’enregistrez pas, ne l’intégrez pas dans des URL et ne la dévoilez à personne d’autre que votre client.

checkout.js

const options = {
  clientSecret: '{{CLIENT_SECRET}}',
  // Fully customizable with appearance API.
  appearance: {/*...*/},
};

// Set up Stripe.js and Elements to use in checkout form, passing the client secret obtained in a previous step
const elements = stripe.elements(options);

// Create and mount the Payment Element
const paymentElementOptions = { layout: 'accordion'};
const paymentElement = elements.create('payment', paymentElementOptions);
paymentElement.mount('#payment-element');

Le composant Payment Element affiche un formulaire dynamique qui permet à votre client de choisir un moyen de paiement. Pour chaque moyen de paiement, le formulaire demande automatiquement au client de renseigner toutes les informations de paiement nécessaires.

Personnaliser l’apparence

Personnalisez le Payment Element pour qu’il corresponde à l’apparence de votre site en ajoutant l’objet Appearance dans options lors de la création du fournisseur Elements.

Collecter les adresses

Par défaut, le composant Payment Element ne collecte que les informations nécessaires relatives à l’adresse de facturation. Si vous souhaitez obtenir l’adresse de facturation (par exemple, pour calculer la taxe sur les biens et services numériques) ou l’adresse de livraison complètes d’un client, utilisez le composant Address Element.

Demander un token de marchand Apple Pay

Si vous avez configuré votre intégration afin d’accepter les paiements Apple Pay, nous vous recommandons de configurer l’interface Apple Pay de manière à renvoyer un token de marchand pour activer les transactions initiées par les marchands. Demandez le type de token de marchand approprié dans le Payment Element.

Envoyer le paiement à Stripe

Côté client

Utilisez stripe.confirmPayment pour effectuer le paiement à l’aide des informations du composant Payment Element. Ajoutez un paramètre return_url à cette fonction pour indiquer la page vers laquelle Stripe doit rediriger l’utilisateur à l’issue du paiement. Votre utilisateur peut être redirigé en premier lieu vers un site intermédiaire, comme une page d’autorisation bancaire, avant d’être redirigé vers la page spécifiée par le paramètre return_url. L’utilisateur sera immédiatement redirigé vers la page return_url après un paiement réussi par carte.

Si vous ne souhaitez pas effectuer de redirection à la fin des paiements par carte, vous pouvez assigner au paramètre redirect la valeur if_required. De cette manière, seuls les clients qui choisissent un moyen de paiement avec redirection seront redirigés.

HTML + JS

React

checkout.js

const form = document.getElementById('payment-form');

form.addEventListener('submit', async (event) => {
  event.preventDefault();

  const {error} = await stripe.confirmPayment({
    //`Elements` instance that was used to create the Payment Element
    elements,
    confirmParams: {
      return_url: 'https://example.com/order/123/complete',
    },
  });

  if (error) {
    // This point will only be reached if there is an immediate error when
    // confirming the payment. Show error to your customer (for example, payment
    // details incomplete)
    const messageContainer = document.querySelector('#error-message');
    messageContainer.textContent = error.message;
  } else {
    // Your customer will be redirected to your `return_url`. For some payment
    // methods like iDEAL, your customer will be redirected to an intermediate
    // site first to authorize the payment, then redirected to the `return_url`.
  }
});

Veillez à ce que le paramètre return_url corresponde à une page de votre site web qui indique l’état du paiement. Lorsque Stripe redirige le client vers la page return_url, nous fournissons les paramètres de requête d’URL suivants :

Paramètre	Description
payment_intent	L’identifiant unique du PaymentIntent.
payment_intent_client_secret	La clé secrète du client de l’objet PaymentIntent.

Mise en garde

Si vous disposez d’outils qui assurent le suivi de la session navigateur du client, vous devrez peut-être ajouter le domaine stripe.com à la liste d’exclusion des sites référents. Les redirections font que certains outils créent de nouvelles sessions, ce qui empêche le suivi de la session dans son ensemble.

Utilisez l’un des paramètres de requête pour récupérer le PaymentIntent. Consultez l’état du PaymentIntent pour déterminer les informations à présenter à vos clients. Vous pouvez également ajouter vos propres paramètres de requête lorsque vous ajoutez l’URL return_url ; ils seront conservés tout au long du processus de redirection.

HTML + JS

React

status.js

// Initialize Stripe.js using your publishable key
const stripe = Stripe(
'pk_test_TYooMQauvdEDq54NiTphI7jx');

// Retrieve the "payment_intent_client_secret" query parameter appended to
// your return_url by Stripe.js
const clientSecret = new URLSearchParams(window.location.search).get(
  'payment_intent_client_secret'
);

// Retrieve the PaymentIntent
stripe.retrievePaymentIntent(clientSecret).then(({paymentIntent}) => {
  const message = document.querySelector('#message')

  // Inspect the PaymentIntent `status` to indicate the status of the payment
  // to your customer.
  //
  // Some payment methods will [immediately succeed or fail][0] upon
  // confirmation, while others will first enter a `processing` state.
  //
  // [0]: https://stripe.com/docs/payments/payment-methods#payment-notification
  switch (paymentIntent.status) {
    case 'succeeded':
      message.innerText = 'Success! Payment received.';
      break;

    case 'processing':
      message.innerText = "Payment processing. We'll update you when payment is received.";
      break;

    case 'requires_payment_method':
      message.innerText = 'Payment failed. Please try another payment method.';
      // Redirect your user back to your payment page to attempt collecting
      // payment again
      break;

    default:
      message.innerText = 'Something went wrong.';
      break;
  }
});

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

Cartes bancaires

Portefeuilles

Virements avec redirection bancaire

Prélèvements bancaires

Coupons

Numéro de carte	Scénario	Méthode de test
4242424242424242	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.
4000002500003155	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.
4000000000009995	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.
6205500000000000004	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 d'autres moyens de paiement

Percevoir des frais

Lorsqu’un paiement est traité, plutôt que de transférer le montant total de la transaction vers un compte connecté, vous pouvez décider que votre plateforme prélève une partie du montant de la transaction sous forme de frais. Vous pouvez définir la tarification des frais de deux manières différentes :

• Utilisez les outils de tarification de la plateforme pour définir des règles de tarification des commissions de plateforme et les tester. Cette fonctionnalité no-code du Dashboard Stripe n’est actuellement disponible que pour les plateformes responsables du paiement des frais Stripe.

• Définissez vos règles de tarification en interne, en spécifiant les frais directement dans un PaymentIntent à l’aide du paramètre application_fee_amount ou du paramètre transfer_data[amount]. Les frais définis avec cette méthode remplacent la logique tarifaire spécifiée dans les outils de tarification de la plateforme.

application_fee_amount

transfer_data[amount]

Lorsque vous créez des paiements avec un paramètre application_fee_amount, la totalité du montant du paiement est transférée de la plateforme vers le compte transfer_data[destination] directement après la capture du paiement. Le montant des commissions, application_fee_amount (qui ne peut dépasser le montant du paiement) est ensuite de nouveau transféré, du compte vers la plateforme.

Command Line

cURL

curl https://api.stripe.com/v1/payment_intents \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d amount=1000 \
  -d currency=usd \
  -d "automatic_payment_methods[enabled]"=true \
  -d application_fee_amount=123 \
  -d "transfer_data[destination]"=
{{CONNECTED_ACCOUNT_ID}}

Une fois les commissions de plateforme perçues, un objet Application Fee est créé. Vous pouvez afficher une liste des commissions de plateforme dans le Dashboard, avec les commissions de plateforme ou dans Sigma. Vous pouvez également utiliser la propriété amount de l’objet Application Fee pour établir des rapports détaillés sur les frais.

Lorsque vous utilisez application_fee_amount, il convient de savoir les choses suivantes :

• Le application_fee_amount est plafonné au montant total de la transaction.
• Le montant application_fee_amount est toujours calculé dans la même devise que la transaction.
• The application fee settles in the same currency as the connected account’s settlement currency. For cross-border destination charges, this might differ from your platform’s settlement currency.
• Votre plateforme paie les frais Stripe après le transfert du application_fee_amount dans votre compte.
• Aucune commission Stripe supplémentaire n’est appliquée au montant.
• Votre plateforme peut utiliser le reporting intégré des commissions de plateforme pour rapprocher les commissions encaissées.
• Dans les Dashboards ou les composants hébergés par Stripe, tels que le composant d’informations de paiement, votre compte connecté peut afficher à la fois le montant total et le montant des commissions de la plateforme.

Mouvements de fonds

Avec le code ci-dessus, le montant total du paiement (10 USD) est ajouté au solde en attente du compte connecté. La somme correspondant au paramètre application_fee_amount (1,23 USD) est déduite du montant du paiement et transférée sur votre plateforme. Les frais Stripe (0,59 USD) sont déduits du solde du compte de votre plateforme. Le montant de la commission de plateforme moins les frais Stripe (1,23 USD - 0,59 USD = 0,64 USD) reste dans le solde du compte de votre plateforme.

Le montant application_fee_amount devient disponible selon la fréquence normale de transfert sur le compte la plateforme, tout comme les fonds provenant des paiements ordinaires Stripe.

Sélectionner l’entité de règlement

Le choix de l’entité de règlement dépend des fonctionnalités définies sur un compte et de la manière dont un paiement est créé. L’entité de règlement détermine quelles seront les informations à utiliser pour effectuer le paiement. Elles comprennent le libellé du relevé (celui de la plateforme ou celui du compte connecté) affiché sur la carte de crédit du client ou le relevé bancaire pour ce paiement.

Préciser l’entité de règlement vous permet d’être plus explicite concernant les personnes pour lesquelles les paiements doivent être créés. Par exemple, certaines plateformes préfèrent être l’entité de règlement parce que le client final communique directement avec leur plateforme (comme dans le cas des plateformes à la demande). Cependant, certaines plateformes ont des comptes connectés qui communiquent directement avec les clients finaux (par exemple, une vitrine sur une plateforme d’e-commerce). Dans ce scénario, il est plus logique que le compte connecté soit l’entité de règlement.

Vous pouvez définir le paramètre on_behalf_of sur l’ID d’un compte connecté pour faire de ce compte l’entité de règlement pour le paiement. Lorsque vous utilisez on_behalf_of :

• Les paiements sont réglés dans le pays et dans la devise de règlement du compte connecté.
• La structure des frais appliquée est celle du pays du compte connecté.
• Le libellé de relevé bancaire du compte connecté apparaît sur le relevé de carte bancaire du client.
• Si le compte connecté relève d’un autre pays que celui de la plateforme, l’adresse et le numéro de téléphone du compte connecté sont affichés sur le relevé de carte bancaire du client.
• Le nombre de jours durant lesquels un solde en attente est bloqué avant d’être versé dépend du paramètre delay_days du compte connecté.

Si le paramètre on_behalf_of est ignoré, la plateforme est l’entreprise de référence pour le paiement.

Émettre des remboursements

Si vous utilisez l’API Payment Intents, les remboursements doivent être émis sur le dernier paiement créé.

Les paiements créés sur le compte de la plateforme peuvent être remboursés en utilisant la clé secrète du compte de la plateforme. Lorsque vous remboursez un paiement comportant un transfer_data[destination], par défaut le compte de destination garde les fonds transférés, laissant le compte de la plateforme couvrir le solde négatif du remboursement. Pour récupérer les fonds du compte connecté afin de couvrir le remboursement, définissez le paramètre reverse_transfer sur true lors de la création du remboursement :

curl https://api.stripe.com/v1/refunds \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -d charge="{CHARGE_ID}" \
  -d reverse_transfer=true \

Par défaut, la totalité du paiement est remboursée, mais vous pouvez créer un remboursement partiel en définissant le paramètre amount sur un nombre entier positif.

Si le remboursement entraîne le remboursement de la totalité du paiement, la totalité du transfert est annulée. Dans le cas contraire, un montant proportionnel du transfert est annulé.

Rembourser les commissions de la plateforme

Lorsque vous remboursez un paiement comportant une commission de la plateforme, par défaut le compte de la plateforme garde les fonds correspondant à la commission. Pour rediriger ces fonds vers le compte connecté, définissez le paramètre refund_application_fee sur true lors de la création du remboursement :

curl https://api.stripe.com/v1/refunds \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -d charge="{CHARGE_ID}" \
  -d reverse_transfer=true \
  -d refund_application_fee=true \

Notez que si vous remboursez la commission de la plateforme pour un paiement indirect, vous devez également annuler le transfert. Si le remboursement se traduit par le remboursement de la totalité du paiement, la totalité de la commission est également remboursée. Dans le cas contraire, un montant proportionnel de la commission est remboursé.

Vous pouvez également indiquer la valeur false pour refund_application_fee et rembourser la commission de la plateforme séparément via l’API.

Remboursements ayant échoué

Si un remboursement échoue ou si vous l’annulez, le montant du remboursement ayant échoué est recrédité sur le solde Stripe de votre compte de plateforme. Créez un transfert pour envoyer les fonds vers le compte connecté, le cas échéant.

Gérer les litiges

Pour les paiements indirects, avec ou sans le paramètre on_behalf_of, Stripe débite le montant du litige et les frais de votre compte de plateforme.

Nous vous recommandons de configurer un webhook pour écouter les événements créés par un litige. Dans ce cas, vous pouvez tenter de récupérer les fonds auprès du compte connecté en annulant le transfert dans le Dashboard ou en créant une annulation de transfert.

Lorsque le compte connecté a un solde négatif, Stripe tente de débiter son compte externe si debit_negative_balances est défini sur true.

Si vous contestez le litige et obtenez gain de cause, vous pouvez renvoyer le paiement précédemment annulé au compte connecté. Si le solde de votre plateforme est insuffisant, le transfert échoue. Pour éviter tout problème lié aux soldes insuffisants, ajoutez des fonds à votre solde Stripe.