1. Use Case 8: Schedule Tax Payments
  2. Use Case 8: Schedule Tax Payments

Schedule tax payments associated with tax accounts. Create tax payments using your system’s tax payment ID with the externalId field. Each tax payment must be associated with an existing tax account.

Use Case 8: Schedule Tax Payments

​
Understanding Tax Payments

Tax payments represent scheduled payments for tax obligations associated with a tax account. Once created, the tax payment will be in Pending Approval status until approved by the taxpayer or firm user. A bank account must be associated before the payment can be processed — you can provide it at creation time with the optional bankAccountId field, or associate it later. Once approved and a bank account is set up, the payment will move to Queued For Payment status and Remitian will process it on the scheduled date.

The complete list of payment types, with the paymentTypeId values accepted by the API, is available at Available Payment Types.

Tax Payment Object Structure:

FieldTypeDescription
idguidUnique identifier for the tax payment
Example: 069bc3f4-d65e-73f7-8133-f5800e825514
externalIdstringYour system’s unique identifier
Example: my_tax_payment_123
taxAccountIdguidAssociated tax account identifier
Example: 059bc3f4-d65e-73f7-8133-f5800e825513
bankAccountIdguid(Optional) Funding bank account for the payment. Can be provided at creation or associated later; required before the payment can be processed
Example: 049bc3f4-d65e-73f7-8133-f5800e825512
taxAuthoritystring(Deprecated) Still required, but the value is ignored: the tax authority always comes from the tax account
Example: US_IRS
paymentTypeIdnumberType of the tax payment, see the Available Payment Types page
Example: 10101
periodEndDatedateEnd date of the tax period the payment covers
Example: 2026-12-31
paymentDatedateScheduled payment date
Example: 2026-12-31
amountdecimalPayment amount
Example: 100.00

​
Tax Payment Statuses

The status field of a tax payment and the statuses filter of List Tax Payments use the values below.

StatusDescription
PendingClientApprovalAwaiting approval from the taxpayer
PendingAccountantApprovalAwaiting approval from the accountant
PendingRepresentativeApprovalAwaiting approval from a taxpayer representative
QueuedForPaymentApproved and queued for processing on the scheduled date
SubmittedSubmitted to the tax authority, not yet pulled
ProcessingSubmissionSubmission to the tax authority in progress
ProcessingPaymentFunds being prepared for the bank
ProcessedPayment completed
PaidManuallyPaid outside Remitian; marked by the firm in the Remitian platform or through the API
QueuedForReminderQueued for a payment reminder instead of processing
ReminderSentReminder notification sent to the taxpayer
PaymentLinkClickedTaxpayer clicked the external tax authority payment link (outcome unknown)
ExpiredApproval window expired before the payment was approved
DeniedApproval was denied
VoidedCancelled before processing
FailedPayment processing failed
DeletedMarked as deleted

​
Payment Approval

A tax payment may need an approval before Remitian processes it. Who has to approve, and the status the payment starts in, depend on who created the payment and on the settings of the firm.

​
Payments Created Through the Public API

A payment created with Schedule a Tax Payment or in a tax payment batch is created by your client application, not by a firm user. Remitian checks the conditions below in order, and the first one that matches applies.

ConditionStarting statusWho acts next
The taxpayer has an active taxpayer representativePendingRepresentativeApprovalThe representative approves the payment
The firm has skipClientApproval set to trueQueuedForPaymentNobody. The payment is processed on its payment date
The firm has requireInternalApproval set to true and the taxpayer is owned by a firm userPendingAccountantApprovalThe firm user that owns the taxpayer approves it. The payment then moves to PendingClientApproval
None of the abovePendingClientApprovalThe taxpayer approves the payment

With skipClientApproval set to true the payment is queued when it is created, so the request must include bankAccountId. A request without it is rejected.

A taxpayer is owned by a firm user when you send ownerFirmUserId at creation or call Change the Owner of a Taxpayer.

​
Payments Created in the Widgets

