Revenue interface
Payment notification
The request that asks Revenue how much to withhold, and the Deduction Authorisation that comes back. This is where the money is decided.
On this page
Request shape
The same SubmitRctRequest element as a contract notification, carrying rct:PaymentNotification children instead. Up to 100 per submission, and a rejection fails the whole batch.
One notification per payment. A subcontractor invoicing monthly against one contract generates one contract notification and many of these.
How to read these
- required
- The schema demands it. Omitting it fails validation.
- required in practice
- The schema says it is optional and Revenue rejects the request without it. Learned the hard way, against PIT3.
- optional
- Genuinely optional. Send it when you have it.
- never send
- The schema permits sending it and you must not. These are response-only fields, and populating one asserts something you have no authority to assert.
Request fields
The parties
rct:PrincipalpartyrequiredYour registration number and type, same structure as on a contract. Leading zero dropped.
rct:SubcontractorpartyrequiredWho is being paid.
What is being notified
rct:NotificationUpdateTypeNEW | AMEND | CANCELrequiredNEW for a payment you are about to make. AMEND or CANCEL to correct or withdraw one, quoting its PaymentNotificationId.
The wider enumeration also contains UNSUSPEND, CARRY_FORWARD and MITIGATION, which apply to situations Brickie does not handle.
rct:ContractIdstringrequiredRevenue’s contract identifier, from the contract acknowledgement.
This is what ties the payment to a specific engagement and site. A subcontractor working two of your jobs has two contracts, and the wrong id here files the payment against the wrong site.
rct:GrossPaydecimal, 2 placesrequiredThe amount you intend to pay, before any deduction. Revenue calculates everything from this figure.
Take it from the approved invoice, never from a number typed again here. A retyped figure that differs from what is actually owed gets a deduction authorised against the wrong amount, and the authorisation is what governs.
rct:PeriodStartDateros:dateoptionalDD/MM/YYYY. The period the payment covers.
rct:PeriodEndDateros:dateoptionalrct:PaymentNotificationIdstringoptionalPresent only on AMEND and CANCEL. Omit on NEW — Revenue assigns it.
rct:ExternalIdstringoptionalSibling of the notification records. Your own reference, echoed back — how one record in a batch is tied to its row.
The fields you must never send
AppliedRate, DeductionAmount and NetPay belong to the same complexType as the request fields, so the schema permits sending them. Revenue’s schema notes are explicit that you must not:
“This element is not required in a request. This element is populated in a response. Will contain either 0, 20 or 35 as the value when populated.”
Response-only
rct:AppliedRate0 | 20 | 35never sendRevenue’s decision. Not an input.
rct:DeductionAmountdecimalnever sendCalculated by Revenue from the gross you sent.
rct:NetPaydecimalnever sendCalculated by Revenue.
Why this matters beyond politeness
Sending a rate asserts one. Deducting on a rate you chose — or on the indicative rate from the contract — makes you liable at 35% of the payment regardless of the subcontractor’s actual rate.
Brickie never sends them and never computes them. It records what Revenue returned and checks Revenue’s own arithmetic.
Notifying a payment already made
There is a path for a payment made before it was notified. It exists because the situation arises; it is not a route to prefer.
Post-payment notification
rct:PostPnbooleanoptionalMarks this as notifying a payment that has already been made.
rct:PostPnDtPaymentros:dateoptionalWhen you actually paid.
rct:PostPnRateAppliedintegeroptionalWhat you withheld. Note this is a statement about what you already did, not a request — the whole problem with a post-payment notification is that you chose a rate without authority.
rct:PostPnReasonstringoptionalWhy it was paid before being notified. Subject to the restricted character set.
This does not undo the exposure
Notifying afterwards records what happened. It does not retrospectively create the authorisation that was missing when you paid, and the 35% liability attaches to the missing authorisation. Treat it as disclosure, not as a fix.
The Deduction Authorisation
Returned in the response body in about 1.7 seconds. One round trip — no polling, nothing to come back for.
| Field | Meaning |
|---|---|
PaymentNotificationId | Revenue's identifier for this notification. Needed to amend or cancel it. |
AppliedRate | 0, 20 or 35. The rate for this payment and no other. |
GrossPay | Echoed back. Compare it against what you sent. |
DeductionAmount | What to withhold and remit to Revenue. |
NetPay | What the subcontractor receives. This is the figure the payment file uses. |
AcknowledgementNumber | Revenue's receipt. Matches the prn in your ROS inbox. |
Accepted with no AppliedRate is not an authorisation
If Revenue accepts the record but returns no AppliedRate, there is no Deduction Authorisation. Do not pay against it. Brickie raises an error rather than treating an accepted record as sufficient.
Checking Revenue’s arithmetic
Worth validating what comes back, but only in ways that cannot produce a false alarm. Brickie checks four things:
- The gross returned matches the gross requested.
- Gross minus deduction equals net, exactly.
- The rate is one Revenue says it issues — 0, 20 or 35.
- The deduction is not negative and does not exceed the gross.
It deliberately does not recompute the deduction from the rate. Revenue’s rounding convention is not documented, and a local recomputation disagreeing by a cent would either cry wolf on every payment or — far worse — tempt someone into “correcting” Revenue’s figure.
A failure is surfaced, never silently reconciled. If Revenue and your arithmetic disagree, that is something to see, not something to smooth over.