Accéder directement au contenu
Créez un compte ou connecter-vous
Logo de la documentation Stripe
/
Créez un compteConnectez-vous
AperçuAccepter un paiementMettre votre intégration à niveau
Paiements en ligne
PrésentationTrouver votre cas d'usageUtiliser Managed PaymentsPaiements récurrents
Paiements par TPE
Moyens de paiement
Opérations de paiement
Soldes et délai de règlementReçusRemboursements et annulations
Intégrations avancées
Au-delà des paiements

Collecter des taxes

Découvrez comment utiliser Stripe Tax pour calculer et collecter les taxes dans votre intégration personnalisée avec Elements.

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.

Si votre tunnel de paiement personnalisé utilise l’API Payment Intents, consultez Calculer les taxes dans vos tunnels de paiement personnalisés. Cette intégration propose un suivi automatique des responsabilités fiscales, des reçus ainsi qu’une prise en charge dans le Dashboard. Nous proposons également une fonctionnalité en aperçu public qui vous permet d’utiliser le composant Tax ID Element afin de collecter les numéros fiscaux des clients. Pour en savoir plus, consultez Collecter les numéros fiscaux des clients ci-dessous.

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

This video walks through a Stripe Tax API integration that uses the Payment Intents API and the Payment Element.

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 un 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 paramètre 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 le composant Payment Element, récupérez les mises à jour du serveur après la mise à jour du 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.

Collecter les numéros fiscaux des clients

Il est courant d’exiger que le numéro fiscal et le nom de l’entreprise d’un client figurent sur les factures. Vous pouvez utiliser le composant Element d’identification fiscale pour collecter ces informations. Cette fonctionnalité est disponible en version bêta publique.

Avis de non-responsabilité

L’API Payment Intents est conçue pour collecter les numéros fiscaux des entreprises, qui peuvent avoir des formats similaires à ceux des identifiants fiscaux personnels dans certaines juridictions. Vous devez vous assurer que seuls les identifiants fiscaux des entreprises, tels que désignés pour ce champ, sont fournis lorsque vous utilisez cette fonctionnalité.

Activer la version bêta

Le composant Element d’identification fiscale avec l’API Payment Intents vous oblige à activer la version bêta du paramètre elements_tax_id_1. Ajoutez la version bêta à votre initialisation Stripe.js :

const stripe = Stripe(
'pk_test_TYooMQauvdEDq54NiTphI7jx'
, {
  betas: ['elements_tax_id_1'],
});

Créer une CustomerSession (facultatif)

Si vous souhaitez enregistrer les numéros fiscaux dans un Client et les afficher à nouveau pour les clients fidèles, vous devez créer une CustomerSession. La CustomerSession fournit un accès temporaire et sécurisé aux données client sans exposer votre clé API secrète au client.

Si vous n’utilisez pas CustomerSession, le composant Element d’identification fiscale fonctionne toujours mais sans les fonctionnalités de sauvegarde et d’affichage. Vous pouvez utiliser getValue pour lire les valeurs d’identification fiscale à partir de l’élément et les traiter manuellement.

Tout d’abord, créez ou récupérez un client :

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl https://api.stripe.com/v1/customers \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  --data-urlencode email="customer@example.com" \
  -d name="Jenny Rosen"

Créez une CustomerSession avec le composant Element d’identification fiscale activé :

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl https://api.stripe.com/v1/customer_sessions \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d customer=
"{{CUSTOMER_ID}}"
 \
  -d "components[tax_id_element][enabled]"=true \
  -d "components[tax_id_element][features][tax_id_redisplay]"=enabled \
  -d "components[tax_id_element][features][tax_id_save]"=enabled

La CustomerSession renvoie une clé client_secret que vous transmettrez côté client.

Créer un PaymentIntent ou un SetupIntent

Créez une PaymentIntent ou une SetupIntent sur votre serveur. Lorsque vous utilisez une CustomerSession, incluez le customer pour activer la fonctionnalité d’enregistrement et d’affichage du numéro fiscal :

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl https://api.stripe.com/v1/payment_intents \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d amount=1099 \
  -d currency=usd \
  -d customer=
"{{CUSTOMER_ID}}"

Remarque

