Configuration fiscale

Les paramètres, les prix TTC, les exonérations, l'autoliquidation et les identifiants fiscaux des clients.

Cinq paramètres déterminent le comportement de Tax pour votre compte. Deux règles propres au client peuvent modifier le résultat d'un paiement donné. Cette page les présente dans l'ordre de lecture du moteur.

Vos paramètres

enabledbooleanfacultatifdéfaut : false

Indique si une ligne est enregistrée pour chaque paiement encaissé. Lorsque ce paramètre est désactivé, rien n'est écrit ni rétroactif. Les paiements encaissés pendant cette période restent définitivement absents du registre.

inclusivebooleanfacultatifdéfaut : false

Indique si les montants débités comprennent déjà la taxe. La valeur false signifie que la taxe est calculée en plus du montant.

default_countrystringfacultatif

Code à deux lettres. Utilisé lorsque le pays du payeur n'a pas pu être déterminé et comme pays de comparaison pour l'autoliquidation. La valeur par défaut est le pays de votre compte, puis CM.

tax_id_typestringobligatoire

Type d'immatriculation que vous possédez, par exemple cm.niu, ci.ifu, ke.pin ou eu.vat. Enregistré tel quel.

registration_numberstringobligatoire

Votre propre numéro. Enregistré tel quel et jamais présenté à vos payeurs par Wajub.

Une différence doit être connue pour automatiser cette configuration : vous écrivez registration_number, mais vous relisez tax_registration_number. Les quatre autres champs conservent leur nom dans les deux sens.

Votre propre immatriculation est enregistrée, mais pas utilisée

Aucun de ces deux champs ne modifie un calcul. Ils permettent à votre compte de porter l'identité utilisée pour vos déclarations. Le taux d'un paiement ne dépend jamais de votre identité, mais uniquement de l'emplacement du payeur.

Prix TTC ou hors taxe

L'interrupteur détermine lequel des deux nombres est déjà connu.

Hors taxe, le comportement par défaut. Votre montant constitue la base. tax = amount × rate et le client doit amount + tax. Sur 10 000 XAF à 19,25 %, la taxe est de 1 925 XAF et le total de 11 925 XAF.

TTC. Votre montant constitue le total. base = amount ÷ (1 + rate) et la taxe correspond au reste. Sur 10 000 XAF à 19,25 %, la base est de 8 385 XAF et la taxe de 1 615 XAF. Le client paie toujours 10 000 XAF.

Ce choix décrit vos prix, pas un paiement particulier. Choisissez celui qui correspond à la façon dont vous annoncez vos tarifs, puis conservez-le. Une modification change la signification de tous les futurs enregistrements, sans recalculer le passé.

Arrondis

La taxe est arrondie selon la précision propre à la devise, pas systématiquement à deux décimales. Le XAF, le XOF, le RWF, l'UGX, le KMF, le GNF, le BIF, le DJF, le JPY, le KRW et les autres devises sans décimales sont arrondis à l'unité. Toutes les autres utilisent deux décimales.

Un calcul en XAF ne contient donc jamais de centimes. Un même taux de 19,25 % sur un même montant produit une présentation différente en EUR.

Pays dont provient le taux

Pour un paiement enregistré, trois étapes s'appliquent dans cet ordre : le pays déterminé depuis l'adresse IP du payeur à l'ouverture de la page de paiement, votre default_country, puis CM.

Pour POST /tax/calculate, une seule étape s'applique : le country envoyé. Ce champ est obligatoire et aucune autre valeur ne le remplace.

La devise n'est jamais consultée. Un payeur situé en France qui vous paie en XAF est soumis à la TVA française de 20 %, car la taxe dépend du lieu de consommation du service.

Clients exonérés

Le calcul d'un client exonéré utilise un taux nul, contient customer_exempt: true et ne produit aucune taxe. Cette règle l'emporte sur toutes les autres, y compris l'autoliquidation.

Vous ne pouvez actuellement exonérer aucun client

L'indicateur est visible sur un client et lu par le moteur, mais aucun endpoint ni formulaire du Dashboard ne permet de l'écrire. En pratique, tous les clients sont à none. En attendant une modification, l'autoliquidation ci-dessous constitue l'exonération utilisable.

Autoliquidation

Lorsqu'elle s'applique, la taxe est nulle et la réponse contient reverse_charge: true. Votre client doit la payer dans son propre pays au lieu de vous la verser. Trois conditions doivent toutes être remplies.

Condition	Vérification
Le client est une entreprise	Son `type` est `business`, pas un particulier
Il possède un identifiant fiscal vérifié	Au moins un de ses identifiants fiscaux a atteint `verified`
Il se trouve dans un autre pays	Son pays diffère de votre `default_country`

Aucun autre élément n'est examiné. La zone économique ne constitue notamment pas une condition. Un marchand camerounais qui vend à une entreprise vérifiée au Sénégal, en Allemagne ou au Japon obtient la même autoliquidation. Une vente à une entreprise vérifiée au Cameroun ne l'obtient pas.

Les conditions sont lues pendant le calcul. Un identifiant fiscal encore en cours de vérification produit donc un résultat normalement taxé. Enregistrez d'abord l'identifiant, attendez sa vérification, puis effectuez le calcul.

