# API Tax autonome Utilisez directement les API Tax Calculations et Transactions pour les frais de livraison, la tarification TTC, et bien plus encore. L’API Tax autonome vous permet de calculer les impôts, d’enregistrer des transactions et de gérer les remboursements directement. Utilisez-la avec des [PaymentIntents](https://docs.stripe.com/tax/payment-intent.md) ou lors du traitement de paiements [hors Stripe](https://docs.stripe.com/tax/off-stripe.md). Les fonctionnalités suivantes sont disponibles avec les API Tax Calculations et Transactions. ## Optional: Calculer 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` : ```curl curl https://api.stripe.com/v1/tax/calculations \ -u "<>:" \ -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](https://docs.stripe.com/api/shipping_rates/object.md) existant pour utiliser son `amount`, son `tax_code` et son `tax_behavior` : ```curl curl https://api.stripe.com/v1/tax/calculations \ -u "<>:" \ -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" ``` ## Optional: Estimer le montant des taxes à partir d'une adresse IP [Côté serveur] Si vous fournissez l’[adresse IP](https://docs.stripe.com/api/tax/calculations/create.md#calculate_tax-customer_details-ip_address) à 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. > É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. ```curl curl https://api.stripe.com/v1/tax/calculations \ -u "<>:" \ -d currency=usd \ -d "line_items[0][amount]=1000" \ -d "line_items[0][reference]=L1" \ -d "customer_details[ip_address]=127.0.0.1" ``` ## Optional: Collecte des 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](https://docs.stripe.com/tax/zero-tax.md#reverse-charges). 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](https://docs.stripe.com/api/tax/calculations/create.md#calculate_tax-customer_details-tax_ids) de votre client pour déterminer automatiquement si l’autoliquidation de la TVA s’applique : ```curl curl https://api.stripe.com/v1/tax/calculations \ -u "<>:" \ -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` : ```json { "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](https://docs.stripe.com/billing/customer/tax-ids.md#validation). ## Optional: Tarification 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](https://docs.stripe.com/api/tax/calculations/create.md#calculate_tax-line_items-tax_behavior) ou les [frais de livraison](https://docs.stripe.com/api/tax/calculations/create.md#calculate_tax-shipping_cost-tax_behavior). Dans l’exemple ci-dessous, le client paie toujours 100 EUR : ```curl curl https://api.stripe.com/v1/tax/calculations \ -u "<>:" \ -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 : ```json { ... "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 } ], ... } ``` ## Optional: Utiliser un objet Product existant [Côté serveur] Vous pouvez fournir un objet [Produit](https://docs.stripe.com/api/products/object.md) pour chaque poste. Si le produit possède un [tax_code](https://docs.stripe.com/api/products/object.md#product_object-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. ```curl curl https://api.stripe.com/v1/tax/calculations \ -u "<>:" \ -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" ``` ## Optional: Utiliser un Account ou un Customer existant [Côté serveur] Le calcul de la taxe utilise automatiquement l’adresse et les identifiants fiscaux du [Customer](https://docs.stripe.com/api/customers/object.md) pertinents, en fonction de la disponibilité des données du client : - L’adresse de livraison du client renseigne le champ `customer_details.address` du calcul. - Sinon, l’adresse du client renseigne le champ `customer_details.address` du calcul. - L’adresse IP du client renseigne le champ `customer_details.ip_address` du calcul. - Si le client bénéficie d’une exonération fiscale, cela renseigne le champ `customer_details.taxability_override` du calcul. - Les identifiants fiscaux du client renseignent le champ `customer_details.tax_ids` du calcul. ```curl curl https://api.stripe.com/v1/tax/calculations \ -u "<>:" \ -d currency=usd \ -d "line_items[0][amount]=1000" \ -d "line_items[0][reference]=L1" \ -d "customer={{CUSTOMER_ID}}" ``` ## Optional: Rectification de 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](https://docs.stripe.com/api/tax/calculations/create.md#calculate_tax-customer_details-taxability_override). Pour fournir le remplacement d’assujettissement à la taxe du client dans vos calculs : ```curl curl https://api.stripe.com/v1/tax/calculations \ -u "<>:" \ -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](https://docs.stripe.com/tax/standalone-tax-api.md#tax-ids) 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 : ```curl curl https://api.stripe.com/v1/tax/calculations \ -u "<>:" \ -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" ``` ## Optional: Spécification d’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) : ```curl curl https://api.stripe.com/v1/tax/calculations \ -u "<>:" \ -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 : ```json { ... "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](https://docs.stripe.com/tax/calculating.md). ## Optional: Calculer 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. ```curl curl https://api.stripe.com/v1/tax/registrations \ -u "<>:" \ -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](https://docs.stripe.com/tax/tax-codes.md?type=physical), 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 : - [Frais de livraison au détail - Colorado](https://docs.stripe.com/tax/supported-countries/united-states/collect-tax.md?tax-jurisdiction-united-states=colorado#other-taxes) - [Frais de livraison au commerce en ligne - Minnesota](https://docs.stripe.com/tax/supported-countries/united-states/collect-tax.md?tax-jurisdiction-united-states=minnesota#other-taxes) ```curl curl https://api.stripe.com/v1/tax/calculations \ -u "<>:" \ -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` : ```json { ... "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 } ], ... } ``` ## Optional: Répartition détaillée des taxes pour les postes de facture [Côté serveur] Le champ [tax_breakdown](https://docs.stripe.com/api/tax/calculations/object.md#tax_calculation_object-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](https://docs.stripe.com/api/tax/calculations/object.md#tax_calculation_object-line_items-data-tax_breakdown-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](https://docs.stripe.com/tax/set-up.md#add-registrations) 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](https://docs.stripe.com/api/tax/calculations/object.md#tax_calculation_object-line_items-data-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` de[tax_rate_details](https://docs.stripe.com/api/tax/calculations/object.md#tax_calculation_object-line_items-data-tax_breakdown-tax_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](https://docs.stripe.com/api/tax/calculations/object.md#tax_calculation_object-line_items-data-tax_breakdown-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](https://docs.stripe.com/tax/tax-codes.md?tax_code=txcd_10103001), 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](https://docs.stripe.com/tax/tax-codes.md?tax_code=txcd_20030000), nous affichons `Taxe sur la valeur ajoutée (TVA)`, qui est la désignation française de la TVA. ```curl curl https://api.stripe.com/v1/tax/calculations \ -u "<>:" \ -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" ``` ```json { ... "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 } ], "line_items": { "object": "list", "data": [ { "id": "tax_li_O84jA8hvV7ZyAa", "object": "tax.calculation_line_item", "amount": 1000, "amount_tax": 103, "product": null, "quantity": 1, "reference": "L1", "tax_behavior": "exclusive", "tax_breakdown": [ { "amount": 65, "jurisdiction": { "country": "US", "display_name": "Washington", "level": "state", "state": "WA" }, "sourcing": "destination", "tax_rate_details": { "display_name": "Retail Sales and Use Tax", "percentage_decimal": "6.5", "tax_type": "sales_tax" },"taxability_reason": "standard_rated", "taxable_amount": 1000 }, { "amount": 0, "jurisdiction": { "country": "US", "display_name": "KING", "level": "county", "state": "WA" }, "sourcing": "destination", "tax_rate_details": null,"taxability_reason": "not_subject_to_tax", "taxable_amount": 0 }, { "amount": 22, "jurisdiction": { "country": "US", "display_name": "SEATTLE", "level": "city", "state": "WA" }, "sourcing": "destination", "tax_rate_details": { "display_name": "Local Sales and Use Tax", "percentage_decimal": "2.2", "tax_type": "sales_tax" },"taxability_reason": "standard_rated", "taxable_amount": 1000 }, { "amount": 14, "jurisdiction": { "country": "US", "display_name": "REGIONAL TRANSIT AUTHORITY", "level": "district", "state": "WA" }, "sourcing": "destination", "tax_rate_details": { "display_name": "Local Sales and Use Tax", "percentage_decimal": "1.4", "tax_type": "sales_tax" },"taxability_reason": "standard_rated", "taxable_amount": 1000 }, { "amount": 2, "jurisdiction": { "country": "US", "display_name": "SEATTLE TRANSPORTATION BENEFIT DISTRICT", "level": "district", "state": "WA" }, "sourcing": "destination", "tax_rate_details": { "display_name": "Local Sales and Use Tax", "percentage_decimal": "0.15", "tax_type": "sales_tax" },"taxability_reason": "standard_rated", "taxable_amount": 1000 } ], "tax_code": "txcd_10000000" } ], "has_more": false, "total_count": 1, "url": "/v1/tax/calculations/taxcalc_1NLoZvBUZ691iUZ4z4cTW6tQ/line_items" }, ... } ``` ## Optional: Ré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](https://docs.stripe.com/tax/tax-codes.md) 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](https://docs.stripe.com/tax/tax-codes.md). 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 1. **Mettez à jour votre code** : assurez-vous de passer un code fiscal valide lors de la création d’un `TaxCalculation`. Par exemple : ```curl curl https://api.stripe.com/v1/tax/calculations \ -u "<>:" \ -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" ``` 1. **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 : ```curl curl https://api.stripe.com/v1/tax/settings \ -u "<>:" \ -d "defaults[tax_code]=txcd_10000000" ``` 1. **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. 1. **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](https://docs.stripe.com/tax/tax-codes.md). Si vous continuez à rencontrer des problèmes, vérifiez la [documentation de l’API des paramètres fiscaux](https://docs.stripe.com/api/tax/settings.md). ## See also - [Stripe Tax avec les PaymentIntents](https://docs.stripe.com/tax/payment-intent.md) - [Paiements externes à Stripe](https://docs.stripe.com/tax/off-stripe.md) - [API Tax Calculation](https://docs.stripe.com/api/tax/calculations/create.md) - [Rapports et déclarations](https://docs.stripe.com/tax/reports.md)