1. Widget Library
  2. Pay with Remitian

The Pay with Remitian widget lets a user complete a tax payment inside your application, from entity and bank account setup through approval, without leaving your product.

To install the SDK and prepare your page, see SDK Setup. The callbacks shared by every flow are described in Callbacks. Pay All is the recommended flow for every integration.

Each resource is loaded or created by the external id you provide. Pre-fill fields are only used when the widget creates a resource; existing records are not updated from them, except for the payment amount and date the user confirms (see Existing Payments).

const widget = Remitian.create(
  Remitian.buildPayWithRemitianConfig({
    passwordlessToken: 'xxxx', // optional; omit to let the user log in
    environment: 'sandbox', // 'sandbox' | 'production' (default)
    taxPayment: { externalId: 'pay-2026-0412' },
    onSuccess: (result) => {},
    onExit: (reason) => {},
    onError: (error) => {},
  }),
);

widget.open(); // shows the modal

​
What the Taxpayer Sees

The widget handles one tax payment. It only shows the steps that are still missing for that payment.

StepShown whenWhat happens
Tax entityNo tax entity exists for taxEntity.externalIdThe user confirms the tax entity details, pre-filled from taxEntity, and the widget creates it
Bank accountThe payment has no bank account to useThe user adds the bank account, pre-filled from bankAccount
ApprovalAlwaysThe user reviews the payment (amount, service fee, payment date and bank account), connects the tax authority when needed and approves it

After the approval, the widget shows the scheduled payment with the date Remitian will debit the account.


​
Parameters

Build the configuration with Remitian.buildPayWithRemitianConfig. The table lists its inputs. When building the config by hand, the flow-specific parameters (taxPayment, taxEntity, taxAccount, bankAccount) nest under parameters next to flow; the rest stays at the top level.

ParameterTypeRequiredNotes
passwordlessTokenstringNoNon-empty when informed. Without it the widget shows the Remitian login
taxPaymentobjectYesRequired for PAY_WITH_REMITIAN
taxPayment.externalIdstringYesYour identifier for the payment. Remitian internal ids are never accepted
taxPayment.amountnumberNoPositive when informed
taxPayment.paymentTypeIdnumberNoUse Remitian.PaymentType.*; the full list matches Available Payment Types
taxPayment.paymentDatestringNoyyyy-mm-dd
taxPayment.periodEndDatestringNoyyyy-mm-dd
taxEntityobjectNotype and externalId required when informed; see the Tax Entity Pre-fill section below
taxAccountobjectNoexternalId required when informed. Required with taxAuthority to create the payment
taxAccount.taxAuthorityRemitian.TaxAuthorityYesRequired to create the payment (no payment exists for taxPayment.externalId). Must be a Remitian.TaxAuthority value
bankAccountobjectNopaymentNetwork and externalId required when informed; see the Bank Account Pre-fill section below
environment'sandbox' | 'production'NoDefaults to 'production'
onSuccess / onExit / onError / onEventfunctionNoSee Events and Payloads

Every externalId must be 3 to 100 characters long and contain only letters, numbers, spaces, underscores, commas, periods or hyphens. Remitian.create rejects any other value.

Widget parameters are delivered to the portal in a POST body, never in the URL, so they cannot leak into logs or browser history. Parameters accept only the documented fields; anything else is dropped from the widget’s pre-fill.

​
Full Pre-fill

Inform everything, including the optional fields, so the widget can create the missing resources on the user’s behalf:

const widget = Remitian.create(
  Remitian.buildPayWithRemitianConfig({
    passwordlessToken: 'xxxx', // optional; omit to let the user log in
    environment: 'sandbox', // 'sandbox' | 'production' (default)

    taxPayment: {
      externalId: 'pay-2026-0412', // required: loads or creates the payment by this external id
      amount: 9169.0, // this and the fields below: optional, only used when the resource needs to be created
      paymentTypeId: Remitian.PaymentType.US_IRS_1040_INDIVIDUAL_INCOME_TAX_ESTIMATED_TAX,
      paymentDate: '2026-09-15', // yyyy-mm-dd
      periodEndDate: '2026-06-30', // yyyy-mm-dd
    },
    taxEntity: Remitian.buildIrsSsnTaxEntityConfig({
      // or buildIrsEinTaxEntityConfig for businesses
      externalId: 'client-8842', // required: loads or creates the tax entity by this external id
      tin: '123456789', // this and the fields below: optional, only used when the resource needs to be created
      firstName: 'Alice',
      lastName: 'Smith',
      email: 'alice@example.com',
      phone: '+1 555 0100',
      address: {
        address1: '123 Main St',
        city: 'Springfield',
        region: 'IL',
        country: 'US',
        postalCode: '62701',
      },
    }),
    taxAccount: {
      externalId: 'acct-2026', // required: loads the tax account by this external id, or creates it with this external id
      taxAuthority: Remitian.TaxAuthority.US_IRS, // required to create the payment
    },
    bankAccount: Remitian.buildAchBankAccountConfig({
      externalId: 'bank-115', // required: loads or creates the bank account by this external id
      bankAccountName: 'Operating', // this and the fields below: optional, only used when the resource needs to be created
      accountNumber: '000123456789',
      routingNumber: '121000358',
    }),

    onSuccess: (result) => {},
    onExit: (reason) => {},
    onError: (error) => {},
    onEvent: (event) => {},
  }),
);