Identifiants fiscaux des clients

Un identifiant fiscal appartient à un client et est enregistré une seule fois, séparément de tous les paiements.

POSThttps://api.wajub.com/customers/{customer_id}/tax_ids

Le type détermine la méthode de vérification. Utilisez donc sa valeur réelle plutôt qu'un terme générique.

Enregistrer le NIU d'un client

curl https://api.wajub.com/customers/cus_sAaim5apjocIgtlhzJY3wQ8s/tax_ids \
  -H "Authorization: sk.kZ3qP8mWvL2xR7tB5nY4hC6dF9jS1aG0eU3i…" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "cm.niu",
    "value": "M071512345A",
    "country_code": "CM"
  }'

L'appel renvoie immédiatement verification_status: "pending", puis la vérification s'exécute en arrière-plan. Aucun webhook ne lui est associé. Relisez l'identifiant fiscal lorsque vous avez besoin de connaître le résultat.

Type	Format vérifié
`cm.niu`	`M`, puis neuf chiffres et une lettre
`ci.ifu`	Sept chiffres, puis une lettre
`sn.ninea`	Sept chiffres, une lettre, un chiffre et une lettre
`ke.pin`	`P`, puis neuf chiffres et une lettre
`ng.tin`	Huit chiffres, un tiret et quatre chiffres
`gh.vat`	Entre dix et quinze lettres ou chiffres
`za_vat`	Dix chiffres
`gb.vat`	`GB`, puis neuf ou douze chiffres
`us.ein`	Deux chiffres, un tiret et sept chiffres
`au_abn`	Onze chiffres
`eu.vat`	Deux lettres, puis entre deux et treize lettres ou chiffres

Les espaces, tirets et points sont supprimés avant la vérification. Quatre statuts sont possibles.

Statut	Signification
`pending`	En file d'attente, pas encore vérifié
`verified`	La vérification a réussi. Seul ce statut permet l'autoliquidation
`failed`	Le format est incorrect ou le registre considère le numéro comme invalide
`unavailable`	Le registre était inaccessible. Réessayez en enregistrant de nouveau l'identifiant

Seule la TVA européenne est vérifiée dans un registre

Un numéro eu.vat est envoyé au service européen VIES. Celui-ci confirme son existence et renvoie le nom enregistré. Tous les autres types sont uniquement comparés à leur format attendu. Un numéro bien formé qui n'appartient à personne revient donc avec verified. Un type absent du tableau ci-dessus est seulement contrôlé selon sa longueur, entre cinq et vingt caractères.

Codes fiscaux des produits

Un code fiscal indique ce que vous vendez afin qu'une juridiction puisse appliquer un taux différent de son taux normal. Envoyez-en un pendant un calcul, ou placez tax_code dans les metadata d'un paiement pour que l'enregistrement le reprenne.

Calculer avec un code fiscal

curl https://api.wajub.com/tax/calculate \
  -H "Authorization: sk.kZ3qP8mWvL2xR7tB5nY4hC6dF9jS1aG0eU3i…" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 10000,
    "currency": "XAF",
    "country": "CM",
    "tax_code": "txcd_10103001"
  }'

Deux comportements doivent être connus avant d'utiliser un code. txcd_00000000 désigne les produits non taxables. Lorsqu'il existe dans le catalogue, il impose un taux nul dans tous les pays. Un code sans taux dans le catalogue utilise silencieusement le taux normal du pays. La réponse répète tout de même le code, ce qui donne l'impression qu'il a été appliqué.

Consultez le catalogue avant d'utiliser un code

GET /tax/codes est la seule référence indiquant les codes existants et les pays qui possèdent un taux pour chacun. GET /tax/codes/{code} présente les taux du code pays par pays. Un code absent ne produit aucune erreur, mais le taux normal. Consultez le catalogue au lieu de supposer qu'un code provenant d'un autre prestataire possède une correspondance.

Un code fiscal est également entièrement ignoré lorsque le client est exonéré ou lorsque l'autoliquidation s'applique. Ces règles sont traitées en premier.

Taux infranationaux

Certains pays appliquent les taxes au niveau d'un État, d'un comté ou d'une ville plutôt qu'au niveau national. GET /tax/jurisdictions répertorie les données conservées par Wajub. Elles peuvent être filtrées par pays, État et niveau. Chaque entrée contient son taux et indique s'il se cumule avec les précédents.

Lorsque plusieurs juridictions correspondent à l'emplacement d'un paiement, l'enregistrement contient leur somme et le détail. Si aucune ne correspond, le taux normal du pays s'applique. C'est le cas partout où Wajub ne possède aucune donnée infranationale.

Vos lieux d'immatriculation

/tax/registrations conserve la liste des juridictions où vous êtes immatriculé, avec un type parmi standard, simplified, ioss et oss, votre numéro et les dates de validité.

Cette liste facilite vos déclarations, mais ne constitue pas un interrupteur. Aucun calcul ni enregistrement ne la consulte. L'ajout d'une immatriculation ne modifie jamais un taux et sa suppression n'arrête aucun enregistrement. La suppression révoque l'entrée au lieu de l'effacer : son statut devient revoked et la ligne reste dans votre historique.

Pages associées