Taxes

Activez la collecte des taxes, calculez-les et gérez vos immatriculations.

Taxes utilise un tableau de taux et vos immatriculations pour calculer un montant sur chaque paiement. Après son activation, chaque transaction est automatiquement taxée et enregistrée. Un objet tax apparaît dans les réponses des paiements et des remboursements. Avant l'activation, ces endpoints permettent de consulter les taux et d'essayer des calculs sans rien valider.

Mode live uniquement, avec une clé privée

Chaque endpoint /tax exige une clé privée (sk.) ou une clé restreinte avec tax.read ou tax.write. Une clé de la sandbox est refusée avec 403 This feature is only available in live mode.

Paramètres

GEThttps://api.wajub.com/tax/settings

curl https://api.wajub.com/tax/settings \
-H "Authorization: $WAJUB_API_KEY"

La configuration est renvoyée dans tax :

Réponse · 200 OK

{

"code": 200,

"status": "OK",

"tax": {

"enabled": false,

"inclusive": false,

"default_country": "CM",

"tax_id_type": null,

"tax_registration_number": null

}

enabledbooleanfacultatif

Indique si la taxe est calculée et enregistrée sur chaque transaction.

inclusivebooleanfacultatif

true signifie que le montant envoyé contient déjà la taxe. Avec false, la taxe est ajoutée au montant.

default_countrystringfacultatif

Pays dont le taux s'applique lorsqu'une transaction n'en précise aucun.

tax_id_typestringfacultatif

Type de numéro d'immatriculation que vous possédez, comme un numéro de TVA.

tax_registration_numberstringfacultatif

Votre numéro d'immatriculation, imprimé sur les reçus et les factures.

L'activation des taxes utilise un appel PUT sur le même chemin. Avec enabled: true, tax_id_type et registration_number deviennent obligatoires dans la même requête. Le format du numéro est vérifié selon son type.

curl -X PUT https://api.wajub.com/tax/settings \
-H "Authorization: $WAJUB_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "enabled": true,
  "inclusive": true,
  "default_country": "CM",
  "tax_id_type": "vat",
  "registration_number": "M071812345678A"
}'

Le champ de la requête est `registration_number`

Vous écrivez registration_number et lisez tax_registration_number. Les deux noms désignent la même valeur. Seule la direction change.

Calculer avant de débiter

POST /tax/calculate calcule le coût avec les taxes sans créer de ressource. Utilisez-le pour afficher le total dans le checkout.

POSThttps://api.wajub.com/tax/calculate

amountnumberobligatoire

Montant dans l'unité principale, au moins égal à 0,01.

countrystringobligatoire

Code pays ISO 3166-1 alpha-2 dont le taux s'applique.

currencystringfacultatifdéfaut : XAF

Code ISO 4217.

tax_inclusivebooleanfacultatifdéfaut : false

Indique si amount contient déjà la taxe.

customer_idstringfacultatif

Uid d'un client. Ses exonérations et son statut d'autoliquidation sont alors appliqués.

tax_codestringfacultatif

Code fiscal d'un produit pour les biens taxés à un taux différent du taux normal. Ignoré lorsque le client est exonéré ou soumis à l'autoliquidation.

curl https://api.wajub.com/tax/calculate \
-H "Authorization: $WAJUB_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "amount": 25000,
  "currency": "XAF",
  "country": "CM",
  "customer_id": "cus_01JXXXXXXXXXXXXX"
}'

total est le montant à afficher au client et à transmettre dans amount lors de la création du paiement :

Réponse · 200 OK