Vous n’avez pas besoin d’inclure de paramètres spécifiques à l’identifiant fiscal lors de la création de PaymentIntent ou SetupIntent. Le composant Element d’identification fiscale gère automatiquement la collecte du numéro fiscal et l’enregistre dans le dossier du client lorsqu’une CustomerSession disposant des autorisations appropriées est présente.

Initialiser Elements

Créez une instance Elements en utilisant la clientSecret de votre PaymentIntent ou SetupIntent.

Pour permettre l’enregistrement des numéros fiscaux d’un client et leur réaffichage pour les clients fidèles, incluez la clé customerSessionClientSecret :

const stripe = Stripe(
'pk_test_TYooMQauvdEDq54NiTphI7jx'
, {
  betas: ['elements_tax_id_1'],
});

// Fetch the clientSecret from your server
const {clientSecret} = await fetch('/create-payment-intent', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
}).then((res) => res.json());

// Fetch the customerSessionClientSecret from your server
const {customerSessionClientSecret} = await fetch('/create-customer-session', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
}).then((res) => res.json());

const elements = stripe.elements({
  clientSecret,
  customerSessionClientSecret,
  appearance: { /* ... */ }
});

Créez et montez le composant Element d’identification fiscale

Créez une instance du composant Element d’identification fiscale et intégrez-la à votre page :

<form id="payment-form">
  <div id="tax-id-element">
    <!--Stripe.js injects the Tax ID Element-->
  </div>
  <button type="submit">Pay</button>
</form>
const taxIdElement = elements.create('taxId', {
  visibility: 'auto', // 'auto' | 'always' | 'never'
});
taxIdElement.mount('#tax-id-element');

Vous pouvez personnaliser le composant Element d’identification fiscale avec des options telles que la visibility, les fields, et la validation. Pour en savoir plus, consulter la documentation relative à la création de composants Element d’identification fiscale.

Utilisation avec le composant Element d’adresse (facultatif)

Lorsque vous utilisez le composant Element d’identification fiscale avec le composant Element d’adresse, Stripe détermine automatiquement le type du numéro fiscal et la visibilité des éléments en fonction de l’adresse du client.

Finaliser le paiement

Lorsque le client soumet le formulaire de paiement, appelez le paramètre confirmPayment ou confirmSetup. Stripe inclut automatiquement les informations relatives au numéro fiscal et les sauvegarde pour le client, si le paiement réussit :

const form = document.getElementById('payment-form');

form.addEventListener('submit', async (event) => {
  event.preventDefault();

  const {error} = await stripe.confirmPayment({
    elements,
    confirmParams: {
      return_url: 'https://example.com/order/complete',
    },
  });

  if (error) {
    // Handle error
    console.error(error.message);
  }
  // Customer gets redirected to return_url if successful
});

Vous pouvez aussi utiliser getValue du côté client pour lire les valeurs de numéro fiscal avant de soumettre le paiement.

Tester votre intégration

Dans les environnements de test, vous pouvez saisir n’importe quelle chaîne de caractères alphanumériques correspondant au format d’un type de numéro fiscal pris en charge (par exemple, DE123456789 pour eu_vat). Vous trouverez une liste complète d’exemples de numéros fiscaux dans notre guide sur les numéros fiscaux des clients. Vous pouvez également utiliser nos numéros fiscaux de test pour tester différents flux d’état de vérification.

Validation du numéro fiscal

Lors de la confirmation du paiement ou de la configuration, Stripe vérifie que les numéros fiscaux fournis sont correctement formatés, mais pas qu’ils sont valides. C’est à vous qu’il incombe de garantir la validité des informations clients. Pour vous aider, Stripe effectue automatiquement une validation asynchrone sur les bases de données gouvernementales pour la Taxe européenne sur la valeur ajoutée (TVA UE) et la Taxe sur la valeur ajoutée du Royaume-Uni (GB TVA). En savoir plus sur les validations que nous effectuons, et l’utilisation du statut de ces vérifications.

Types de numéros fiscaux pris en charge

Le composant Element d’identification fiscale prend en charge la collecte des numéros fiscaux dans les pays et régions suivants :

