Accéder directement au contenu
Créez un compte ou connecter-vous
Logo de la documentation Stripe
/
Créez un compteConnectez-vous
Aperçu
Billing
PrésentationÀ propos des API Billing
Tax
Présentation
Rapports
PrésentationRapports sur plusieurs comptes
Données
Présentation

Collecter des taxes

Utilisez les API Stripe Tax pour implémenter le calcul des taxes dans votre intégration personnalisée.

Les API Stripe Tax vous permettent de calculer les taxes dans vos tunnels de paiement personnalisés. Une fois le paiement effectué par votre client, enregistrez la transaction pour qu’elle apparaisse dans les rapports de Stripe Tax. Les exemples de ce guide se basent sur les paiements Stripe, mais vous pouvez utiliser l’API Tax avec n’importe quel prestataire de services de paiement ou plusieurs prestataires de services de paiement.

Pour la plupart des intégrations, nous vous recommandons d’utiliser l’API Checkout Sessions avec Stripe Tax.

Vous pouvez également intégrer Stripe Tax avec Payment Links, Checkout, Billing et Invoicing avec des configurations no-code ou low-code.

Les API Stripe Tax vous permettent de calculer les taxes dans vos tunnels de paiement personnalisés. Une fois le paiement effectué par votre client, enregistrez la transaction pour qu’elle apparaisse dans les rapports de Stripe Tax. Les exemples de ce guide se basent sur les paiements Stripe, mais vous pouvez utiliser l’API Tax avec n’importe quel prestataire de services de paiement ou plusieurs prestataires de services de paiement.

If your custom payment flow uses the Payment Intents API, see Calculate tax in your custom payment flows. This integration offers automatic liability tracking, receipts and Dashboard support.

Vous pouvez également intégrer Stripe Tax avec Payment Links, Checkout, Billing et Invoicing avec des configurations no-code ou low-code.

Démarrer

Cette courte vidéo présente une intégration de l’API Stripe Tax utilisant l’API Payment Intents et l’Element Payment.

Chargement du contenu vidéo...

Ajouter des immatriculations

Stripe Tax calcule les taxes uniquement dans les juridictions où vous êtes immatriculé pour collecter la TVA. Vous devez ajouter vos immatriculations fiscales dans le Dashboard.

FacultatifCollecter l'adresse du client
Côté client

La taxe que vous collectez dépend généralement de l’emplacement de votre client. Pour un calcul de taxe plus précis, veuillez collecter l’adresse complète de votre client. Avant de collecter l’adresse, vous pouvez afficher une estimation à votre client en fonction de son adresse IP.

Remarque

Les exemples ci-dessous utilisent un simple formulaire d’adresse personnalisé, mais vous pouvez également utiliser le composant Adress Element pour collecter les adresses des clients avec des fonctionnalités de saisie semi-automatique et de localisation.

Le formulaire ci-dessous exige la saisie d’une adresse postale complète :

checkout.html
<form>
    <label for="address_line1">Address Line 1</label> <input type="text" id="address_line1" />
    <label for="address_city">City</label> <input type="text" id="address_city" />
    <label for="address_state">State</label> <select id="address_state">
      <option value="WA">Washington</option>
      <!-- add more states here -->
    </select>
    <label for="address_postal_code">Postal code</label> <input type="text" id="address_postal_code" />
    <label for="address_country">Country</label> <select id="address_country">
      <option value="US">United States</option>
      <option value="DE">Germany</option>
      <option value="IE">Ireland</option>
      <!-- add more countries here -->
    </select>
</form>

Vous pouvez transmettre l’adresse à l’endpoint de votre serveur comme suit :

checkout.js
const address = {
  line1: document.getElementById('address_line1').value,
  city: document.getElementById('address_city').value,
  state: document.getElementById('address_state').value,
  postal_code: document.getElementById('address_postal_code').value,
  country: document.getElementById('address_country').value,
};
var response = fetch('/preview-cart', {
  method: 'POST',
  body: JSON.stringify({address: address}),
  headers: {'Content-Type': 'application/json'},
}).then(function(response) {
  return response.json();
}).then(function(responseJson) {
  // Handle errors, or display calculated tax to your customer.
});

Les informations d’adresse requises pour le calcul de la taxe varient selon le pays du client :

  • États-Unis : nous exigeons au moins le code postal de votre client. Pour un calcul plus précis des taxes, nous vous recommandons de fournir une adresse complète.
  • Canada : nous avons besoin du code postal ou de la province de votre client.
  • Autres pays : nous exigeons uniquement le code pays de votre client.

Calculer la taxe
Côté serveur

Vous choisissez quand et à quelle fréquence calculer la taxe. Par exemple, vous pouvez :

  • Montrez une estimation des taxes basée sur l’adresse IP de votre client lorsqu’il accède à votre tunnel de paiement
  • Recalculer les taxes lorsque le client saisit son adresse de facturation ou de livraison
  • Calculer le montant final de la taxe à percevoir lorsque votre client a saisi son adresse

Stripe facture des frais par appel API de calcul de taxe. Vous pouvez limiter les appels API de calcul de taxe afin de gérer vos coûts.

Les exemples ci-dessous montrent comment calculer la taxe dans différents scénarios. Stripe Tax ne calcule la taxe que dans les juridictions où vous avez effectué votre enregistrement pour la percevoir. Vous devez ajouter vos immatriculations fiscales dans le Dashboard.