{

"code": 200,

"status": "OK",

"calculation": {

"amount": 25000,

"tax_amount": 4812.5,

"taxable_amount": 25000,

"total": 29812.5,

"rate": 19.25,

"tax_name": "TVA",

"country_code": "CM",

"currency": "XAF",

"tax_inclusive": false,

"tax_code": null,

"customer_exempt": false,

"reverse_charge": false

}

L'exonération et l'autoliquidation sont des résultats, pas des erreurs

Lorsque customer_exempt ou reverse_charge vaut true, tax_amount vaut zéro et total est égal à amount. Ce calcul est correct pour un client qui possède un identifiant fiscal vérifié dans une juridiction soumise à l'autoliquidation. Il ne s'agit pas d'un échec de calcul.

Données de référence

Ces listes en lecture seule sont identiques pour tous les marchands. Aucune n'accepte de cursor. Les deux listes paginées utilisent per_page, avec 50 par défaut et 100 au maximum.

Endpoint	Champ renvoyé	Filtres	Pagination
`GET /tax/rates`	`rates`	`country`	Non
`GET /tax/codes`	`tax_codes`	`category`	Oui
`GET /tax/codes/{code}`	`tax_code`		Sans objet
`GET /tax/jurisdictions`	`jurisdictions`	`country`, `state`, `type`	Oui
`GET /tax/thresholds`	`thresholds`	`country`	Non

GET /tax/rates est la liste la plus courte, avec un taux normal par pays :

Réponse · 200 OK

{

"code": 200,

"status": "OK",

"rates": [

{

"country_code": "CM",

"name": "TVA",

"rate": 19.25,

"type": "standard"

{

"country_code": "CI",

"name": "TVA",

"rate": 18,

"type": "standard"

}

"total": 2

}

Le champ jurisdiction_type d'une juridiction vaut country, state, county, city ou district. is_compound indique si son taux s'ajoute à celui de sa juridiction parente au lieu de le remplacer.

GET /tax/codes/{code} renvoie un code et tous les taux nationaux associés dans rates. Un seul appel indique ainsi comment une catégorie de produits est taxée sur tous vos marchés.

Immatriculations

Les pays où vous êtes immatriculé pour collecter les taxes. Ces cinq endpoints suivent la structure habituelle et sont tous limités à votre équipe.

Méthode	Endpoint	Renvoie
`GET`	`/tax/registrations`	`registrations`
`POST`	`/tax/registrations`	`registration`, 201
`GET`	`/tax/registrations/{id}`	`registration`
`PUT`	`/tax/registrations/{id}`	`registration`
`DELETE`	`/tax/registrations/{id}`	confirmation

country_codestringobligatoire

Code ISO 3166-1 alpha-2.

state_codestringfacultatif

Pour les pays qui appliquent des taxes sous le niveau national.

typestringfacultatif

Une valeur parmi standard, simplified, ioss, oss.

registration_numberstringfacultatif

Votre numéro d'immatriculation dans cette juridiction.

registered_atdatefacultatif

Date d'entrée en vigueur de l'immatriculation.

expires_atdatefacultatif

Doit être postérieure à registered_at.

Une nouvelle immatriculation est créée avec status: "active".

Seuils et alertes

De nombreuses juridictions exigent une immatriculation uniquement après le dépassement d'un seuil de chiffre d'affaires. GET /tax/thresholds les répertorie. GET /tax/thresholds/alerts les compare à votre propre volume et renvoie les pays où vous approchez ou dépassez déjà le seuil.

curl https://api.wajub.com/tax/thresholds/alerts \
-H "Authorization: $WAJUB_API_KEY"

Identifiants fiscaux des clients

Les identifiants fiscaux d'un client se trouvent sous le client, pas sous /tax. Leur ajout place une vérification asynchrone dans une file. L'identifiant est donc renvoyé avec verification_status: "pending" et son statut évolue plus tard.

Méthode	Endpoint	Renvoie
`GET`	`/customers/{customer_id}/tax_ids`	`tax_ids`
`POST`	`/customers/{customer_id}/tax_ids`	`tax_id`, 201
`DELETE`	`/customers/{customer_id}/tax_ids/{id}`	confirmation

typestringobligatoire

Type d'identifiant, jusqu'à 64 caractères.

valuestringobligatoire

L'identifiant lui-même, jusqu'à 128 caractères.

country_codestringobligatoire

Code ISO 3166-1 alpha-2.

Les identifiants fiscaux modifient le calcul

Un identifiant fiscal vérifié permet à customer_exempt ou reverse_charge de renvoyer true depuis POST /tax/calculate. Ajoutez l'identifiant avant le calcul, pas après.

Rapports

GET /tax/reports agrège les taxes collectées sur une période. Il accepte period, avec une valeur parmi 7d, 30d, 90d, month, year ou custom. Pour custom, ajoutez start_date et end_date. Les filtres currency et country sont facultatifs. Le résultat est renvoyé dans report.

Pages associées

Paramètres

Calculer avant de débiter

Données de référence

Immatriculations

Seuils et alertes

Identifiants fiscaux des clients

Rapports

Que pensez-vous de ce contenu ?