- Widget Library
- Pay All
Widget Library
Pay All
The widget flow that lets a taxpayer approve every pending tax payment of a tax entity in one session: parameters, events, error codes and status values.
Pay All is the recommended widget flow. It lists every tax payment already scheduled and pending the taxpayer’s approval for one tax entity, resolves the pending tax authority connections, picks the funding bank account and approves the payments in one session.
To install the SDK and prepare your page, see SDK Setup. The callbacks shared by every flow are described in Callbacks.
Pay All requires @remitian/widget-sdk 1.1.0 or later. The v1 CDN script always serves the latest 1.x release, so it already includes Pay All. If you pinned an older version (in your package.json or lockfile, or with a versioned CDN URL such as https://cdn.remitian.com/widget-sdk/v1.0.0/remitian.js), update it with npm install @remitian/widget-sdk@^1.1.0 or https://cdn.remitian.com/widget-sdk/v1.1.0/remitian.js. On 1.0.0, Remitian.buildPayAllConfig does not exist.
The widget does not create tax payments. It lists the payments that are in PendingClientApproval; see Payment Approval for when a payment created through the Public API starts in that status. Create the tax entity and schedule its tax payments with the Public API first (see Use Case 4: Manage Tax Entities and Use Case 8: Schedule Tax Payments, including tax payment batches), then open the widget with the same external ids.
const widget = Remitian.create(
Remitian.buildPayAllConfig({
passwordlessToken: 'xxxx', // optional; omit to let the user log in
environment: 'sandbox', // 'sandbox' | 'production' (default)
// Required. Only payments and connections of this tax entity are handled.
taxEntity: { externalId: 'my_tax_entity_123' },
// Optional. These payments open preselected in the review step.
taxPayments: [{ externalId: 'my_tax_payment_123' }],
// Optional, display only. Payments you could not create in Remitian.
unsupportedTaxPayments: [
{ taxAuthority: Remitian.TaxAuthority.US_NJ, form: 'Form NJ-1040-ES', taxYear: 2026, dueDate: '2026-09-15', amount: 340.0 },
],
onSuccess: (result) => {}, // approved payments only
onError: (error) => {}, // failed payments only
onExit: (reason) => {}, // never a success signal
onEvent: (event) => {},
}),
);
widget.open();
What the Taxpayer Sees
The widget is a wizard with up to four steps. A step is skipped when there is nothing to do in it.
| Step | What happens | step value in step_changed |
|---|---|---|
| Connections | The taxpayer connects or fixes the tax authority connections of the tax entity | connections |
| Bank account | The taxpayer picks, or adds, the bank account that funds the payments | bank_account |
| Review | Every payment pending the taxpayer’s approval is listed. The ones in taxPayments open preselected. The taxpayer selects what to approve | review |
| Result | The approved payments and the ones that failed, with the option to try the failed ones again | result |
When the tax entity has no payment to approve, the widget shows an empty state instead of the wizard.
Bank Accounts
The taxpayer manages their saved bank accounts inside the widget, under General settings > Bank account:
- Add an account manually or by connecting it through Plaid.
- Edit the nickname at any time. On a manually added account the type can also change, and the numbers too while no scheduled payment or subscription uses it. An account connected through Plaid keeps the type and numbers from the bank.
- Delete an account that no scheduled payment or subscription uses.
- Set as primary to make it the tax entity’s default account for new payments. Payments already scheduled keep their account.
On a single payment, Payment details only picks the account that payment is debited from. Accounts added or changed in the widget are the same ones returned by List bank accounts.
Parameters
Build the configuration with Remitian.buildPayAllConfig. When building the config by hand, set flow: 'PAY_ALL' and nest taxEntity, taxPayments and unsupportedTaxPayments under parameters; the rest stays at the top level.
| Parameter | Type | Required | Notes |
|---|---|---|---|
passwordlessToken | string | No | Non-empty when informed. Without it the widget shows the Remitian login |
taxEntity | object | Yes | Required for PAY_ALL |
taxEntity.externalId | string | Yes | Your identifier for the tax entity. The widget fails with tax_entity_not_found when it does not exist in Remitian |
taxPayments | array | No | Payments that open preselected in the review step. It never filters the list: every payment of the tax entity pending approval is shown, the others as ready to approve |
taxPayments[].externalId | string | Yes | Your identifier for the payment |
unsupportedTaxPayments | array | No | Display only. Payments you could not create in Remitian; they never become scheduled payments. Once every listed payment is approved, Done on the result opens a notice listing them |
unsupportedTaxPayments[].taxAuthority | Remitian.TaxAuthority | Yes | Must be a Remitian.TaxAuthority value |
unsupportedTaxPayments[].form | string | Yes | Non-empty. Shown as is, for example Form NJ-1040-ES |
unsupportedTaxPayments[].taxYear | number | Yes | Integer from 2020 to the current year + 1 |
unsupportedTaxPayments[].dueDate | string | Yes | yyyy-mm-dd |
unsupportedTaxPayments[].amount | number | Yes | Positive |
environment | 'sandbox' | 'production' | No | Defaults to 'production' |
onSuccess / onExit / onError / onEvent | function | No | See Events and Payloads |
externalId values follow the same rule as Pay with Remitian (3 to 100 characters: letters, numbers, spaces, underscores, commas, periods or hyphens). Remitian.create rejects an invalid config before opening the widget.
Events and Payloads
Every event reaches onEvent as { name, ...payload }. Some events also call another callback, which receives the payload without name.
Event name | Fires when | Payload | Also calls |
|---|---|---|---|
ready | The widget finished loading | ||
step_changed | The taxpayer moved to another step | { step } | |
approved | An approval attempt approved one or more payments | { flow, taxPayments[] } | onSuccess |
error | Something failed. See Error Codes | { flow, code, message, taxPayments[]? } | onError |
rejected | The taxpayer closed the widget with payments to approve and without having tried to approve any | { flow } | |
exit | The taxpayer closed the widget | { reason } | onExit |
step_changed
step is one of connections, bank_account, review or result (see What the Taxpayer Sees):
{ name: 'step_changed', step: 'review' }
New steps may be added; treat the list as non-exhaustive.
approved
onSuccess receives the payments approved in the attempt:
{
flow: 'PAY_ALL',
taxPayments: [
{ externalId: 'my_tax_payment_123', id: '3f0c9a52-...', status: 'QueuedForPayment' },
],
}
externalId is null for payments created without one.
error
onError receives the failure, with the failed payments and a reason for each one when the failure is about specific payments:
{
flow: 'PAY_ALL',
code: 'approval_failed',
message: '1 payment could not be approved.',
taxPayments: [
{ externalId: 'my_tax_payment_456', id: '7b21e4d0-...', status: 'PendingClientApproval', reason: '...' },
],
}
On a partial failure both fire: onSuccess with the approved payments and onError with the failed ones.
rejected
{ name: 'rejected', flow: 'PAY_ALL' }
rejected is not an error and does not call onError. After an approval attempt, the outcome is reported by onSuccess and onError only.
Error Codes
code | When | taxPayments[] |
|---|---|---|
approval_failed | One or more selected payments could not be approved | { externalId, id, status, reason } per failed payment |
tax_payments_not_found | External ids in taxPayments[] the widget does not list: unknown, paid, cancelled, from another tax entity, or expired or failed with a payment date more than 30 days ago. The widget still opens with the other payments | { externalId, reason: 'not_found' } per external id, without id and status |
tax_entity_not_found | taxEntity.externalId does not exist in Remitian | Not sent |
load_failed | The widget could not load the tax entity, its payments or its accounts | Not sent |
New codes may be added; treat the list as non-exhaustive.
A configuration problem is not reported through onError: Remitian.create throws a RemitianConfigError before the widget opens. See Widget Lifecycle.
Status Values
taxPayments[].status takes the tax payment status names of the Public API, also exposed as Remitian.TaxPaymentStatus.
| Where | Status | Meaning |
|---|---|---|
onSuccess | QueuedForPayment | The taxpayer approved the payment. Remitian submits it on the payment date |
onError with approval_failed | The status the payment kept, usually PendingClientApproval | The approval did not go through, so the payment is still waiting for the taxpayer |
See Tax Payment Statuses for every status and its meaning.
Success Handling
- Treat a payment as approved only when it comes back in
onSuccess, or through the tax payment status on the Public API and Webhooks. onExitonly means the widget closed; it never means the payments were approved.- The taxpayer can approve more than once in a session, for example to try the failed payments again. Each attempt calls
onSuccesswith the payments approved in that attempt only, so add them up instead of replacing the previous result. - Use
rejectedto know that the taxpayer left without approving anything.