Effectuer l'intégration avec l'API Invoicing

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

# Available as a gem
sudo gem install stripe

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

Pour créer un produit, saisissez son nom :

curl https://api.stripe.com/v1/products \
  -u "
sk_test_VePHdqKTYQjKNInc7u56JBrQ
:" \
  -d "name=Gold Special"

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).

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 :

curl https://api.stripe.com/v1/prices \
  -u "
sk_test_VePHdqKTYQjKNInc7u56JBrQ
:" \
  -d "product=
{{PRODUCT_ID}}" \
  -d unit_amount=1000 \
  -d currency=usd

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 configuré par le client, soit un Customer.

curl -X POST https://api.stripe.com/v2/core/accounts \
  -H "Authorization: Bearer 
sk_test_VePHdqKTYQjKNInc7u56JBrQ
" \
  -H "Stripe-Version: 2026-06-24.preview" \
  --json '{
    "contact_email": "jenny.rosen@example.com",
    "display_name": "Jenny Rosen",
    "configuration": {
        "customer": {
            "capabilities": {}
        }
    },
    "include": [
        "configuration.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.

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.

curl https://api.stripe.com/v1/invoices \
  -u "
sk_test_VePHdqKTYQjKNInc7u56JBrQ
:" \
  -d "customer_account=
{{CUSTOMER_ACCOUNT_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.

curl https://api.stripe.com/v1/invoiceitems \
  -u "
sk_test_VePHdqKTYQjKNInc7u56JBrQ
:" \
  -d "customer_account=
{{CUSTOMER_ACCOUNT_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. 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 :

curl -X POST https://api.stripe.com/v1/invoices/
{{INVOICE_ID}}
/finalize \
  -u "
sk_test_VePHdqKTYQjKNInc7u56JBrQ
:"

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

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.

Les paiements de facture réussis déclenchent à la fois un événement invoice.paid et 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. 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 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 :