WidgetWhat happens
Pay with RemitianThe taxpayer creates the payment and approves it in the same flow, so it starts in QueuedForPayment. When a payment already exists for taxPayment.externalId and is in PendingClientApproval, the widget asks the taxpayer to approve it; see Existing Payments
Pay AllThe widget does not create payments. It lists the payments of the tax entity that are in PendingClientApproval and the taxpayer approves them in one session

A payment in PendingAccountantApproval or PendingRepresentativeApproval cannot be approved by the taxpayer in a widget until the firm user or the representative approves it.

​
Firm Settings

Both settings belong to the firm and are set with Create a Firm or changed later with PATCH /v1/firms/{firmId}. Both default to false.

SettingEffect
skipClientApprovalWhen true, payments that do not need another approval skip the taxpayer approval and start in QueuedForPayment. This includes every payment created through the Public API, even when requireInternalApproval is true
requireInternalApprovalWhen true, a payment for a taxpayer that is owned by a firm user starts in PendingAccountantApproval, and the owner approves it before the taxpayer does. This applies to the payments created through the Public API when skipClientApproval is false, and to the payments created in the Remitian platform by a firm user who does not own the taxpayer. Firm Admin users and firm users with the CanSendApprovalDirectlyToClient permission are not affected

​
After the Approval

ActionResulting status
The last required approval is givenQueuedForPayment
The approver denies the paymentDenied
The payment is not approved in timeExpired

Remitian sends the schedule.PendingApproval.v1 webhook when a payment starts to wait for an approval, and schedule.QueuedForPayment.v1 when it is approved. See Webhook Events and the full list of statuses in Tax Payment Statuses.


​
Schedule a Tax Payment

Sequence of Events:

  1. Your system sends a request to schedule a tax payment using an external ID and associates it with an existing tax account
  2. Remitian responds with the created tax payment’s details
  3. Your system can then use this id for subsequent operations

HTTP Request:

POST https://public-api.remitian.com/v1/taxpayers/{taxpayerId}/tax-payments
Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN
x-api-key: YOUR_API_KEY

{
  "externalId": "my_tax_payment_123",
  "taxAccountId": "059bc3f4-d65e-73f7-8133-f5800e825513",
  "bankAccountId": "049bc3f4-d65e-73f7-8133-f5800e825512",
  "taxAuthority": "US_IRS",
  "paymentTypeId": 10101,
  "periodEndDate": "2026-12-31",
  "paymentDate": "2026-12-31",
  "amount": 100.00
}

Note: bankAccountId is optional. Omit it to associate a bank account later; the payment cannot be processed until one is set.

Validation:

  • paymentTypeId must belong to the tax account’s tax authority.
  • The payment type must match the tax account type: Personal tax accounts accept only individual payment types (e.g. Form 1040, Form 706), and Corporate tax accounts accept only business payment types (e.g. Form 1120, Form 1065).

A mismatch returns 400 Bad Request, naming the conflicting values in the response body:

HTTP/1.1 400 Bad Request
Content-Type: application/problem+json

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "errors": {
    "Schedule.PaymentTypeTaxAccountTypeMismatch": [
      "The payment type 'US_IRS_1120_CORPORATION_INCOME_TAX_BALANCE_DUE_ON_RETURN_OR_NOTICE' cannot be used with a 'Personal' tax account."
    ]
  }
}

HTTP Response:

HTTP/1.1 201 Created
Content-Type: application/json

{
  "id": "069bc3f4-d65e-73f7-8133-f5800e825514",
  "externalId": "my_tax_payment_123"
}

​
List Tax Payments

Sequence of Events:

  1. Your system sends a request to list all tax payments associated with a specific taxpayer
  2. You can filter tax payments by statuses, taxAuthorities, taxEntityIds, taxAccountIds, and/or externalIds
  3. Remitian responds with a paginated list of tax payments

Query Parameters:

