Tax residency

Tax residency records where a counterparty is tax resident, from when, and under which tax number. It is the answer to “which revenue authority does this holder belong to”, and three other things read it.

A counterparty can be tax resident in more than one country at once. So this is a list, not a single value. You work with it on the Tax residency panel of the counterparty screen.

What each record holds

The country is an ISO 3166-1 alpha-2 code, and only that. ZAF and South Africa are refused rather than stored as a fourth spelling of one country.

A blank tax number is normal, not an omission. A holder who is not resident where you operate often has no local tax number, and is still reported.

stateDiagram-v2
    [*] --> Live: Declare
    Live --> Live: Correct
    Live --> Ceased: Cease on a date
    Ceased --> Ceased: Correct

Declaring a residency

1. Open the counterparty and select the Tax residency panel.
2. Select Declare.
3. Choose the Country of tax residence.
4. Enter the Tax identification number, or leave it blank.
5. Enter Resident from and confirm.

Repeat for each country the holder is resident in. A holder resident in two countries has two Live records, and reads as resident in both.

Declaring, correcting and ceasing each take a second pair of eyes. What you declare decides which revenue authority the holder is reported to, so it does not take effect on your word alone. See countersign.

Seeing a declaration before it is approved

Your declaration waits for an approver. You can still see it.

At the top of the counterparty you get a Now / Staged toggle, with a count of what is waiting.

A country you declared this morning appears in Staged as a new row, and a residency you ceased shows its cessation date on the row already there. Nothing you see in Staged is reported anywhere, and none of it reaches the withholding rules, until the approver agrees.

A correction is the exception. It waits for an approver like the other two, but it does not appear in Staged — the panel keeps showing the record uncorrected until the correction is granted. Correcting a residency also revisits any withholding shortfall it caused, and that recalculation cannot be previewed.

When a residency is required

Requirement is per role, not per counterparty. Someone who only borrows is never asked for a tax residency. Someone who invests is.

Which roles demand one is configuration. Where a role demands it, the residency is asked for on the same form as the role — during onboarding, or when the role is granted later. There is no second screen to visit.

If the role is granted with no residency and none on file, the grant is refused, and the refusal names the holder. Nothing is part-saved.

This is separate from counterparty clearance. Clearance asks whether you have verified who someone is. Tax residency asks which revenue authority they answer to.

Ceasing a residency

People emigrate. Ceasing records that fact and stops there.

1. Select Cease on the record.
2. Enter Ceased on and confirm.

The account continues. No balance is frozen, no payment is stopped, and no other residency on the holder is touched. A holder who was resident in two countries is simply resident in one.

The holder is still resident on the cessation date itself. Interest paid the day after is non-resident interest, and everything downstream splits the period there.

A cessation date before the residency began is refused.

Correcting a record

Correct replaces the declared country, tax number, from-date and declaration reference. A ceased record stays correctable — a wrong tax number on a past period still misreports for that period. Re-entering the same values changes nothing and is not recorded as a correction.

Two kinds of correction move the holder’s tax position backwards: changing the country, and moving the from-date earlier. Either one can mean too little tax was withheld on interest already paid. Amounts already withheld are never restated behind your back. Instead a follow-up task is raised against the counterparty, so someone decides what to do about the shortfall. Correcting only the tax number raises nothing.

The declaration behind the record

A residency record is a self-certification. The holder states where they are tax resident, and you record what they told you.

The record can carry a reference to the signed declaration itself — the treaty declaration or self-certification the holder handed over. That reference is what unlocks a reduced treaty rate. Without it, a payment falls to the standard rate for the paying country, which is the safe direction.

The panel does not capture that reference yet. Until it does, treaty relief that depends on a held declaration is not reachable from this screen.

What depends on a declared residency

A missing residency never blocks a return and never stops money. It raises work. At end of day, every holder who needs a residency and has none gets a follow-up task, and re-running the sweep does not raise a second one. The same holders are listed as warnings on the return, which cannot be marked submitted while that list is non-empty. Close the gap, produce the period again, then submit.

That posture is deliberate. Failing the first return against the whole existing book, days before a statutory deadline, helps nobody.

Two standards sit behind those rows. The return and the certificate follow SARS IT3(b) third-party reporting, BRS version 4.0.0D-10. Withholding follows the OECD Model Tax Convention Article 11 shape: a statutory rate in the paying country, with a treaty rate substituted for a named residency country. Neither is claimed in full — file transport is manual, and the treaty rates your organisation seeds are its own to maintain.

Worked example

Alex holds a savings account with Woodgrove Bank, which pays interest from South Africa. Countries are ISO 3166-1 alpha-2 codes, and every date below is a calendar date.

1. A clerk declares Alex resident in ZA from 1 March 2026, tax number 0123456789. The record is Live.
2. Alex is also resident in the United Kingdom. The clerk declares GB from the same date. Alex now has two Live records.
3. On 1 August 2026 Alex’s countries of residence are ZA and GB. Interest paid that day withholds nothing, because Alex is resident where Woodgrove Bank pays.
4. Alex emigrates. The clerk ceases the ZA record on 31 August 2026.
5. On 31 August Alex is still resident in ZA. On 1 September the only country of residence is GB, and interest paid then is non-resident interest.
6. The account carries on throughout. Nothing froze and no payment stopped.

What your organisation configures

• Whether tax residency runs at all. It is a licensed capability. A tenant without it has no panel, no gap sweep and no requirement. See switching features on and off.
• Which roles require a declared residency, per counterparty type. One row per type and role. A holder with none of those roles is never asked.
• Which counterparty screens show the panel. The panel is listed per counterparty type, so a type that never invests need not carry it.
• Whether declaring, ceasing and correcting need a second approver, and which group approves them.
• The withholding rules that read the declaration. Which country you pay from, which residency countries get a treaty rate, which declaration unlocks it, and which payer classes are exempt. No rate lives in code.
• Which returns and certificates the declaration feeds, and the periods they cover.

All of it is settings, so onboarding under a different tax regime is configuration rather than a release.