# Effectuer l'intégration avec l'API Invoicing Apprenez à coder pour créer et envoyer une facture au client. Le [Dashboard](https://dashboard.stripe.com/invoices) est le moyen le plus courant de [créer des factures](https://docs.stripe.com/invoicing/dashboard.md#create-invoice). 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](https://docs.stripe.com/invoicing/integration/quickstart.md). ## Configurer Stripe Utilisez nos bibliothèques officielles pour accéder à l’API Stripe : #### Ruby ```bash # Available as a gem sudo gem install stripe ``` ```ruby # If you use bundler, you can add this line to your Gemfile gem 'stripe' ``` ## Créer un produit Pour créer un produit, saisissez son nom : ```curl curl https://api.stripe.com/v1/products \ -u "<>:" \ -d "name=Gold Special" ``` ## Créer un tarif L’API [Prices](https://docs.stripe.com/api.md#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). Si vous n’avez pas besoin de créer un tarif pour votre produit, vous pouvez également utiliser le paramètre [amount](https://docs.stripe.com/api/invoiceitems/create.md#create_invoiceitem-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 : ```curl curl https://api.stripe.com/v1/prices \ -u "<>:" \ -d "product={{PRODUCT_ID}}" \ -d unit_amount=1000 \ -d currency=usd ``` ## Créer un client Lorsque vous créez une facture, vous avez besoin d’un objet pour représenter le client qui achète votre produit. Cet objet peut être soit un [Account](https://docs.stripe.com/api/v2/core/accounts/object.md#v2_account_object-configuration-customer) configuré par le client, soit un [Customer](https://docs.stripe.com/api/customers/object.md). > #### Utiliser l’API Accounts v2 pour représenter les clients > > L’API Accounts v2 est généralement disponible pour les utilisateurs de Connect et en aperçu public pour les autres utilisateurs de Stripe. Si vous avez accès à l’aperçu Accounts v2, vous devez [spécifier une version d’aperçu](https://docs.stripe.com/api-v2-overview.md#sdk-and-api-versioning) dans votre code. > > Pour demander l’accès à l’aperçu Accounts v2, > > Dans la plupart des cas d’usage, nous vous recommandons de [modéliser vos clients en tant qu’objets Account configurés par le client](https://docs.stripe.com/accounts-v2/use-accounts-as-customers.md), plutôt que d’utiliser des objets [Customer](https://docs.stripe.com/api/customers.md). #### Accounts v2 Pour créer un [Account](https://docs.stripe.com/api/v2/core/accounts/create.md#v2_create_accounts-configuration-customer) configuré par le client avec un `display_name` et un `contact_email`, comme dans l’exemple suivant : ```curl curl -X POST https://api.stripe.com/v2/core/accounts \ -H "Authorization: Bearer <>" \ -H "Stripe-Version: 2026-04-22.preview" \ --json '{ "contact_email": "jenny.rosen@example.com", "display_name": "Jenny Rosen", "configuration": { "customer": { "capabilities": {} } }, "include": [ "configuration.customer" ] }' ``` #### Customers v1 Pour créer un [Customer](https://docs.stripe.com/api/customers/create.md) avec un `name`, un `email` et une `description`, comme dans l’exemple suivant : ```curl curl https://api.stripe.com/v1/customers \ -u "<>:" \ -d "name=Jenny Rosen" \ --data-urlencode "email=jenny.rosen@example.com" \ -d "description=My first customer" ``` 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. ## Créer une facture Définissez l’attribut [collection_method](https://docs.stripe.com/api/invoices/object.md#invoice_object-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](https://docs.stripe.com/api/invoices/create.md#create_invoice-days_until_due). Stripe envoie au client la facture et des instructions de paiement par e-mail. #### Accounts v2 ```curl curl https://api.stripe.com/v1/invoices \ -u "<>:" \ -d "customer_account={{CUSTOMERACCOUNT_ID}}" \ -d collection_method=send_invoice \ -d days_until_due=30 ``` #### Customers v1 ```curl curl https://api.stripe.com/v1/invoices \ -u "<>:" \ -d "customer={{CUSTOMER_ID}}" \ -d collection_method=send_invoice \ -d days_until_due=30 ``` Ensuite, créez un poste de facture en transmettant l’identifiant du client, le `price` du produit et l’ID de la `Invoice`. Le nombre maximal de postes de facture est de 250. #### Accounts v2 ```curl curl https://api.stripe.com/v1/invoiceitems \ -u "<>:" \ -d "customer_account={{CUSTOMERACCOUNT_ID}}" \ -d "pricing[price]={{PRICE_ID}}" \ -d "invoice={{INVOICE_ID}}" ``` #### Customers v1 ```curl curl https://api.stripe.com/v1/invoiceitems \ -u "<>:" \ -d "customer={{CUSTOMER_ID}}" \ -d "pricing[price]={{PRICE_ID}}" \ -d "invoice={{INVOICE_ID}}" ``` Lorsque vous définissez `auto_advance` sur `false`, vous pouvez continuer à modifier la facture jusqu’à sa [finalisation](https://docs.stripe.com/invoicing/integration/workflow-transitions.md). 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](https://docs.stripe.com/api/invoices/finalize.md) : ```curl curl -X POST https://api.stripe.com/v1/invoices/{{INVOICE_ID}}/finalize \ -u "<>:" ``` Si vous créez une facture par erreur, [annulez-la](https://docs.stripe.com/invoicing/overview.md#void). Vous pouvez également marquer une facture comme [irrécouvrable](https://docs.stripe.com/invoicing/overview.md#uncollectible). ## Accepter le paiement de la facture #### Envoyer une facture Envoyez la facture à l’adresse e-mail associée au client. Stripe finalise la facture dès que vous l’envoyez. De nombreuses juridictions considèrent les factures finalisées comme des documents juridiques, ce qui rend impossible la modification de certains champs. Si vous envoyez des factures qui ont déjà été payées, l’e-mail ne fait pas référence au paiement. > L’e-mail ne contient pas de référence au paiement lorsque vous envoyez une facture qui a déjà été payée. Stripe envoie les factures à l’adresse e-mail associée au client. ```curl curl -X POST https://api.stripe.com/v1/invoices/{{INVOICE_ID}}/send \ -u "<>:" ``` #### Stripe Elements Lorsque la facture est finalisée, un *PaymentIntent* (The Payment Intents API tracks the lifecycle of a customer checkout flow and triggers additional authentication steps when required by regulatory mandates, custom Radar fraud rules, or redirect-based payment methods) est généré et associé à la facture. Utilisez [Stripe Elements](https://docs.stripe.com/payments/elements.md) pour collecter les informations de paiement et confirmer le PaymentIntent de la facture. 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](https://docs.stripe.com/api/payment_intents/update.md), vous pouvez uniquement modifier les paramètres `setup_future_usage`, `metadata`, `payment_method`, `description`, `receipt_email`, `payment_method_data`, `payment_method_options` et `shipping`. #### Payment Element (recommandé) Le composant [Payment Element](https://docs.stripe.com/payments/payment-element.md) 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](https://docs.stripe.com/payments/payment-methods/payment-method-support.md) 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](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-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](https://docs.stripe.com/api/expanding_objects.md) son attribut [confirmation_secret](https://docs.stripe.com/api/invoices/object.md#invoice_object-confirmation_secret) lors de la [finalisation](https://docs.stripe.com/api/invoices/finalize.md) de la facture ou lorsque vous effectuez un autre appel API, tel que [retrieve](https://docs.stripe.com/api/invoices/retrieve.md) ou [update](https://docs.stripe.com/api/invoices/update.md)) sur la facture après l’avoir finalisée. Renvoyez le `client_secret` au front-end pour finaliser le paiement. ```curl curl https://api.stripe.com/v1/invoices/{{INVOICE_ID}}/finalize \ -u "<>:" \ -d "expand[]=confirmation_secret" ``` Une fois la facture renvoyée, accédez à la clé secrète du client dans le champ `confirmation_secret` développé. #### curl #### CLI Stripe #### Ruby ```ruby client_secret = invoice.confirmation_secret.client_secret ``` #### Python ```python client_secret = invoice.confirmation_secret.client_secret ``` #### PHP ```php $client_secret = $invoice->confirmation_secret->client_secret; ``` #### Java ```java String clientSecret = invoice.getConfirmationSecret().getClientSecret(); ``` #### Node.js ```javascript const client_secret = invoice.confirmation_secret.client_secret; ``` #### Go ```go clientSecret := invoice.ConfirmationSecret.ClientSecret ``` #### .NET ```csharp var clientSecret = invoice.ConfirmationSecret.ClientSecret; ``` ### 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. ```html Pay Invoice ``` Créez une instance de Stripe avec le code JavaScript suivant sur votre page de paiement : ```javascript // 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('<>'); ``` ### 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. ```html
``` 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. ```javascript 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](https://docs.stripe.com/elements/appearance-api.md) 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* (Strong Customer Authentication (SCA) is a regulatory requirement in effect as of September 14, 2019, that impacts many European online payments. It requires customers to use two-factor authentication like 3D Secure to verify their purchase) (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](https://docs.stripe.com/api/payment_intents/confirm.md#confirm_payment_intent-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. ```javascript 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](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-client_secret) de l’objet `PaymentIntent`. Pour les intégrations d’abonnements, le client_secret est également exposé sur l’objet `Invoice` via [`confirmation_secret`](https://docs.stripe.com/api/invoices/object.md#invoice_object-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. > 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](https://docs.stripe.com/payments/paymentintents/lifecycle.md) 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. ```javascript // Initialize Stripe.js using your publishable key const stripe = Stripe('<>'); // 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; } }); ``` #### Card Element L’Element Card collecte et valide de manière sécurisée les informations de carte bancaire de votre client. ### Transmettre la clé secrète du client au front-end Stripe.js utilise le [client_secret](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-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](https://docs.stripe.com/api/expanding_objects.md) son attribut [confirmation_secret](https://docs.stripe.com/api/invoices/object.md#invoice_object-confirmation_secret) lors de la [finalisation](https://docs.stripe.com/api/invoices/finalize.md) de la facture ou lorsque vous effectuez un autre appel API, tel que [retrieve](https://docs.stripe.com/api/invoices/retrieve.md) ou [update](https://docs.stripe.com/api/invoices/update.md)) sur la facture après l’avoir finalisée. Renvoyez le `client_secret` au front-end pour finaliser le paiement. ```curl curl https://api.stripe.com/v1/invoices/{{INVOICE_ID}}/finalize \ -u "<>:" \ -d "expand[]=confirmation_secret" ``` Une fois la facture renvoyée, accédez à la clé secrète du client dans le champ `confirmation_secret` développé. #### curl #### CLI Stripe #### Ruby ```ruby client_secret = invoice.confirmation_secret.client_secret ``` #### Python ```python client_secret = invoice.confirmation_secret.client_secret ``` #### PHP ```php $client_secret = $invoice->confirmation_secret->client_secret; ``` #### Java ```java String clientSecret = invoice.getConfirmationSecret().getClientSecret(); ``` #### Node.js ```javascript const client_secret = invoice.confirmation_secret.client_secret; ``` #### Go ```go clientSecret := invoice.ConfirmationSecret.ClientSecret ``` #### .NET ```csharp var clientSecret = invoice.ConfirmationSecret.ClientSecret; ``` ### Configurer Stripe Elements Stripe Elements est inclus dans 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 un lot ni en héberger de copie. ```html Subscription prices ``` Créez une instance d’Elements avec le JavaScript suivant : ```javascript // Set your publishable key: remember to change this to your live publishable key in production // See your keys here: https://dashboard.stripe.com/apikeys let stripe = Stripe('<>'); let elements = stripe.elements(); ``` ### Ajouter Elements à votre page Vous devez attribuer un emplacement dédié à vos Elements dans votre formulaire de paiement. Créez des nœuds DOM vides (conteneurs) possédant des ID uniques dans votre formulaire de paiement, puis transmettez ces ID aux Elements. ```html
``` Créez une instance d’un Element et montez-la sur le conteneur Element : ```javascript let card = elements.create('card', { style: style }); card.mount('#card-element'); ``` L’Element `card` simplifie le formulaire et réduit le nombre de champs requis en insérant un champ de saisie unique flexible qui collecte en toute sécurité l’ensemble des informations de carte bancaire nécessaires. Consultez notre [documentation Stripe.js](https://docs.stripe.com/js.md#elements_create) pour obtenir la liste complète des types d’Elements pris en charge. Utilisez le numéro de carte de test **4242 4242 4242 4242**, un code CVC à trois chiffres, une date d’expiration future et un code postal à cinq chiffres. Elements valide les informations dès leur saisie par l’utilisateur. Pour aider vos clients à repérer d’éventuelles erreurs, écoutez les événements `change` de la propriété Elements `card` et affichez les erreurs : ```javascript card.on('change', function (event) { displayError(event); }); function displayError(event) { changeLoadingStatePrices(false); let displayError = document.getElementById('card-element-errors'); if (event.error) { displayError.textContent = event.error.message; } else { displayError.textContent = ''; } } ``` La [validation du code postal](https://docs.stripe.com/js.md#postal-code-formatting) dépend du pays de facturation de votre client. Pour tester d’autres formats de code postal, vous pouvez utiliser nos [cartes de test internationales](https://docs.stripe.com/testing.md#international-cards). ### Mener à bien le paiement Lorsque votre client soumet le formulaire Elements, appelez `stripe.confirmCardPayment` avec la *clé secrète du client* (The client secret is a unique key returned from Stripe as part of a PaymentIntent. This key lets the client access important fields from the PaymentIntent (status, amount, currency) while hiding sensitive ones (metadata, customer)) que vous avez transmise à votre front-end. Cela crée un moyen de paiement et *confirme* (Confirming an intent indicates that the customer intends to use the current or provided payment method. Upon confirmation, the intent attempts to initiate the portions of the flow that have real-world side effects) le PaymentIntent de la facture, ce qui déclenche un paiement. Si l’*authentification forte du client* (Strong Customer Authentication (SCA) is a regulatory requirement in effect as of September 14, 2019, that impacts many European online payments. It requires customers to use two-factor authentication like 3D Secure to verify their purchase) (SCA) est requise pour le paiement, Elements gère le processus d’authentification avant de confirmer le PaymentIntent. ```javascript const btn = document.querySelector('#submit-payment-btn'); btn.addEventListener('click', async (e) => { e.preventDefault(); const nameInput = document.getElementById('name'); // Create payment method and confirm PaymentIntent. stripe.confirmCardPayment(clientSecret, { payment_method: { card: cardElement, billing_details: { name: nameInput.value, }, } }).then((result) => { if(result.error) { alert(result.error.message); } else { // Successful invoice payment } }); }); ``` ## Gérer les événements post-paiement Stripe envoie un événement [invoice.paid](https://docs.stripe.com/api/events/types.md?event_types-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](https://stripe.com/payments/payment-methods-guide) avec une seule intégration. Les paiements de facture réussis déclenchent à la fois un événement [invoice.paid](https://docs.stripe.com/api/events/types.md?event_types-invoice.paid) et [invoice.payment_succeeded](https://docs.stripe.com/api/events/types.md?event_types-invoice.payment_succeeded). Les deux types d’événements contiennent les mêmes données de facture, il suffit donc d’en écouter un pour être notifié des paiements réussis. La différence est la suivante : les événements `invoice.payment_succeeded` sont envoyés pour les paiements de facture réussis, mais ne sont pas envoyés lorsque vous marquez une facture comme [paid_out_of_band](https://docs.stripe.com/api/invoices/pay.md#pay_invoice-paid_out_of_band). Cependant, les événements `invoice.paid` sont déclenchés à la fois pour les paiements réussis et les paiements hors flux standard. Étant donné que `invoice.paid` couvre les deux scénarios, il est généralement recommandé d’écouter `invoice.paid` plutôt que `invoice.payment_succeeded`. Utilisez l’[outil de webhook du Dashboard](https://dashboard.stripe.com/webhooks) ou suivez le [Quickstart consacré aux webhooks](https://docs.stripe.com/webhooks/quickstart.md) 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](https://docs.stripe.com/api/events/types.md?lang=php#event_types-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](https://docs.stripe.com/api/events/types.md?lang=php#event_types-payment_intent.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. | ## Optional: Personnaliser une facture Vous pouvez [personnaliser les factures](https://docs.stripe.com/invoicing/customize.md) de plusieurs façons. Les options de personnalisation offertes par Stripe vous permettent d’ajouter votre propre image de marque et de modifier vos factures afin qu’elles soient conformes aux régions dans lesquelles vous travaillez. ### Champs personnalisés Ajoutez des champs personnalisés pour améliorer vos documents PDF de facture et vous aider à respecter vos pratiques professionnelles et vos obligations de déclaration fiscale. Les champs personnalisés vous permettent de fournir jusqu’à quatre paires clé-valeur qui s’affichent dans l’en-tête de la facture. Vous pouvez définir jusqu’à quatre paires clé-valeur de champ personnalisé dans l’[éditeur de factures](https://dashboard.stripe.com/invoices/create) ou avec l’[API Invoices](https://docs.stripe.com/api/invoices/create.md#create_invoice-custom_fields) ou avec les [modèles de facture](https://docs.stripe.com/invoicing/invoice-rendering-template.md). Voici des exemples courants d’utilisation des champs personnalisés : - Numéros de bon de commande - Numéros de sous-traitant - Conformité fiscale Voici un exemple de création d’une facture avec un numéro de bon de commande et la taxe sur la valeur ajoutée (TVA) comme champs personnalisés : #### Accounts v2 ```curl curl https://api.stripe.com/v1/invoices \ -u "<>:" \ -d "customer_account={{CUSTOMERACCOUNT_ID}}" \ -d "custom_fields[0][name]=PO number" \ -d "custom_fields[0][value]=12345" \ -d "custom_fields[1][name]=VAT" \ -d "custom_fields[1][value]=123ABC" ``` #### Customers v1 ```curl curl https://api.stripe.com/v1/invoices \ -u "<>:" \ -d "customer={{CUSTOMER_ID}}" \ -d "custom_fields[0][name]=PO number" \ -d "custom_fields[0][value]=12345" \ -d "custom_fields[1][name]=VAT" \ -d "custom_fields[1][value]=123ABC" ``` #### Champs personnalisés hérités Vous pouvez définir des champs de facture personnalisés sur l’objet qui représente votre client. Les champs personnalisés que vous définissez au niveau du client s’appliquent à tous les brouillons de factures que vous générez pour ce client. Vous pouvez toujours modifier ces champs personnalisés hérités tant que la facture est encore à l’état de brouillon. Une fois la facture finalisée, vous ne pouvez plus mettre à jour les champs personnalisés. #### Accounts v2 Voici un exemple d’ajout de [custom_fields](https://docs.stripe.com/api/v2/core/accounts/create.md#v2_create_accounts-configuration-customer-billing-invoice-custom_fields) au niveau du client à appliquer à tous les brouillons de facture à venir : ```curl curl -X POST https://api.stripe.com/v2/core/accounts \ -H "Authorization: Bearer <>" \ -H "Stripe-Version: 2026-04-22.preview" \ --json '{ "contact_email": "jenny.rosen@example.com", "display_name": "Jenny Rosen", "configuration": { "customer": { "billing": { "invoice": { "custom_fields": [ { "name": "PO number", "value": "12345" } ] } } } }, "include": [ "configuration.customer" ] }' ``` #### Customers v1 Voici un exemple d’ajout de [custom_fields](https://docs.stripe.com/api/customers/object.md#customer_object-invoice_settings-custom_fields) au niveau du client à appliquer à tous les brouillons de facture à venir : ```curl curl https://api.stripe.com/v1/customers \ -u "<>:" \ --data-urlencode "email=jenny.rosen@example.com" \ -d payment_method=pm_card_visa \ -d "invoice_settings[default_payment_method]=pm_card_visa" \ -d "invoice_settings[custom_fields][0][name]=PO number" \ -d "invoice_settings[custom_fields][0][value]=12345" \ -d "invoice_settings[custom_fields][1][name]=VAT" \ -d "invoice_settings[custom_fields][1][value]=123ABC" ``` ## See also - [Post-finalisation](https://docs.stripe.com/invoicing/integration/workflow-transitions.md#post-finalized) - [Utiliser les webhooks entrants pour être informé des mises à jour en temps réel](https://docs.stripe.com/webhooks.md)