ParameterTypeDescription
statusesstringFilter by status. Comma-separated for multiple values — see Tax Payment Statuses
Example: PendingClientApproval,Processed
taxAuthoritiesstringFilter by tax authority. Comma-separated for multiple values — see Available Tax Authorities in Manage Tax Accounts
Example: US_IRS,US_CA
taxEntityIdsguidFilter by tax entity. Comma-separated for multiple values
Example: 039bc3f4-d65e-73f7-8133-f5800e825511
taxAccountIdsguidFilter by tax account. Comma-separated for multiple values
Example: 059bc3f4-d65e-73f7-8133-f5800e825513
externalIdsstringFilter by your system’s tax payment ID. Comma-separated for multiple values
Example: my_tax_payment_123
paymentDateFrom / paymentDateTodateFilter by scheduled payment date range
Example: 2026-12-01
submissionDateFrom / submissionDateTodateFilter by submission date range
Example: 2026-12-01
pageNumbernumberPage to retrieve
Example: 1
pageSizenumberItems per page
Example: 10

Multi-value format: to filter by more than one value, pass them comma-separated in a single query parameter, e.g. ?statuses=PendingClientApproval,Processed. Repeating the query key (?statuses=PendingClientApproval&statuses=Processed) is not supported — the API Gateway forwards only one of the repeated values and silently drops the rest. Comma-separated is the only supported multi-value format.

HTTP Request:

GET https://public-api.remitian.com/v1/taxpayers/{taxpayerId}/tax-payments?statuses=PendingClientApproval,Processed
Authorization: Bearer YOUR_ACCESS_TOKEN
x-api-key: YOUR_API_KEY

HTTP Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "items": [
    {
      "id": "069bc3f4-d65e-73f7-8133-f5800e825514",
      "externalId": "my_tax_payment_123",
      "taxAccountId": "059bc3f4-d65e-73f7-8133-f5800e825513",
      "bankAccountId": "049bc3f4-d65e-73f7-8133-f5800e825512",
      "paymentTypeId": 10101,
      "status": "Processed",
      "periodEndDate": "2026-12-31",
      "paymentDate": "2026-12-31",
      "amount": 100.00
    }
  ],
  "currentPage": 1,
  "pageSize": 10,
  "totalCount": 1,
  "totalPages": 1
}

Accepted statuses Values: every status listed in Tax Payment Statuses.

Validation:

An unknown value passed to any filter returns 400 Bad Request, naming the invalid value in the response body:

HTTP/1.1 400 Bad Request
Content-Type: application/problem+json

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "errors": {
    "Statuses": [
      "'Unknown' is not a valid Statuses value."
    ]
  }
}

Known limitation: an external ID that contains a comma cannot be used with the externalIds filter — the comma is always interpreted as a value separator, so a comma-containing ID gets split into multiple (incorrect) filter values.


​
Mark a Tax Payment as Paid Manually

Use this when the tax payment was paid outside Remitian, for example directly on the tax authority’s website. Remitian stops processing the tax payment and will not pull the funds.

Sequence of Events:

  1. Your system sends a request with the taxpayerId and the id of the tax payment
  2. Remitian sets the tax payment to Paid Manually and responds with 204 No Content
  3. Remitian sends the schedule.PaidManually.v1 webhook, see Webhooks

HTTP Request:

POST https://public-api.remitian.com/v1/taxpayers/{taxpayerId}/tax-payments/{taxPaymentId}/mark-paid-manually
Authorization: Bearer YOUR_ACCESS_TOKEN
x-api-key: YOUR_API_KEY

The request has no body.

HTTP Response:

HTTP/1.1 204 No Content

Statuses That Can Be Marked as Paid Manually:

  • PendingClientApproval
  • PendingAccountantApproval
  • QueuedForPayment
  • PaymentLinkClicked

A tax payment in any other status returns 409 Conflict, naming the current status in the response body:

HTTP/1.1 409 Conflict
Content-Type: application/problem+json

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.10",
  "title": "Cannot mark as paid manually because the status is 'Processed'.",
  "status": 409
}

A tax payment that does not exist, or that belongs to another taxpayer, returns 404 Not Found.

Note: It is safe to repeat the request. A tax payment that is already PaidManually returns 204 No Content again, and the webhook is not sent a second time.


​
Tax Payment Batches

To schedule many tax payments at once, submit up to 5,000 tax payments for the taxpayers of one firm in a single request. Remitian schedules each item asynchronously and sends the batch.Processed.v1 webhook event when every item has an outcome.

See Tax Payment Batches for the integration flow, the endpoints, the webhook and the error handling.