Effectuer l'intégration avec l'API Invoicing

Apprenez à coder pour créer et envoyer une facture au client.

Le Dashboard est le moyen le plus courant de créer des factures. Si vous souhaitez automatiser la création des factures, vous pouvez intégrer l’API. Créez une intégration Invoicing complète et fonctionnelle à l’aide de notre exemple d’intégration.

Remarque

Vous n’avez pas besoin d’intégrer l’API Payments pour intégrer l’API Invoicing.

Configurer Stripe

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

Créer un produit

Pour créer un produit, saisissez son nom :

Créer un tarif

L’API Prices définit le montant et la fréquence de facturation des produits. Dans le cadre d’un abonnement, elle détermine notamment le coût du produit, la devise à utiliser et la période de facturation. De même que pour les produits, si vous n’avez défini que quelques tarifs, il est préférable de les gérer dans le Dashboard. Utilisez le montant unitaire pour exprimer les tarifs dans l’unité la plus faible de la devise, en l’occurrence les centimes (10 USD correspondant à 1 000 centimes, le montant unitaire est 1 000).

Remarque

Si vous n’avez pas besoin de créer un tarif pour votre produit, vous pouvez également utiliser le paramètre amount lors de la création du poste de facture.

Pour créer un tarif et l’associer au produit, transmettez l’ID du produit, le montant unitaire et la devise. Dans l’exemple suivant, le tarif du produit « Gold Special » est fixé à 10 USD :

Créer un client

L’objet Customer représente le client qui achète votre produit. Il est obligatoire pour créer une facture. Pour créer un client avec un name, email et description, ajoutez le code suivant en remplaçant les valeurs par les vôtres :

Après avoir créé le client, enregistrez la valeur id du client dans votre base de données pour pouvoir la réutiliser ultérieurement. Par exemple, l’étape suivante utilise l’ID du client pour créer une facture.

Remarque

Consultez Créer un client pour accéder à des paramètres supplémentaires.

Créer une facture

Définissez l’attribut collection_method sur send_invoice. Pour que Stripe soit en mesure de marquer une facture comme étant en retard, renseignez le paramètre days_until_due. Stripe envoie au client la facture et des instructions de paiement par e-mail.

Ensuite, créez un poste de facture en transmettant l’id du client, le price du produit et la invoice de l’ID de la facture.

Le nombre maximal de postes de facture est de 250.

Lorsque vous définissez auto_advance sur false, vous pouvez continuer à modifier la facture jusqu’à sa finalisation. Pour finaliser un brouillon de facture, utilisez le Dashboard, envoyez la facture au client ou déclenchez son règlement. Vous pouvez également utiliser l’API Finalize :

Remarque

Si vous avez créé la facture par erreur, annulez-la. Vous pouvez également marquer la facture comme irrécouvrable.

Accepter le paiement de la facture

Lorsque la facture est finalisée, un PaymentIntent est généré et associé à la facture. Utilisez Stripe Elements pour collecter les informations de paiement et confirmer le PaymentIntent de la facture.

Remarque

Dès l’instant qu’une facture est finalisée, vous ne pouvez plus modifier les valeurs monétaires ni le paramètre collection_method. Cette restriction s’applique également au PaymentIntent de la facture finalisée. Lorsque vous mettez à jour le PaymentIntent d’une facture à l’aide d’un appel update, vous pouvez uniquement modifier les paramètres setup_future_usage, metadata, payment_method, description, receipt_email, payment_method_data, payment_method_options et shipping.

Le composant Payment Element collecte de manière sécurisée toutes les informations de paiement nécessaires pour un grand nombre de moyens de paiement. Consultez la section Prise en charge des produits et moyens de paiement pour déterminer si les moyens de paiement que vous avez sélectionnés sont pris en charge à la fois par Invoicing et par Payment Element.

Transmettre la clé secrète du client au front-end

Stripe.js utilise le client_secret du PaymentIntent pour mener à bien le processus de paiement en toute sécurité. Récupérez la clé secrète du client de la facture en développant son attribut confirmation_secret lors de la finalisation de la facture ou lorsque vous effectuez un autre appel API, tel que retrieve ou update) sur la facture après l’avoir finalisée. Renvoyez le client_secret au front-end pour finaliser le paiement.

Une fois la facture renvoyée, accédez à la clé secrète du client dans le champ confirmation_secret développé.

Configurer Stripe Elements

Le Payment Element est automatiquement disponible en tant que fonctionnalité de Stripe.js. Intégrez le script Stripe.js à votre page de paiement en l’ajoutant au head votre fichier HTML. Chargez toujours Stripe.js directement à partir de js.stripe.com pour rester conforme aux normes PCI. N’incluez pas le script dans un lot et n’en hébergez pas de copie.

pay-invoice.html
<head>
  <title>Pay Invoice</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 :

pay-invoice.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 l’Element Payment à votre page

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

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