widget.open(); // shows the modal
widget.exit(); // closes the modal (reusable; open() again later)
widget.destroy(); // removes everything; the handler cannot be reused

​
Minimal Info

When the resources already exist (a schedule previously created through the Public API, for instance), the tax payment external id is all it takes; the widget loads everything from it and asks the user for anything still missing:

const widget = Remitian.create(
  Remitian.buildPayWithRemitianConfig({
    taxPayment: { externalId: 'pay-2026-0412' },
  }),
);

widget.open();

Building the RemitianConfig by hand also works: the flow-specific parameters (taxPayment, taxEntity, taxAccount, bankAccount) nest under parameters together with flow: Remitian.Flow.PAY_WITH_REMITIAN, while passwordlessToken, environment, and the callbacks stay at the top level.

create validates the configuration and throws a RemitianConfigError when something is wrong. See Widget Lifecycle.

​
Tax Entity Pre-fill

taxEntity pre-fills the tax entity created inside the widget. It is one of two shapes, selected by type (Remitian.TaxEntityType): IrsSsn (individual) or IrsEin (business). The factory helpers stamp the type for you:

// Individual
taxEntity: Remitian.buildIrsSsnTaxEntityConfig({
  externalId: 'client-8842', // required: your identifier
  firstName: 'Alice', // optional
  lastName: 'Smith', // optional
  email: 'alice@example.com', // optional
  tin: '123456789', // optional
  phone: '+1 555 0100', // optional
  address: {
    address1: '123 Main St',
    city: 'Springfield',
    region: 'IL',
    country: 'US',
    postalCode: '62701',
  }, // optional; also address2, apartmentOrSuite, poBox
});

// Business
taxEntity: Remitian.buildIrsEinTaxEntityConfig({
  externalId: 'biz-101',
  businessName: 'Acme Corporation',
});

Building the object by hand works too: set type: Remitian.TaxEntityType.IrsSsn (or IrsEin) explicitly. Everything except type and externalId is optional pre-fill; the widget asks the user for whatever is missing.

​
Tax Account Resolution

When taxEntity.externalId matches an existing tax entity, the widget picks the tax account for a new payment in this order:

  1. The tax entity’s account for taxAccount.taxAuthority whose external id is taxAccount.externalId.
  2. Otherwise, the tax entity’s account for taxAccount.taxAuthority with the account type of the tax entity: Personal for IrsSsn, Corporate for IrsEin. An account of a different type is never used.
  3. Otherwise, the widget creates the account with taxAccount.taxAuthority, that account type and taxAccount.externalId. You can then find it with GET /v1/taxpayers/{taxpayerId}/tax-accounts?externalId=....

External ids are not unique in Remitian, so the widget only considers accounts of the resolved tax entity and tax authority. Existing accounts are never changed: the widget does not add or replace their external id.

​
Existing Payments

When a payment already exists for taxPayment.externalId, the widget loads it instead of creating a new one. If the payment is pending the user’s approval and taxPayment.amount or taxPayment.paymentDate differs from the scheduled values, the widget shows the differences (including any service fee change) and asks the user to apply them or keep the existing values. The other fields of an existing payment are never changed.

​
Bank Account Pre-fill

bankAccount pre-fills the bank account created inside the widget, selected by paymentNetwork (Remitian.PaymentNetwork): currently Ach only. The factory helper stamps the network:

bankAccount: Remitian.buildAchBankAccountConfig({
  externalId: 'bank-115', // required: your identifier
  bankAccountName: 'Operating', // optional
  accountNumber: '000123456789', // optional
  routingNumber: '121000358', // optional
});

Building the object by hand works too: set paymentNetwork: Remitian.PaymentNetwork.Ach explicitly. Everything except paymentNetwork and externalId is optional pre-fill.


​
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
approvedThe user approved the payment{ taxPayment }onSuccess
errorSomething failed inside the widget{ message }onError
exitThe user closed the widget{ reason }onExit

​
approved

onSuccess receives the approved payment:

{
  taxPayment: { externalId: 'pay-2026-0412', status: 'QueuedForPayment' },
}

​
error

{ message: 'An error occurred inside the widget.' }

​
Error Codes

onError always receives a message. code is optional: read it when present and fall back to message.

A configuration problem is not reported through onError: Remitian.create throws a RemitianConfigError before the widget opens. See Widget Lifecycle.


​
Status Values

taxPayment.status takes the tax payment status names of the Public API, also exposed as Remitian.TaxPaymentStatus.

WhereStatusMeaning
onSuccessQueuedForPaymentThe user approved the payment. Remitian submits it on the payment date

See Tax Payment Statuses for every status and its meaning.


​
Success Handling

  • Treat the 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 payment was approved.
  • To find the resources the widget created, list them by the external ids you provided, for example GET /v1/taxpayers/{taxpayerId}/tax-accounts?externalId=....