- Widget Library
- Pay with Remitian
Widget Library
Pay with Remitian
The widget flow that lets a user complete a single tax payment inside your application: parameters, events, error codes and status values.
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.
| Step | Shown when | What happens |
|---|---|---|
| Tax entity | No tax entity exists for taxEntity.externalId | The user confirms the tax entity details, pre-filled from taxEntity, and the widget creates it |
| Bank account | The payment has no bank account to use | The user adds the bank account, pre-filled from bankAccount |
| Approval | Always | The 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.
| Parameter | Type | Required | Notes |
|---|---|---|---|
passwordlessToken | string | No | Non-empty when informed. Without it the widget shows the Remitian login |
taxPayment | object | Yes | Required for PAY_WITH_REMITIAN |
taxPayment.externalId | string | Yes | Your identifier for the payment. Remitian internal ids are never accepted |
taxPayment.amount | number | No | Positive when informed |
taxPayment.paymentTypeId | number | No | Use Remitian.PaymentType.*; the full list matches Available Payment Types |
taxPayment.paymentDate | string | No | yyyy-mm-dd |
taxPayment.periodEndDate | string | No | yyyy-mm-dd |
taxEntity | object | No | type and externalId required when informed; see the Tax Entity Pre-fill section below |
taxAccount | object | No | externalId required when informed. Required with taxAuthority to create the payment |
taxAccount.taxAuthority | Remitian.TaxAuthority | Yes | Required to create the payment (no payment exists for taxPayment.externalId). Must be a Remitian.TaxAuthority value |
bankAccount | object | No | paymentNetwork and externalId required when informed; see the Bank Account Pre-fill section below |
environment | 'sandbox' | 'production' | No | Defaults to 'production' |
onSuccess / onExit / onError / onEvent | function | No | See 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:
- The tax entity’s account for
taxAccount.taxAuthoritywhose external id istaxAccount.externalId. - Otherwise, the tax entity’s account for
taxAccount.taxAuthoritywith the account type of the tax entity: Personal forIrsSsn, Corporate forIrsEin. An account of a different type is never used. - Otherwise, the widget creates the account with
taxAccount.taxAuthority, that account type andtaxAccount.externalId. You can then find it withGET /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 name | Fires when | Payload | Also calls |
|---|---|---|---|
ready | The widget finished loading | ||
approved | The user approved the payment | { taxPayment } | onSuccess |
error | Something failed inside the widget | { message } | onError |
exit | The 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.
| Where | Status | Meaning |
|---|---|---|
onSuccess | QueuedForPayment | The 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. onExitonly 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=....