1. Widget Library
  2. Pay All

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.

StepWhat happensstep value in step_changed
ConnectionsThe taxpayer connects or fixes the tax authority connections of the tax entityconnections
Bank accountThe taxpayer picks, or adds, the bank account that funds the paymentsbank_account
ReviewEvery payment pending the taxpayer’s approval is listed. The ones in taxPayments open preselected. The taxpayer selects what to approvereview
ResultThe approved payments and the ones that failed, with the option to try the failed ones againresult

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.

ParameterTypeRequiredNotes
passwordlessTokenstringNoNon-empty when informed. Without it the widget shows the Remitian login
taxEntityobjectYesRequired for PAY_ALL
taxEntity.externalIdstringYesYour identifier for the tax entity. The widget fails with tax_entity_not_found when it does not exist in Remitian
taxPaymentsarrayNoPayments 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[].externalIdstringYesYour identifier for the payment
unsupportedTaxPaymentsarrayNoDisplay 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[].taxAuthorityRemitian.TaxAuthorityYesMust be a Remitian.TaxAuthority value
unsupportedTaxPayments[].formstringYesNon-empty. Shown as is, for example Form NJ-1040-ES
unsupportedTaxPayments[].taxYearnumberYesInteger from 2020 to the current year + 1
unsupportedTaxPayments[].dueDatestringYesyyyy-mm-dd
unsupportedTaxPayments[].amountnumberYesPositive
environment'sandbox' | 'production'NoDefaults to 'production'
onSuccess / onExit / onError / onEventfunctionNoSee 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 nameFires whenPayloadAlso calls
readyThe widget finished loading
step_changedThe taxpayer moved to another step{ step }
approvedAn approval attempt approved one or more payments{ flow, taxPayments[] }onSuccess
errorSomething failed. See Error Codes{ flow, code, message, taxPayments[]? }onError
rejectedThe taxpayer closed the widget with payments to approve and without having tried to approve any{ flow }
exitThe 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

codeWhentaxPayments[]
approval_failedOne or more selected payments could not be approved{ externalId, id, status, reason } per failed payment
tax_payments_not_foundExternal 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_foundtaxEntity.externalId does not exist in RemitianNot sent
load_failedThe widget could not load the tax entity, its payments or its accountsNot 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.

WhereStatusMeaning
onSuccessQueuedForPaymentThe taxpayer approved the payment. Remitian submits it on the payment date
onError with approval_failedThe status the payment kept, usually PendingClientApprovalThe 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.
  • onExit only 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 onSuccess with the payments approved in that attempt only, so add them up instead of replacing the previous result.
  • Use rejected to know that the taxpayer left without approving anything.