Cet exemple calcule la taxe pour une adresse de livraison aux États-Unis. Le poste a un prix de 10 USD et utilise le code fiscal prédéfini de votre compte.

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl https://api.stripe.com/v1/tax/calculations \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d currency=usd \
  -d "line_items[0][amount]"=1000 \
  -d "line_items[0][reference]"=L1 \
  -d "customer_details[address][line1]"="920 5th Ave" \
  -d "customer_details[address][city]"=Seattle \
  -d "customer_details[address][state]"=WA \
  -d "customer_details[address][postal_code]"=98104 \
  -d "customer_details[address][country]"=US \
  -d "customer_details[address_source]"=shipping

La réponse de calcul contient des montants que vous pouvez afficher à votre client, et utiliser pour accepter les paiements :

AttributDescription
amount_totalLe montant total après calcul des taxes. Utilisez ce montant pour définir le montant du PaymentIntent à facturer à votre client.
tax_amount_exclusiveLe montant des taxes qui vient s’ajouter aux postes de facture et aux frais de livraison, faisant s’accroître la valeur amount_total. Utilisez-le pour indiquer à votre client le montant de taxes ajouté au sous-total de la transaction.
tax_amount_inclusiveLe montant des taxes inclus dans vos postes de facture et vos frais de livraison (si vous avez opté pour les tarification TTC). Ce montant n’augmente pas la valeur amount_total. Utilisez-le pour communiquer à votre client quelle est la part des taxes dans le montant total payé.
tax_breakdownListe de montants de taxe répartis par taux d’imposition du pays ou de l’État. Vous pouvez vous en servir pour indiquer à vos clients quelles taxes vous collectez.

Gérer les erreurs d’emplacement du client

Le calcul renvoie le code d’erreur customer_tax_location_invalid si l’adresse de votre client est invalide ou n’est pas suffisamment précise pour calculer la taxe :

{
  "error": {
    "doc_url": "https://docs.stripe.com/error-codes#customer-tax-location-invalid",
    "code": "customer_tax_location_invalid",
    "message": "We could not determine the customer's tax location based on the provided customer address.",
    "param": "customer_details[address]",
    "type": "invalid_request_error"
  }
}

Si vous recevez cette erreur, demandez à votre client de vérifier l’adresse saisie et de corriger toute éventuelle faute de frappe.

Utiliser le calcul avec un autre sous-traitant

Si vous traitez des transactions en dehors de Stripe, vous pouvez ignorer les étapes suivantes et appliquer le calcul à vos transactions traitées en externe.

Créer une transaction fiscale
Côté serveur

La création d’une transaction fiscale enregistre les taxes que vous avez collectées auprès de votre client, afin que vous puissiez ultérieurement télécharger des exports et générer des rapports pour faciliter votre déclaration fiscale. Vous pouvez créer une transaction à partir d’un calcul jusqu’à la date d’expiration (expires_at), soit 90 jours après sa création. Toute tentative d’utilisation après cette période renverra une erreur.

Remarque

La transaction est considérée comme effective à la date d’appel de create_from_calculation, et les montants de taxe ne seront pas recalculés.

Lorsque vous créez une transaction fiscale, vous devez fournir une reference unique pour la transaction et pour chaque poste de facture. Ces références apparaissent dans les exports des taxes et permettent de rapprocher les taxes perçues et les commandes de votre système.

Par exemple, une transaction fiscale portant la référence pi_123456789, les références de poste de facture L1 et L2 et des frais de livraison prend la forme suivante dans les exportations détaillées des taxes.

IDline_item_idtypedevisetransaction_date
pi_123456789L1externeUSD23/02/2023 17:01:16
pi_123456789L2externeUSD23/02/2023 17:01:16
pi_123456789livraisonexterneUSD23/02/2023 17:01:16

Lorsque votre client paie, utilisez l’ID de calcul pour enregistrer la taxe perçue. Vous pouvez le faire de deux manières :

  • Si votre serveur dispose d’un endpoint où votre client soumet sa commande, vous pouvez créer la transaction fiscale une fois la commande soumise.
  • Écoutez l’événement webhook paiement_intent.succeeded. Récupérez l’identifiant de calcul à partir des metadata de PaymentIntent.

L’exemple ci-dessous crée une transaction et utilise l’identifiant PaymentIntent comme référence unique :

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl https://api.stripe.com/v1/tax/transactions/create_from_calculation \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d calculation={{TAX_CALCULATION}} \
  -d reference=
"{{PAYMENT_INTENT_ID}}"
 \
  -d "expand[]"=line_items

Sauvegardez l’identifiant de la transaction fiscale pour enregistrer les remboursements ultérieurement. Vous pouvez sauvegarder l’identifiant de la transaction dans votre base de données ou dans les métadonnées de la PaymentIntent :

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl https://api.stripe.com/v1/payment_intents/
{{PAYMENT_INTENT_ID}}
 \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d "metadata[tax_transaction]"={{TAX_TRANSACTION}}

Enregistrer des remboursements
Côté serveur

Après avoir créé une transaction fiscale correspondant à une vente à un client, vous devrez peut-être enregistrer des remboursements. Ces opérations sont représentées par des transactions fiscales dans lesquelles type=reversal. Les transactions d’annulation compensent des transactions antérieures en présentant des montants de signes opposés. Par exemple, le remboursement intégral d’une vente de 50 USD sera représenté par une opération de -50 USD.

Lorsque vous émettez un remboursement (via Stripe ou en dehors de Stripe), vous devez créer une transaction fiscale d’annulation avec une référence unique. Voici quelques stratégies courantes :

  • Ajoutez un suffixe à la référence originale. Par exemple, si la transaction d’origine porte la référence pi_123456789, créez une transaction d’annulation avec la référence pi_123456789-refund.
  • Utilisez l’ID de remboursement de Stripe ou un identifiant de remboursement provenant de votre système. Par exemplere_3MoslRBUZ691iUZ41bsYVkOg oumyRefund_456.

