Quickstart

Turn tax on, compute it, charge it, and read the first report.

Five steps, and the third one is the one people skip. Wajub computes the tax and records it, but charging it is yours: the amount you create the payment for is the amount your customer pays.

Nothing here works in sandbox

Tax endpoints refuse a test key, and a sandbox payment writes no record. The first real number you see will come from a real payment, so start with a small one you make yourself.

1. Turn it on

Recording is off until you switch it on, and switching it on requires declaring your own tax registration. Both fields are mandatory the moment enabled is true, and neither has a default.

Enable tax recording

curl -X PUT https://api.wajub.com/tax/settings \
  -H "Authorization: sk.xxxxxxxxxxxxxxxx…" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "inclusive": true,
    "default_country": "CM",
    "tax_id_type": "cm.niu",
    "registration_number": "M071512345678A"
  }'

inclusive says whether the amount you create a payment for already contains the tax. It is true here because step 3 charges the total, tax included: when the payment is credited, Wajub takes the tax out of the amount charged. Leave it false only if you charge the price before tax and nothing on top: Wajub then computes the tax on top of the amount charged, so charging the total with false records a tax on the tax. The same switch is on Tax, Settings in the Dashboard. registration_number is checked against the format of tax_id_type: a Cameroonian NIU is a letter, twelve digits and a letter, and anything else answers 422.

2. Ask what is owed

The country is required. There is no inference from the phone number, the IP or the currency on this endpoint, and your default_country is not used as a fallback here.

Calculate

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

The answer carries the arithmetic in full, so you never have to redo it.

Response · 200 OK

{

"code": 200,

"status": "OK",

"calculation": {

"amount": 10000,

"tax_amount": 1925,

"taxable_amount": 10000,

"total": 11925,

"rate": 19.25,

"tax_name": "TVA",

"country_code": "CM",

"currency": "XAF",

"tax_inclusive": false,

"tax_code": null,

"customer_exempt": false,

"reverse_charge": false

}

total is what to charge. On an exclusive calculation it is amount + tax_amount; on an inclusive one it is the amount you sent, unchanged, and taxable_amount is what is left once the tax is extracted.

This calculation does not read your inclusive setting. It is exclusive unless you send tax_inclusive: true, and exclusive is what you want here: 10 000 XAF is your price before tax, and the question is what to add to it. The setting describes something else, the amount you charge in the next step.

3. Charge the total yourself

You do not send tax when you create a payment. Create it for the figure the calculation returned.

curl https://api.wajub.com/payments \
  -H "Authorization: sk.xxxxxxxxxxxxxxxx…" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 11925,
    "currency": "XAF",
    "email": "[email protected]"
  }'

What you charge and what inclusive says about it have to agree. At 19.25 %, for a price of 10 000 XAF before tax:

You create the payment for	`inclusive`	What is recorded
11 925, the total	`true`	1 925 of tax on a base of 10 000. This is what this quickstart does
10 000, the price before tax	`false`	1 925 of tax on a base of 10 000. You collected none of it and pay it out of the 10 000
11 925, the total	`false`	2 296 of tax on a base of 11 925: a tax on the tax
10 000, the price before tax	`true`	1 614 of tax on a base of 8 386: your price read as if it contained the tax

The first two rows are the two ways that work. The last two are the mistakes, and nothing stops them: the payment goes through either way, and only the record is wrong.

Skip this step and nothing breaks either. With the settings above, the payment goes through for 10 000 XAF and the record is the last row: 1 614 XAF of tax, taken out of what you collected.

4. The record writes itself

When the payment is credited, Wajub computes the tax on it again, from your settings and the payer's country, and writes one row. You do nothing, and there is nothing to call.

That second computation is not the one you asked for in step 2. It uses the payer's real country and the amount actually charged, which is why the two can differ if you charged a country you did not calculate for. One row per payment, written once: a repeat of the same payment never duplicates it.

5. Read what was recorded

The report aggregates the ledger over a period, by country and by currency.

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

Narrow it to the country and the month you are filing for. net_tax in the summary is collections minus reversals, which is the figure you file.

This month, Cameroon only

curl "https://api.wajub.com/tax/reports?period=month&country=CM" \
  -H "Authorization: sk.xxxxxxxxxxxxxxxx…"

The same numbers are on Tax in the Dashboard, with a CSV export. Reports has the full shape of both.

If you send invoices instead

An invoice does carry a tax line, per item, and it behaves differently depending on where the invoice was created.

Created from	What happens to the line's tax
The Dashboard	With Tax on and the line left on automatic, the country's standard rate is filled in for you
The API	You set `items[].tax_rate` yourself. Nothing is filled in

Either way the item's tax is computed from the rate on the item, and the invoice total is the sum of the lines. The country used for the automatic fill is the customer's country on the invoice, falling back to your default_country.