Configuration fiscale

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

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.

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 386 XAF et la taxe de 1 614 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é.

Le réglage s'applique aux enregistrements écrits sur vos paiements. POST /tax/calculate ne le lit pas : envoyez tax_inclusive: true dans la requête pour un calcul TTC, sinon le calcul est hors taxe.

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é. Le KWD, le BHD, l'OMR, le JOD et le TND sont arrondis à trois décimales. 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.

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.

Le pays du calcul est celui dont provient le taux : le country envoyé à POST /tax/calculate ou, sur un paiement enregistré, le pays du payeur résolu à l'ouverture de la page de paiement. Le pays propre du client n'est pas lu. Une entreprise étrangère qui vous paie depuis votre propre pays est taxée comme n'importe qui d'autre dans ce pays.

Aucun autre élément n'est examiné. La zone économique ne constitue notamment pas une condition. Un marchand camerounais payé par une entreprise vérifiée depuis le Sénégal, l'Allemagne ou le Japon obtient la même autoliquidation. Un paiement venu du Cameroun ne l'obtient pas.

Un identifiant fiscal ne mène jamais qu'à l'autoliquidation. Il ne rend jamais un client exonéré : cet indicateur est distinct, et rien ne l'écrit (voir plus haut).

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.

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

curl https://api.wajub.com/customers/cus_sAaim5apjocIgtlhzJY3wQ8s/tax_ids \
  -H "Authorization: sk.xxxxxxxxxxxxxxxx…" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "cm.niu",
    "value": "M071512345678A",
    "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. Ces routes se trouvent sous /customers : une clé restreinte a besoin de customer.read et customer.write, pas des permissions fiscales.

Le numéro d'un client est vérifié selon la même liste de formats que votre propre numéro d'immatriculation.

Un numéro est accepté avec ou sans les espaces, tirets, points et barres obliques que son format comporte : 12-3456789 et 123456789 sont le même EIN. Ajouter de nouveau le même type et le même numéro ne crée pas de copie : l'appel répond 200 avec l'entrée existante, repassée à pending le temps d'une nouvelle vérification. Quatre statuts sont possibles.

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.

curl https://api.wajub.com/tax/calculate \
  -H "Authorization: sk.xxxxxxxxxxxxxxxx…" \
  -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é.

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.

Un paiement est enregistré au taux normal du pays, celui que renvoie POST /tax/calculate. Un paiement ne porte ni État ni ville : les taux infranationaux sont répertoriés mais pas appliqués.

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 : l'entrée est conservée comme revoked dans votre historique. Il existe une entrée par pays et par État : enregistrer de nouveau le même pays et le même État répond 422, entrée révoquée comprise. Réactivez-la avec PUT et status: "active".