PaysEnumDescriptionExemple
Impact sur le calcul des taxes
Afrique du Sudza_vatSouth African VAT number4123456789Oui
Albanieal_tinAlbania Tax Identification NumberJ12345678NOui
Allemagneeu_vatEuropean VAT numberDE123456789Oui
Angolaao_tinAngola Tax Identification Number5123456789Non
Arabie saouditesa_vatSaudi Arabia VAT123456789012345Oui
Arménieam_tinArmenia Tax Identification Number02538904Oui
Arubaaw_tinAruba Tax Identification Number12345678Oui
Australieau_abnAustralian Business Number (AU ABN)12345678912Oui
Autricheeu_vatEuropean VAT numberATU12345678Oui
Azerbaïdjanaz_tinAzerbaijan Tax Identification Number0123456789Oui
Bahamasbs_tinBahamas Tax Identification Number123.456.789Non
Bahreïnbh_vatBahraini VAT Number123456789012345Oui
Bangladeshbd_binBangladesh Business Identification Number123456789-0123Oui
Barbadebb_tinBarbados Tax Identification Number1123456789012Non
Belgiqueeu_vatEuropean VAT numberBE0123456789Oui
Béninbj_ifuBenin Tax Identification Number (Identifiant Fiscal Unique)1234567890123Oui
Biélorussieby_tinBelarus TIN Number123456789Oui
Bosnie-Herzégovineba_tinBosnia and Herzegovina Tax Identification Number123456789012Oui
Bulgarieeu_vatEuropean VAT numberBG0123456789Oui
Burkina Fasobf_ifuBurkina Faso Tax Identification Number (Numéro d'Identifiant Fiscal Unique)12345678AOui
Cambodgekh_tinCambodia Tax Identification Number1001-123456789Oui
Camerouncm_niuCameroon Tax Identification Number (Numéro d'Identifiant fiscal Unique)M123456789000LNon
Canadaca_bnCanadian BN123456789Non
Canadaca_gst_hstCanadian GST/HST number123456789RT0002Oui
Canadaca_pst_bcCanadian PST number (British Columbia)PST-1234-5678Non
Canadaca_pst_mbCanadian PST number (Manitoba)123456-7Non
Canadaca_pst_skCanadian PST number (Saskatchewan)1234567Non
Canadaca_qstCanadian QST number (Québec)1234567890TQ1234Oui
Cap-Vertcv_nifCape Verde Tax Identification Number (Número de Identificação Fiscal)213456789Non
Chilicl_tinChilean TIN12.345.678-KOui
Chypreeu_vatEuropean VAT numberCY12345678ZOui
Congo-Kinshasacd_nifCongo (DR) Tax Identification Number (Número de Identificação Fiscal)A0123456MNon
Corée du Sudkr_brnKorean BRN123-45-67890Oui
Costa Ricacr_tinCosta Rican tax ID1-234-567890Non
Croatieeu_vatEuropean VAT numberHR12345678912Oui
Danemarkeu_vatEuropean VAT numberDK12345678Oui
Égypteeg_tinEgyptian Tax Identification Number123456789Oui
Émirats arabes unisae_trnUnited Arab Emirates TRN123456789012345Oui
Équateurec_rucEcuadorian RUC number1234567890001Non
Espagnees_cifSpanish NIF number (previously Spanish CIF number)A12345678Non
Espagneeu_vatEuropean VAT numberESA1234567ZOui
Estonieeu_vatEuropean VAT numberEE123456789Oui
Éthiopieet_tinEthiopia Tax Identification Number1234567890Oui
Finlandeeu_vatEuropean VAT numberFI12345678Oui
Franceeu_vatEuropean VAT numberFRAB123456789Oui
Géorgiege_vatGeorgian VAT123456789Oui
Grèceeu_vatEuropean VAT numberEL123456789Oui
Guinéegn_nifGuinea Tax Identification Number (Número de Identificação Fiscal)123456789Oui
Hongrieeu_vatEuropean VAT numberHU12345678Oui
Indein_gstIndian GST number12ABCDE3456FGZHOui
Irlandeeu_vatEuropean VAT numberIE1234567ABOui
Islandeis_vatIcelandic VAT123456Oui
Italieeu_vatEuropean VAT numberIT12345678912Oui
Kazakhstankz_binKazakhstani Business Identification Number123456789012Oui
Kenyake_pinKenya Revenue Authority Personal Identification NumberP000111111ANon
Kirghizistankg_tinKyrgyzstan Tax Identification Number12345678901234Non
Laosla_tinLaos Tax Identification Number123456789-000Non
Lettonieeu_vatEuropean VAT numberLV12345678912Oui
Liechtensteinli_vatLiechtensteinian VAT number12345Oui
Lituanieeu_vatEuropean VAT numberLT123456789123Oui
Luxembourgeu_vatEuropean VAT numberLU12345678Oui
Macédoine du Nordmk_vatNorth Macedonia VAT NumberMK1234567890123Oui
Malteeu_vatEuropean VAT numberMT12345678Oui
Marocma_vatMorocco VAT Number12345678Oui
Mauritaniemr_nifMauritania Tax Identification Number (Número de Identificação Fiscal)12345678Non
Mexiquemx_rfcMexican RFC numberABC010203AB9Non
Moldaviemd_vatMoldova VAT Number1234567Oui
Monténégrome_pibMontenegro PIB Number12345678Non
Népalnp_panNepal PAN Number123456789Oui
Nigériang_tinNigerian Tax Identification Number12345678-0001Non
Norvègeno_vatNorwegian VAT number123456789MVAOui
Nouvelle-Zélandenz_gstNew Zealand GST number123456789Oui
Omanom_vatOmani VAT NumberOM1234567890Oui
Ougandaug_tinUganda Tax Identification Number1014751879Oui
Ouzbékistanuz_tinUzbekistan TIN Number123456789Non
Ouzbékistanuz_vatUzbekistan VAT Number123456789012Oui
Pays-Baseu_vatEuropean VAT numberNL123456789B12Oui
Péroupe_rucPeruvian RUC number12345678901Oui
Philippinesph_tinPhilippines Tax Identification Number123456789012Oui
Pologneeu_vatEuropean VAT numberPL1234567890Oui
Polognepl_nipPolish NIP number1234567890Non
Portugaleu_vatEuropean VAT numberPT123456789Oui
République tchèqueeu_vatEuropean VAT numberCZ1234567890Oui
Roumanieeu_vatEuropean VAT numberRO1234567891Oui
Royaume-Unieu_vatNorthern Ireland VAT numberXI123456789Oui
Royaume-Unigb_vatUnited Kingdom VAT numberGB123456789Oui
Russieru_innRussian INN1234567891Oui
Russieru_kppRussian KPP123456789Oui
Sénégalsn_nineaSenegal NINEA Number12345672A2Non
Serbiers_pibSerbian PIB number123456789Non
Singapoursg_gstSingaporean GSTM12345678XOui
Slovaquieeu_vatEuropean VAT numberSK1234567891Oui
Slovénieeu_vatEuropean VAT numberSI12345678Oui
Suèdeeu_vatEuropean VAT numberSE123456789123Oui
Suissech_vatSwitzerland VAT numberCHE-123.456.789 MWSTOui
Surinamesr_finSuriname FIN Number1234567890Oui
Tadjikistantj_tinTajikistan Tax Identification Number123456789Oui
Taïwantw_vatTaiwanese VAT12345678Oui
Tanzanietz_vatTanzania VAT Number12345678AOui
Thaïlandeth_vatThai VAT1234567891234Oui
Turquietr_tinTurkish Tax Identification Number0123456789Oui
Ukraineua_vatUkrainian VAT123456789Oui
Uruguayuy_rucUruguayan RUC number123456789012Oui
Zambiezm_tinZambia Tax Identification Number1004751879Non
Zimbabwezw_tinZimbabwe Tax Identification Number1234567890Non

Utiliser les identifiants fiscaux dans les calculs (facultatif)

Dans certains cas, comme la prestation transfrontalière de services, votre client peut être tenu de déclarer la taxe selon le principe de l’autoliquidation. Au lieu de percevoir la taxe, vous devez émettre une facture portant la mention « Taxe à payer selon le principe de l’autoliquidation ».

Lorsque vous fournissez les numéros fiscaux de vos clients à Stripe Tax, nous déterminons automatiquement quand l’autoliquidation 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 non valide, le calcul renvoie le code d’erreur tax_id_invalid :

Voir aussi