Choisissez l’approche qui fonctionne le mieux pour rapprocher les commandes de vos clients avec vos exportations fiscales.

Remboursement intégral d’une vente

Une fois que vous avez effectué le remboursement intégral d’une vente dans votre système, créez une transaction d’annulation avec le paramètre mode=full.

Dans l’exemple ci-dessous, tax_1MEFAAI6rIcR421eB1YOzACZ est la transaction fiscale qui enregistre la vente à votre client :

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl https://api.stripe.com/v1/tax/transactions/create_reversal \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d mode=full \
  -d original_transaction=tax_1MEFAAI6rIcR421eB1YOzACZ \
  -d reference=pi_123456789-cancel \
  -d "expand[]"=line_items

La transaction d’annulation intégrale ainsi créée est alors renvoyée :

{
  "id": "tax_1MEFtXI6rIcR421e0KTGXvCK",
  "object": "tax.transaction",
  "created": 1670866467,
  "currency": "eur",
  "customer": null,
  "customer_details": {
    "address": {
      "city": null,
      "country": "IE",

L’annulation complète d’une transaction n’affecte pas les annulations partielles précédentes. Lorsque vous enregistrez une annulation complète, veillez à annuler intégralement toutes les annulations partielles précédentes pour la même transaction afin d’éviter les remboursements en double.

Remboursement partiel d’une vente

Après émission d’un remboursement à votre client, créez un opération fiscale d’annulation avec mode=partial. Cela vous permet d’enregistrer un remboursement partiel en fournissant les montants des postes remboursés. Vous pouvez créer jusqu’à 30 annulations partielles pour chaque vente. Si vous annulez plus que la quantité de taxes que vous avez collectée, une erreur est renvoyée.

Dans l’exemple ci-dessous, seul le premier poste de la transaction d’origine est remboursé :

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl https://api.stripe.com/v1/tax/transactions/create_reversal \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d mode=partial \
  -d original_transaction=tax_1MEFAAI6rIcR421eB1YOzACZ \
  -d reference=pi_123456789-refund_1 \
  -d "line_items[0][original_line_item]"=tax_li_MyBXPByrSUwm6r \
  -d "line_items[0][reference]"=L1 \
  -d "line_items[0][amount]"=-4999 \
  -d "line_items[0][amount_tax]"=-1150 \
  -d "metadata[refund]"=
"{{REFUND_ID}}"
 \
  --data-urlencode "metadata[refund_reason]"="Refunded line 1 of pi_123456789 (customer was unhappy)" \
  -d "expand[0]"=line_items

La transaction d’annulation partielle ainsi créée est alors renvoyée :

{
  "id": "tax_1MEFACI6rIcR421eHrjXCSmD",
  "object": "tax.transaction",
  "created": 1670863656,
  "currency": "eur",
  ...
  "line_items": {
    "object": "list",
    "data": [
      {

Pour chaque poste annulé, vous devez fournir l’amount et amount_tax annulés. L’amount inclut la taxe si le poste initial du calcul incluait la taxe.

La façon dont les attributs amount et amount_tax sont déterminés dépend de votre situation :

  • Si vos transactions comportent toujours un seul poste, utilisez les annulations complètes à la place.
  • Si vous remboursez toujours les postes dans leur intégralité, utilisez les valeurs amount et amount_tax du poste d’origine, mais avec des signes négatifs.
  • Si vous remboursez une partie de la valeur des postes, vous devez calculer les montants remboursés. Par exemple, pour une transaction de vente avec amount=5000 et amount_tax=500, après avoir remboursé la moitié de la valeur du poste, vous créez une annulation partielle avec la valeur de poste amount=-2500 et amount_tax=-250.

Rapports fiscaux avec remboursements partiels

Si vous remboursez un montant de taxe de manière à ce que le total des taxes ne soit plus proportionnel au sous-total, votre déclaration fiscale peut devenir inexacte. Le système n’ajustera pas automatiquement les montants imposables et non imposables, et ne reflétera pas la raison de l’annulation de la taxe (comme une exonération produit, une exonération client ou une autoliquidation). Nous vous recommandons de ne pas rembourser partiellement les taxes par ligne d’article. Annulez plutôt la transaction et créez-en une nouvelle avec les entrées appropriées pour un calcul fiscal précis.

Remboursement partiel d’une vente par montant fixe

Vous pouvez également créer une annulation avec le paramètre mode=partial en spécifiant le montant fixe après impôt que vous souhaitez rembourser. Ce montant est alors réparti entre les différents postes et frais de livraison de manière proportionnelle, en fonction du montant restant à rembourser pour chacun d’entre eux.

Dans l’exemple ci-dessous, la transaction comporte deux postes de facture : un poste de 10 USD et un poste de 20 USD, tous deux taxés à 10 %. Le montant total de la transaction est de 33,00 USD. On reçoit un remboursement d’un montant fixe de 16,50 USD :

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl https://api.stripe.com/v1/tax/transactions/create_reversal \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d mode=partial \
  -d original_transaction=tax_1NVcKqBUZ691iUZ4xMZtcGYt \
  -d reference=pi_234567890-refund_1 \
  -d flat_amount=-1650 \
  -d "metadata[refund]"=
"{{REFUND_ID}}"
 \
  --data-urlencode "metadata[refund_reason]"="Refunded $16.50 of pi_234567890 (customer was unhappy)" \
  -d "expand[]"=line_items

La transaction d’annulation partielle ainsi créée est alors renvoyée :

{
  "id": "tax_1NVcQYBUZ691iUZ4SBPukGa6",
  "object": "tax.transaction",
  "created": 1689780994,
  "currency": "usd",
  ...
  "line_items": {
    "object": "list",
    "data": [
      {

Les montants remboursés et taxes correspondant à chaque poste de facture et frais de livraison de la transaction initiale sont calculés comme suit :

  1. Tout d’abord, nous calculons le montant total remboursable sur la transaction. Puisque celle-ci n’avait fait l’objet d’aucun remboursement précédent, le montant total pouvant être remboursé est de 33,00 USD.
  2. Ensuite, nous calculons le montant à rembourser pour chaque poste de facture, en fonction de la proportion que représente le montant remboursable de ce poste par rapport au montant total remboursable sur la transaction. Par exemple, le poste de 10 USD présente un montant remboursable de 11 USD, ce qui représente 33,33 % du montant total remboursable sur la transaction. Le montant à rembourser pour ce poste est donc de -16.50 USD * 33.33% = -5.50 USD.
  3. Enfin, pour chaque poste, le montant total à rembourser est réparti entre les attributs amount et amount_tax. Cette opération s’effectue également au prorata du montant de taxe remboursable sur un poste par rapport au montant total remboursable. Si on reprend l’exemple du poste de 10 USD, la taxe (1,00 USD) représentant 9,09 % du total remboursable (11 USD), la valeur associée à l’attribut amount_tax est donc de -5.50 USD * 9.09% = -0.50 USD.

Le montant forfaitaire est réparti en fonction du montant left to refund dans la transaction, et non du montant initialement enregistré. Par exemple, au lieu d’enregistrer un remboursement d’un montant forfaitaire de 16,50 USD, vous enregistrez d’abord une annulation partielle du montant total du poste de 10 USD :

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl https://api.stripe.com/v1/tax/transactions/create_reversal \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d mode=partial \
  -d original_transaction=tax_1NVcKqBUZ691iUZ4xMZtcGYt \
  -d reference=pi_234567890-refund_1 \
  -d "line_items[0][original_line_item]"=tax_li_OICmRXkFuWr8Df \
  -d "line_items[0][reference]"=partial_refund_l1 \
  -d "line_items[0][amount]"=-1000 \
  -d "line_items[0][amount_tax]"=-100 \
  -d "metadata[refund]"=
"{{REFUND_ID}}"
 \
  --data-urlencode "metadata[refund_reason]"="Refunded line 1 of pi_234567890 (customer was unhappy)" \
  -d "expand[0]"=line_items

Ensuite, vous enregistrez une annulation d’un montant fixe de 16,50 USD :

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl https://api.stripe.com/v1/tax/transactions/create_reversal \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d mode=partial \
  -d original_transaction=tax_1NVcKqBUZ691iUZ4xMZtcGYt \
  -d reference=pi_234567890-refund_2 \
  -d flat_amount=-1650 \
  -d "metadata[refund]"=
"{{REFUND_ID}}"
 \
  --data-urlencode "metadata[refund_reason]"="Refunded $16.50 of pi_234567890 (customer was still unhappy)" \
  -d "expand[]"=line_items

La transaction d’annulation partielle suivante est alors renvoyée :

{
  "id": "tax_1NVxFIBUZ691iUZ4saOIloxB",
  "object": "tax.transaction",
  "created": 1689861020,
  "currency": "usd",
  ...
  "line_items": {
    "object": "list",
    "data": [
      {

Étant donné que le montant total restant à rembourser sur la transaction est désormais de 22,00 USD et que le poste de 10 USD est intégralement remboursé, les 16,50 USD sont entièrement imputés au poste de 20 USD, puis répartis, selon la logique de l’étape 3, entre attribut amount = -15,00 USD et attribut amount_tax = -1,50 USD. Pendant ce temps, le poste de 10 USD de la transaction enregistre un remboursement de 0 USD.

Annuler un remboursement partiel

Les transactions fiscales sont immuables, mais vous pouvez annuler un remboursement partiel en créant une annulation intégrale.

Vous pouvez être amené à le faire dans les cas suivants :

  • Le remboursement du paiement échoue et vous n’avez pas fourni le bien ou le service à votre client
  • La mauvaise commande ou les mauvais montants sont remboursés
  • La vente initiale est intégralement remboursée et les remboursements partiels ne sont plus valides

Dans l’exemple ci-dessous, tax_1MEFACI6rIcR421eHrjXCSmD est la transaction qui représente le remboursement partiel :

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl https://api.stripe.com/v1/tax/transactions/create_reversal \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d mode=full \
  -d original_transaction=tax_1MEFACI6rIcR421eHrjXCSmD \
  -d reference=pi_123456789-refund_1-cancel \
  -d "metadata[refund_reason]"="User called to cancel because they selected the wrong item" \
  -d "expand[]"=line_items

La transaction d’annulation intégrale ainsi créée est alors renvoyée :

{
  "id": "tax_1MEFADI6rIcR421e94fNTOCK",
  "object": "tax.transaction",
  "created": 1670863657,
  "currency": "eur",
  ...
  "line_items": {
    "object": "list",
    "data": [
      {

Test

Utilisez les environnements de test dont la structure de réponse est identique à celle du mode production, pour vérifier que votre intégration fonctionne correctement avant de la mise en production.

Avertissement

Dans les environnements de test, les calculs ne garantissent pas des résultats de taxation à jour. Vous êtes limité à 1 000 calculs de taxes par jour. Si vous avez besoin d’une limite plus élevée, contactez le service d’assistance Stripe. Pour obtenir des conseils sur les tests automatisés et les stratégies permettant d’éviter les limites d’appels dans les environnements de test, consultez la section Tests automatisés.

Afficher les transactions fiscales

Vous pouvez afficher toutes les transactions comportant des taxes de votre compte sur la page Transactions avec taxe du Dashboard. Cliquez sur une transaction donnée pour afficher le détail des taxes calculées par territoire fiscal et par produit inclus dans la transaction.

Remarque

La page Transactions fiscales n’inclut que les transactions et non les calculations. Si vous vous attendez à voir un calcul et que vous ne le trouvez pas sur cette page, vérifiez que vous avez bien créé une transaction fiscale à partir du calcul.

FacultatifExemples d'intégration

Vous pouvez calculer la taxe pour votre client avant de collecter les informations relatives au moyen de paiement et de créer une PaymentIntent. Par exemple, vous pouvez afficher le total du panier lorsque le client indique son code postal.

Dans l’exemple ci-dessous, votre serveur définit un endpoint /preview-cart sur lequel est envoyée l’adresse du client depuis votre formulaire côté client. Le serveur calcule la taxe en fonction des postes de factures inclus dans le panier et de l’adresse du client.

server.js
Node.js
Java
Ruby
PHP
Python
Accédez à
.NET
No results
// Set your secret key. Remember to switch to your live secret key in production.
// See your keys here: https://dashboard.stripe.com/apikeys
const stripe = require('stripe')(
'sk_test_BQokikJOvBiI2HlWgH4olfQ2'
);
const express = require('express');
const app = express();

// Parse the request body as JSON.
app.use(express.json());

app.post('/preview-cart', async (req, res) => {

Lorsque vous pouvez accepter le paiement, créez une PaymentIntent à partir du résultat du calcul des taxes. Sauvegardez l’identifiant du calcul des taxes dans les métadonnées de PaymentIntent ou dans votre propre base de données, afin de pouvoir créer une transaction fiscale lorsque votre client aura effectué le paiement.

L’exemple ci-dessous montre un endpoint serveur qui calcule la taxe, crée (ou met à jour) un PaymentIntent et renvoie le résultat au client. Vous pouvez ensuite afficher la taxe à votre client. Utilisez le client_secret pour accepter le paiement.

server.js
Node.js
Java
Ruby
PHP
Python
Accédez à
.NET
No results
// Set your secret key. Remember to switch to your live secret key in production.
// See your keys here: https://dashboard.stripe.com/apikeys
const stripe = require('stripe')(
'sk_test_BQokikJOvBiI2HlWgH4olfQ2'
);
const express = require('express');
const app = express();

// Parse the request body as JSON.
app.use(express.json());

app.post('/calculate-cart', async (req, res) => {

Si votre intégration utilise l’Element Payment, récupérez les mises à jour du serveur après la mise à jour de PaymentIntent.

FacultatifCalculer les taxes sur les frais de livraison
Côté serveur

Pour calculer les taxes sur les frais de livraison, utilisez le paramètre shipping_cost :

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl https://api.stripe.com/v1/tax/calculations \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d currency=usd \
  -d "line_items[0][amount]"=1000 \
  -d "line_items[0][reference]"=L1 \
  -d "customer_details[address][line1]"="920 5th Ave" \
  -d "customer_details[address][city]"=Seattle \
  -d "customer_details[address][state]"=WA \
  -d "customer_details[address][postal_code]"=98104 \
  -d "customer_details[address][country]"=US \
  -d "customer_details[address_source]"=shipping \
  -d "shipping_cost[amount]"=500 \
  -d "shipping_cost[tax_code]"=txcd_92010001

Transmettez l’identifiant d’un ShippingRate existant pour utiliser son amount, son tax_code et son tax_behavior :

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl https://api.stripe.com/v1/tax/calculations \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d currency=usd \
  -d "line_items[0][amount]"=1000 \
  -d "line_items[0][reference]"=L1 \
  -d "customer_details[address][line1]"="920 5th Ave" \
  -d "customer_details[address][city]"=Seattle \
  -d "customer_details[address][state]"=WA \
  -d "customer_details[address][postal_code]"=98104 \
  -d "customer_details[address][country]"=US \
  -d "customer_details[address_source]"=shipping \
  -d "shipping_cost[shipping_rate]"=shr_1Mlh8YI6rIcR421eUr9SJzAD

FacultatifEstimer le montant des taxes à partir d'une adresse IP
Côté serveur

Si vous fournissez l’adresse IP à votre client, nous la géolocalisons et utilisons cet emplacement comme celui de votre client. Utilisez cette fonctionnalité pour afficher une estimation de taxe à votre client avant qu’il ne fournisse son adresse postale.

Mise en garde

Étant donné que l’emplacement d’une adresse IP peut être loin de l’emplacement actuel du client, nous vous déconseillons d’utiliser une adresse IP pour déterminer le montant final de la taxe à percevoir.

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl https://api.stripe.com/v1/tax/calculations \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d currency=usd \
  -d "line_items[0][amount]"=1000 \
  -d "line_items[0][reference]"=L1 \
  -d "customer_details[ip_address]"="127.0.0.1"

FacultatifCollecter les numéros fiscaux des clients
Côté serveur

Dans certains cas, comme la fourniture de services transfrontaliers, votre client peut être tenu de déclarer la TVA selon le mécanisme d’autoliquidation de la TVA. Au lieu de collecter la TVA, vous devez émettre une facture comportant la mention « Autoliquidation de la TVA par le client ». Cela informe votre client qu’il est responsable du paiement de la TVA sur son achat.

Fournissez les numéros fiscaux de votre client pour déterminer automatiquement si l’autoliquidation de la TVA s’applique :

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl https://api.stripe.com/v1/tax/calculations \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d currency=usd \
  -d "line_items[0][amount]"=1000 \
  -d "line_items[0][reference]"=L1 \
  -d "customer_details[address][country]"=IE \
  -d "customer_details[address_source]"=billing \
  -d "customer_details[tax_ids][0][type]"=eu_vat \
  -d "customer_details[tax_ids][0][value]"=DE123456789

Si vous fournissez un numéro fiscal au format invalide, le calcul renvoie le code d’erreur tax_id_invalid :

{
  "error": {
    "code": "tax_id_invalid",
    "doc_url": "https://docs.stripe.com/error-codes#tax-id-invalid",
    "message": "Invalid value for eu_vat.",
    "param": "customer_details[tax_ids][0][value]",
    "type": "invalid_request_error"
  }
}

L’API Tax ne valide pas automatiquement les numéros fiscaux auprès des bases de données gouvernementales. Pour valider un numéro fiscal avant de calculer la TVA, vous devez utiliser la validation du numéro fiscal du client.

FacultatifTarification TTC
Côté serveur

Par défaut, la taxe est calculée en plus du montant du poste et des frais de livraison que vous indiquez. Pour calculer la taxe incluse dans vos prix, définissez le paramètre tax_behavior sur inclusive pour le poste ou les frais de livraison.

Dans l’exemple ci-dessous, le client paie toujours 100 EUR :

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl https://api.stripe.com/v1/tax/calculations \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d currency=eur \
  -d "line_items[0][amount]"=10000 \
  -d "line_items[0][reference]"=L1 \
  -d "line_items[0][tax_behavior]"=inclusive \
  -d "line_items[0][tax_code]"=txcd_10103000 \
  -d "customer_details[address][country]"=IE \
  -d "customer_details[address_source]"=billing

La réponse renvoie le montant toutes taxes comprises :

{
  ...
  "amount_total": 10000,
  ...
  "tax_amount_exclusive": 0,
  "tax_amount_inclusive": 1870,
  "tax_breakdown": [
    {
      "amount": 1870,
      "inclusive": true,
      "tax_rate_details": {
        "country": "IE",
        "percentage_decimal": "23.0",
        "state": null,
        "tax_type": "vat"
      },
      "taxability_reason": "standard_rated",
      "taxable_amount": 8130
    }
  ],
  ...
}

FacultatifUtiliser un objet Product existant
Côté serveur

Vous pouvez fournir un objet Produit pour chaque poste. Si le produit possède un tax_code, nous l’utilisons comme tax_code du poste, s’il n’est pas déjà renseigné. Nous n’utilisons pas les autres valeurs du produit, notamment le tax_behavior et le price, lors du calcul des taxes.

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl https://api.stripe.com/v1/tax/calculations \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d currency=usd \
  -d "line_items[0][amount]"=1000 \
  -d "line_items[0][reference]"=L1 \
  -d "line_items[0][product]"=
"{{PRODUCT_ID}}"
 \
  -d "customer_details[address][country]"=IE \
  -d "customer_details[address_source]"=billing

FacultatifUtiliser un objet Customer existant
Côté serveur

Si vous fournissez un objet Client, nous copions et utilisons automatiquement l’adresse et les numéros fiscaux du client pour le calcul :

  • Si l’adresse shipping du client est présente, elle est copiée dans customer_details.address.
  • Sinon, si l’address du client est présente, elle est copiée dans customer_details.address.
  • Sinon, si l’adresse IP du client (tax.ip_address) est présente, elle est copiée dans customer_details.ip_address.
  • Sinon, si le champ tax.tax_exempt du client est présent, il est copié dans customer_details.taxability_override.

Les numéros fiscaux du client sont copiés danscustomer_details.tax_ids.

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl https://api.stripe.com/v1/tax/calculations \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d currency=usd \
  -d "line_items[0][amount]"=1000 \
  -d "line_items[0][reference]"=L1 \
  -d customer=
"{{CUSTOMER_ID}}"

FacultatifRemplacer l'assujettissement à la taxe du client
Côté serveur

Vous n’avez pas besoin de collecter de taxe dans certains cas, par exemple lorsque votre client est exonéré de taxe. Vous pouvez indiquer l’exonération de taxe à Stripe Tax à l’aide du paramètre taxability_override.

Pour fournir le remplacement d’assujettissement à la taxe du client dans vos calculs :

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl https://api.stripe.com/v1/tax/calculations \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d currency=usd \
  -d "line_items[0][amount]"=1000 \
  -d "line_items[0][reference]"=L1 \
  -d "customer_details[address][line1]"="920 5th Ave" \
  -d "customer_details[address][city]"=Seattle \
  -d "customer_details[address][state]"=WA \
  -d "customer_details[address][postal_code]"=98104 \
  -d "customer_details[address][country]"=US \
  -d "customer_details[address_source]"=billing \
  -d "customer_details[taxability_override]"=customer_exempt

Autoliquidation de la TVA

Certaines régions, comme l’Union européenne, appliquent un mécanisme d’« autoliquidation de la TVA » où le client est responsable de la déclaration de la TVA s’il achète en tant qu’entreprise. Pour que Stripe Tax applique le régime fiscal approprié, nous vous recommandons de collecter les numéros fiscaux de vos clients. Il se peut que vous ne disposiez pas des numéros fiscaux de votre client, ou que vous ayez déterminé séparément que le mécanisme d’autoliquidation de la TVA s’applique. Dans de tels scénarios, vous pouvez utiliser taxability_override pour forcer Stripe Tax à appliquer le mécanisme d’autoliquidation de la TVA.

Pour fournir le remplacement d’assujettissement à la taxe du client dans vos calculs :

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl https://api.stripe.com/v1/tax/calculations \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d currency=eur \
  -d "line_items[0][amount]"=1000 \
  -d "line_items[0][reference]"=L1 \
  -d "customer_details[address][country]"=IE \
  -d "customer_details[address_source]"=billing \
  -d "customer_details[taxability_override]"=reverse_charge

FacultatifSpécifier un lieu d'expédition
Côté serveur

Si vous expédiez des marchandises à partir d’une autre adresse que l’adresse principale de votre entreprise, vous pouvez fournir cette adresse pour le calcul des taxes.

Pour indiquer l’adresse de l’expéditeur, utilisez le paramètre ship_from_details. Dans cet exemple, l’utilisateur est établi en Floride, son client est établi à Springfield (Illinois), et l’utilisateur expédie les marchandises depuis Naperville (Illinois) :

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl https://api.stripe.com/v1/tax/calculations \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d currency=usd \
  -d "line_items[0][amount]"=1000 \
  -d "line_items[0][reference]"=L1 \
  -d "line_items[0][tax_behavior]"=exclusive \
  -d "line_items[0][tax_code]"=txcd_99999999 \
  -d "customer_details[address][city]"=Springfield \
  -d "customer_details[address][state]"=IL \
  -d "customer_details[address][postal_code]"=62704 \
  -d "customer_details[address][country]"=US \
  -d "customer_details[address_source]"=billing \
  -d "ship_from_details[address][city]"=Naperville \
  -d "ship_from_details[address][state]"=IL \
  -d "ship_from_details[address][postal_code]"=60540 \
  -d "ship_from_details[address][country]"=US

La réponse renvoie la taxe calculée en fonction de l’adresse d’expédition de la commande (Naperville, IL) au lieu de l’adresse de destination (Springfield, IL) ou de l’adresse de l’entreprise du commerçant :

{
  ...
  "amount_total": 1078,
  ...
  "tax_amount_exclusive": 78,
  ...
  "tax_breakdown": [
    {
      "amount": 78,
      "inclusive": true,
      "tax_rate_details": {
        "country": "US",
        "percentage_decimal": "7.75",
        "state": "IL",
        "tax_type": "sales_tax"
      },
      "taxability_reason": "standard_rated",
      "taxable_amount": 1000
    }
  ],
  ...
}

Pour en savoir plus sur la façon dont nous calculons les taxes dans ces scénarios, consultez la section Documentation fiscale Stripe.

FacultatifCalculer les frais de livraison d’articles au détail
Côté serveur

Stripe Tax prend en charge le calcul des frais de livraison d’articles au détail au Minnesota et au Colorado.

Après avoir ajouté une immatriculation fiscale de type state_retail_delivery_fee dans les États pris en charge, les frais de livraison au détail sont déterminés lors du calcul des taxes.

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl https://api.stripe.com/v1/tax/registrations \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d country=US \
  -d "country_options[us][state]"=CO \
  -d "country_options[us][type]"=state_retail_delivery_fee \
  -d active_from=now

Pour calculer les frais de livraison au détail, appelez l’API de calcul des taxes en utilisant un code de taxe sur les produits physiques, tel que txcd_30011000, qui représente les Vêtements et les Chaussures.

Tous les articles physiques ne déclenchent pas le calcul des frais de livraison au détail. Consultez la documentation de l’État concerné pour savoir quand la taxe s’applique :

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl https://api.stripe.com/v1/tax/calculations \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d currency=usd \
  -d "line_items[0][amount]"=1000 \
  -d "line_items[0][reference]"=L1 \
  -d "line_items[0][tax_behavior]"=exclusive \
  -d "line_items[0][tax_code]"=txcd_30011000 \
  -d "shipping_cost[amount]"=400 \
  -d "customer_details[address][line1]"="1437 Bannock St Room 451" \
  -d "customer_details[address][city]"=Springfield \
  -d "customer_details[address][state]"=CO \
  -d "customer_details[address][postal_code]"=80202 \
  -d "customer_details[address][country]"=US \
  -d "customer_details[address_source]"=shipping

La réponse renvoie la taxe calculée, incluant les frais de livraison au détail pour le Colorado. Il s’agit d’une entrée supplémentaire dans l’objet tax_breakdown, avec tax_breakdown.tax_rate_details.rate_type défini sur flat_amount :

{
  ...
  "amount_total": 2165,
  ...
  "tax_amount_exclusive": 165,
  ...
  "tax_breakdown": [
    {
      "amount": 88,
      "inclusive": false,
      "tax_rate_details": {
        "percentage_decimal": "8.81",
        "rate_type": "percentage",
        "tax_type": "sales_tax",
        ...
      },
      "taxability_reason": "standard_rated",
      "taxable_amount": 1000
    },
    ...
    {
      "amount": 29,
      "inclusive": false,
      "tax_rate_details": {
        "flat_amount": {
          "amount": 29,
          "currency": "usd"
        },
        "percentage_decimal": "0.0",
        "rate_type": "flat_amount",
        "tax_type": "retail_delivery_fee",
        ...
      },
      "taxability_reason": "standard_rated",
      "taxable_amount": 1000
    }
  ],
  ...
}

FacultatifRépartition détaillée des taxes pour les postes de facture
Côté serveur

Le champ tax_breakdown de niveau supérieur est toujours renvoyé et fournit une ventilation simple, adaptée à l’affichage d’une liste de taxes lors du paiement ou sur un reçu.

Vous pouvez utiliser le champ taxability_reason pour comprendre pourquoi la taxe n’est pas appliquée lors de la création de votre intégration. Par exemple, not_collecting indique que la taxe n’est pas collectée dans le pays ou l’État où elle serait due. L’ajout d’informations sur les immatriculations fiscales dans les paramètres de votre compte indique à Stripe où vous collectez la taxe. Si vous avez ajouté une immatriculation fiscale pour l’État de Washington, le motif d’assujettissement à la taxe affiché dans votre résultat est standard_rated, ce qui indique que le produit est taxé au taux standard.

Développez l’attribut tax_breakdown du poste pour obtenir une ventilation détaillée, incluant les taxes locales et les attributs expliquant la raison de chaque taxe.

  • Le champ tax_type detax_rate_details est une indication de type fiscal de haut niveau qui peut ne pas toujours correspondre au type renvoyé dans les rapports et les exportations de transactions. Par exemple, elle ne fait pas la distinction entre la taxe de vente américaine et la taxe d’utilisation américaine.
  • Utilisez le champ display_name de tax_rate_details dans votre tunnel de paiement pour afficher toutes les taxes. Les taxes sont localisées en fonction de l’emplacement du client et des informations fiscales du produit. Par exemple, si la TVA est appliquée pour l’Allemagne car le client se trouve en Allemagne et que le produit est taxé à destination, comme txcd_10103001 : Software as a service (SaaS) à usage professionnel, nous affichons Umsatzsteuer (USt), qui est la désignation allemande de la TVA. Si la TVA est appliquée pour la France car l’adresse du siège social est définie sur la France et que le produit est taxé à l’origine, comme txcd_20030000 : Général - Services, nous affichons Taxe sur la valeur ajoutée (TVA), qui est la désignation française de la TVA.
Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl https://api.stripe.com/v1/tax/calculations \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d currency=usd \
  -d "line_items[0][amount]"=1000 \
  -d "line_items[0][reference]"=L1 \
  -d "customer_details[address][line1]"="920 5th Ave" \
  -d "customer_details[address][city]"=Seattle \
  -d "customer_details[address][state]"=WA \
  -d "customer_details[address][postal_code]"=98104 \
  -d "customer_details[address][country]"=US \
  -d "customer_details[address_source]"=shipping \
  -d "expand[0]"="line_items.data.tax_breakdown"
{
  ...
  "tax_breakdown": [
    {
      "amount": 103,
      "inclusive": false,
      "tax_rate_details": {
        "country": "US",
        "percentage_decimal": "10.25",
        "state": "WA",
        "tax_type": "sales_tax"
      },
      "taxability_reason": "standard_rated",
      "taxable_amount": 1000
    }
  ],

FacultatifRésolution des erreurs courantes
Côté serveur

Suivez les étapes ci-dessous pour résoudre les erreurs dans votre intégration fiscale.

Résolution des erreurs liées aux codes fiscaux non valides

Si l’erreur Code fiscal invalide est renvoyée, consultez la liste des Codes fiscaux des produits disponibles. Suivez ensuite ces étapes pour résoudre le problème :

  1. Vérifier le code fiscal : assurez-vous d’utiliser un code fiscal valide parmi la liste des codes fiscaux disponibles. Les erreurs courantes comprennent ce qui suit :

    • Utilisation d’une chaîne vide ou de la valeur null comme code fiscal
    • Faute d’orthographe dans le code fiscal
    • Utilisation d’un code fiscal inexistant

  2. Mettez à jour votre code : assurez-vous de passer un code fiscal valide lors de la création d’un TaxCalculation. Par exemple :

    Command Line
    cURL
    Stripe CLI
    Ruby
    Python
    PHP
    Java
    Node.js
    Go
    .NET
    No results
    curl https://api.stripe.com/v1/tax/calculations \
  -u "
    sk_test_BQokikJOvBiI2HlWgH4olfQ2
    :"     \
  -d currency=usd \
  -d "line_items[0][amount]"=1000 \
  -d "line_items[0][reference]"=L1 \
  -d "line_items[0][tax_code]"=txcd_10000000 \
  -d "customer_details[address][line1]"="354 Oyster Point Blvd" \
  -d "customer_details[address][city]"="South San Francisco" \
  -d "customer_details[address][state]"=CA \
  -d "customer_details[address][postal_code]"=94080 \
  -d "customer_details[address][country]"=US \
  -d "customer_details[address_source]"=shipping

  3. Utiliser le code fiscal par défaut : Stripe Tax utilise un code fiscal par défaut pour les calculs lorsqu’aucun code fiscal spécifique n’est fourni pour un produit ou dans une demande de calcul de taxe. Vous pouvez consulter et modifier la valeur par défaut dans vos paramètres fiscaux.

    Utilisez l’API pour mettre à jour le code fiscal par défaut :

    Command Line
    cURL
    Stripe CLI
    Ruby
    Python
    PHP
    Java
    Node.js
    Go
    .NET
    No results
    curl https://api.stripe.com/v1/tax/settings \
  -u "
    sk_test_BQokikJOvBiI2HlWgH4olfQ2
    :"     \
  -d "defaults[tax_code]"=txcd_10000000

  4. Vérifier votre catalogue de produits : si vous utilisez des codes fiscaux associés aux produits de votre catalogue Stripe, assurez-vous que ces codes sont correctement attribués à vos produits.

  5. Vérifiez les incohérences de données : assurez-vous que le code fiscal est correctement transmis de votre base de données ou de votre interface utilisateur à votre code côté serveur qui effectue l’appel à l’API vers Stripe.

Pour obtenir des calculs fiscaux plus précis, utilisez le code fiscal le plus spécifique qui s’applique à votre produit ou service. Si vous ne savez pas quel code fiscal utiliser, consultez la documentation sur les codes fiscaux.

Si vous continuez à rencontrer des problèmes, vérifiez la documentation de l’API des paramètres fiscaux.

Voir aussi