Lorsque le formulaire est chargé, créez une instance du Payment Element et la monter sur le nœud DOM du conteneur. Transmettez la clé secrète du client du PaymentIntent comme option lors de la création d’une instance d’Elements.

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

// Set up Stripe.js and Elements to use in your checkout form, passing in the client secret.
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 Element Payment affiche un formulaire dynamique qui permet à votre client de choisir un moyen de paiement. Le formulaire collecte automatiquement toutes les informations de paiement nécessaires pour le moyen de paiement sélectionné par le client.

Vous pouvez adapter le Payment Element au design de votre site en transmettant l’objet Appearance dans les options lors de la création d’une instance d’Elements.

Mener à bien le paiement

Utilisez stripe.confirmPayment pour mener à bien le paiement à l’aide des informations du composant Payment Element. Un moyen de paiement est alors créé et le PaymentIntent de la facture est confirmé, ce qui déclenche le processus de paiement. Si une authentication forte du client (SCA) est requise pour le paiement, le composant Payment Element gère le processus d’authentification avant de confirmer le PaymentIntent.

Ajoutez une URL return_url à la fonction confirmPayment pour indiquer la page vers laquelle Stripe doit rediriger l’utilisateur une fois le paiement effectué. Votre utilisateur peut être d’abord redirigé vers un site intermédiaire, comme une page d’autorisation bancaire, avant d’être redirigé vers l’URL return_url. Les paiements par carte bancaire sont immédiatement redirigés vers l’URL return_url à la réussite du paiement.

pay-invoice.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`.
  }
});

Lorsque votre client effectue un paiement, Stripe le redirige vers l’URL return_url et inclut les paramètres de requête d’URL suivants. La page de redirection peut utiliser ces paramètres pour récupérer l’état du PaymentIntent et ainsi afficher l’état du paiement pour le client.

Lorsque vous spécifiez une URL return_url, vous pouvez également ajouter vos propres paramètres de requête à utiliser sur la page de redirection.

Paramètre	Description
`payment_intent`	Identifiant unique du `PaymentIntent`.
`payment_intent_client_secret`	La clé secrète du client de l’objet `PaymentIntent`. Pour les intégrations d’abonnements, le client_secret est également exposé sur l’objet `Invoice` via `confirmation_secret`

Lorsque le client est redirigé vers votre site, vous pouvez utiliser le payment_intent_client_secret pour interroger le PaymentIntent et communiquer l’état de la transaction à votre client.

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 le paramètre de requête payment_intent_client_secret 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.

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

Stripe envoie un événement invoice.paid à chaque règlement de facture. Écoutez cet événement pour garantir le bon traitement de la commande. Si votre intégration s’appuie sur un rappel côté client, il est possible que l’utilisateur perde la connexion avant l’exécution du rappel. Le client serait client alors facturé sans que votre serveur n’en soit informé. Le fait de configurer votre intégration de manière à ce qu’elle écoute les événements asynchrones vous permet également d’accepter différents types de méthodes de paiement avec une seule intégration.

Remarque

Les paiements de factures déclenchent les événements invoice.paid et invoice.payment_succeeded. Chacun de ces deux types d’événements contiennent les mêmes données de facturation. C’est pourquoi vous n’avez besoin que d’écouter l’un des deux pour être notifié des paiements de factures réussis. La différence est que les événements invoice.payment_succeeded sont envoyés pour les paiements de factures réussis, mais ne sont pas envoyés lorsque vous marquez une facture comme paid_out_of_band. Les événements invoice.paid, quant à eux, sont déclenchés à la fois pour les paiements réussis et pour les paiements hors bande. Comme invoice.paid couvre les deux scénarios, nous recommandons généralement d’écouter invoice.paid plutôt que invoice.payment_succeeded.

Utilisez l’outil de webhook du Dashboard ou suivez le Quickstart 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.

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

Événement	Description	du client
payment_intent.processing	Envoyé lorsqu’un client a initié un paiement, mais qu’il ne l’a pas encore finalisé. Dans la plupart des cas, cet événement est envoyé lorsqu’un prélèvement a été effectué. Il est suivi par un événement `invoice.paid` ou `invoice.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é.
invoice.payment_failed	Envoyé lorsqu’un client a tenté de régler une facture, mais que le paiement a échoué.	Si un paiement passe de l’état `processing` à `payment_failed`, proposez au client de retenter le paiement.

Effectuer l'intégration avec l'API Invoicing

Apprenez à coder pour créer et envoyer une facture au client.

Remarque

Configurer Stripe

Créer un produit

Créer un tarif

Remarque

Créer un client

Remarque

Créer une facture

Remarque

Accepter le paiement de la facture

Remarque

Transmettre la clé secrète du client au front-end

Configurer Stripe Elements

Ajouter l’Element Payment à votre page

Mener à bien le paiement

Mise en garde

Gérer les événements post-paiement

Remarque

FacultatifPersonnaliser une facture

Voir aussi