API Tax pour la taxe de vente, la TPS et la TVA

Stripe Tax calcule uniquement les taxes sur les territoires où vous disposez d’une immatriculation pour collecter les taxes et vous demande d’ajouter vos immatriculations dans le Dashboard.

C’est à vous de déterminer quand et à quelle fréquence calculer les taxes. Par exemple, vous pouvez :

• Afficher une estimation du montant des taxes basée sur l’adresse IP de votre client lorsqu’il débute le 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 pour chaque appel à l’API de calcul des taxes. Vous pouvez restreindre le nombre d’appels à l’API afin de maîtriser vos coûts.

Les exemples ci-dessous montrent comment calculer la taxe dans différents scénarios. Stripe Tax calcule uniquement les taxes dans les juridictions dans lesquelles vous êtes immatriculé(e) pour collecter les taxes et vous demande d’ajouter vos immatriculations dans le Dashboard.

curl https://api.stripe.com/v1/tax/calculations \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -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

Le résultat du calcul contient des montants que vous pouvez présenter à votre client et utiliser pour encaisser le paiement :

Gestion des erreurs d’emplacement du client

Le calcul renvoie le code d’erreur customer_tax_location_invalid si l’adresse de votre client n’est pas valide ou pas assez 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"
  }
}

Lorsque vous recevez cette erreur, invitez votre client à vérifier l’adresse qu’il a saisie et à corriger toute erreur de frappe.

La création d’une transaction fiscale enregistre les taxes que vous avez collectées auprès de votre client. Vous pourrez ensuite télécharger des exports et générer des rapports pour remplir plus facilement vos déclarations fiscales. Vous pouvez créer une transaction à partir d’un calcul jusqu’à l’horodatage expires_at, soit 90 jours après sa création. Toute tentative d’utilisation après ce délai entraîne une erreur.

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.

Lorsque votre client paie, utilisez l’ID de calcul pour enregistrer la taxe perçue. Il existe deux façons de procéder :

• 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 payment_intent.succeeded. Récupérez l’ID du calcul dans les metadata du PaymentIntent.

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

curl https://api.stripe.com/v1/tax/transactions/create_from_calculation \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -d calculation={{TAX_CALCULATION}} \
  -d reference=
{{PAYMENT_INTENT_ID}} \
  -d "expand[]"=line_items

Conservez l’ID de la transaction fiscale dans votre base de données ou dans les métadonnées du PaymentIntent afin de pouvoir enregistrer de futurs remboursements :

curl https://api.stripe.com/v1/payment_intents/
{{PAYMENT_INTENT_ID}} \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -d "metadata[tax_transaction]"={{TAX_TRANSACTION}}

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 reference unique. Les stratégies les plus courantes sont les suivantes :

• 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 du remboursement Stripe ou l’ID d’un remboursement de votre système. Par exemple, re_3MoslRBUZ691iUZ41bsYVkOg ou myRefund_456.

Choisissez l’approche qui vous convient le mieux en fonction de votre procédure de rapprochement des commandes client avec vos rapports de taxes.

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 fait référence à la transaction fiscale correspondant à la vente de votre client :

curl https://api.stripe.com/v1/tax/transactions/create_reversal \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -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 toutefois à annuler intégralement toutes les annulations partielles portant sur la même transaction afin d’éviter les remboursements en double.

Remboursement partiel d’une vente

Après avoir émis un remboursement à l’intention de votre client, créez une transaction fiscale d’annulation en précisant la valeur mode=partial. Cela vous permet d’enregistrer un remboursement partiel en fournissant les montants des postes de facture remboursés. Vous pouvez créer jusqu’à 30 annulations partielles par vente. Le fait d’annuler un montant supérieur aux taxes perçues renvoie un message d’erreur.

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

curl https://api.stripe.com/v1/tax/transactions/create_reversal \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -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 de facture annulé, vous devez fournir les valeurs amount et amount_tax annulées. La valeur amount est exprimée TTC si le poste de facture d’origine incluait les taxes.

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 plutôt les remboursements intégraux.
• 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 procédez au remboursement partiel de postes, vous devez calculer les montants remboursés. Par exemple, pour une vente dans laquelle amount=5000 et amount_tax=500, après avoir remboursé la moitié du poste, vous créerez une annulation partielle avec amount=-2500 et amount_tax=-250.

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 :

curl https://api.stripe.com/v1/tax/transactions/create_reversal \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -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 fixe est réparti en fonction de ce qui reste à rembourser pour la transaction, non de ce qui a été initialement enregistré. Prenons l’exemple suivant : au lieu d’enregistrer un remboursement pour un montant fixe de 16,50 USD, vous devez d’abord enregistrer une annulation partielle pour la totalité du poste de 10 USD :

curl https://api.stripe.com/v1/tax/transactions/create_reversal \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -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 :

curl https://api.stripe.com/v1/tax/transactions/create_reversal \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -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 un remboursement intégral.

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, la transaction tax_1MEFACI6rIcR421eHrjXCSmD représente le remboursement partiel :

curl https://api.stripe.com/v1/tax/transactions/create_reversal \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -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 picked 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": [
      {

La structure de réponse est identique en mode test et en mode production, ce qui vous permet de vérifier que votre intégration fonctionne avant de la mettre en production.