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.
curl -X PUT https://api.wajub.com/tax/settings \
-H "Authorization: sk.kZ3qP8mWvL2xR7tB5nY4hC6dF9jS1aG0eU3i…" \
-H "Content-Type: application/json" \
-d '{
"enabled": true,
"inclusive": false,
"default_country": "CM",
"tax_id_type": "cm.niu",
"registration_number": "M071512345A"
}'inclusive says whether the prices you charge already contain tax. Leave it false and Wajub
treats the amount as the base to add tax on top of. The same switch is on Tax, Settings in the
Dashboard.
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.
curl https://api.wajub.com/tax/calculate \
-H "Authorization: sk.kZ3qP8mWvL2xR7tB5nY4hC6dF9jS1aG0eU3i…" \
-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.
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.
3. Charge the total yourself
There is no tax field on a payment. Create it for the figure the calculation returned.
curl https://api.wajub.com/payments \
-H "Authorization: sk.kZ3qP8mWvL2xR7tB5nY4hC6dF9jS1aG0eU3i…" \
-H "Content-Type: application/json" \
-d '{
"amount": 11925,
"currency": "XAF",
"email": "client@example.com"
}'Skip this step and nothing breaks: the payment goes through for 10 000 XAF and the record says 1 925 XAF of tax was owed on it. You will simply have collected 10 000 and owe tax out of it.
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.
https://api.wajub.com/tax/reportsNarrow 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.
curl "https://api.wajub.com/tax/reports?period=month&country=CM" \
-H "Authorization: sk.kZ3qP8mWvL2xR7tB5nY4hC6dF9jS1aG0eU3i…"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.