Scheduling tax payments and the payment lifecycle
Schedule a tax payment against a tax account, then follow it from approval to processing with statuses and webhook events.
What it is
A tax payment is a scheduled payment against an existing tax account. You create it with POST /v1/taxpayers/{taxpayerId}/tax-payments, using your own ID in externalId, and Remitian processes it on the scheduled date once it is approved and funded.
When you need it
- You want to schedule a single tax payment for a taxpayer from your system.
- You need to check where a payment is, or explain to a firm why it has not been processed.
How it works
- Send the payment with
taxAccountId,paymentTypeId,periodEndDate,paymentDateandamount.taxAuthorityis still required but ignored: the tax authority always comes from the tax account. - Attach a bank account now with the optional
bankAccountId, or associate one later. The payment cannot be processed until a bank account is set. - Remitian returns the payment
id. The payment starts in Pending Approval until the taxpayer or a firm user approves it. - Once approved and funded, it moves to Queued For Payment and is processed on the scheduled date.
- Follow progress with
GET /v1/taxpayers/{taxpayerId}/tax-paymentsor theschedule.*webhook events.
| Stage | What it means |
|---|---|
| Pending Approval | Waiting for the taxpayer, accountant or taxpayer representative to approve |
| Queued For Payment | Approved and waiting for the scheduled date |
| Submitted | Sent to the tax authority |
| Processed | Payment completed |
| Failed, Voided, Deleted, Expired, Paid Manually | End states: processing failed, cancelled before processing, deleted, approval window expired, or the taxpayer paid directly through the tax authority portal |
Common questions
Why is a payment stuck in Pending Approval?
It has not been approved yet. The PendingClientApproval, PendingAccountantApproval and PendingRepresentativeApproval statuses tell you whose approval is outstanding. An approved payment also needs a bank account before it can be processed.
Why did I get a 400 error when scheduling?
The paymentTypeId must belong to the tax account's tax authority and match the account type: Personal accounts accept only individual payment types, Corporate accounts only business ones. The response body names the conflicting values.
How do I filter the payment list by more than one value?
Pass values comma-separated in one parameter, for example statuses=PendingClientApproval,Processed. Repeating the parameter is not supported: only one value is kept. You can filter by status, tax authority, tax entity, tax account, external ID and payment or submission date range.
Can I filter by an external ID that contains a comma?
No. The comma is always read as a separator, so the ID is split into several incorrect values. Avoid commas in tax payment external IDs you plan to filter on.
Is anything different for Canadian tax payments?
Yes, in a few places:
- Filter with
CA_CRAorCA_QCintaxAuthorities. - Some payment types need a
remittanceInformationobject.CraPayrolltakes the payroll program account code (for exampleRP0001), gross payroll and number of employees. Revenu Québec payments useQuebecPayroll,QuebecPaymentCodeorQuebecSalesTax. - A tax code is only accepted on CRA corporate, payroll and GST/HST payments. A US payment that includes one is rejected with
Schedule.TaxCodeNotAllowed. fundingPacesets the direct debit speed: regular (the default), express or priority.- Payments stay blocked until the taxpayer user, and for businesses and trusts the business, is verified.