1. Widget Library
  2. SDK Setup

Every widget flow uses the same JavaScript SDK, @remitian/widget-sdk. This page covers what the flows share. The parameters, events and error codes of each flow are on its own page: Pay All and Pay with Remitian.

The SDK is a thin layer. It opens a modal with the Remitian portal inside, delivers the flow parameters in a POST request body (never in the URL) and relays what happens in the portal back to your code as callbacks.


​
Install the SDK

With a bundler, install the package from npm:

npm install @remitian/widget-sdk
import * as Remitian from '@remitian/widget-sdk';

Without a bundler, load it from the CDN:

<script src="https://cdn.remitian.com/widget-sdk/v1/remitian.js"></script>
<!-- exposes window.Remitian -->

The v1 URL always serves the latest 1.x release, so it receives fixes automatically.

​
Pinned Versions and Subresource Integrity

Pin an exact version when your policy requires it or when you use Subresource Integrity (SRI). Use the versioned URL with the sha384 hash published in the release notes of that version, and keep crossorigin="anonymous":

<script
  src="https://cdn.remitian.com/widget-sdk/v1.1.0/remitian.js"
  integrity="sha384-<hash from the release notes>"
  crossorigin="anonymous"
></script>

SRI does not work with the v1 URL: the hash matches exactly one file, and the file behind v1 changes on every release.


​
Host Page Setup

  • Authentication. Generate the passwordless token on your server and hand it to your frontend. Never call the Public API from frontend code; your credentials must stay on your server. The token is optional: without it, the widget shows the Remitian login.
  • Environment. environment selects the portal the widget opens. Use a token generated in the same environment.
SandboxProduction
environment'sandbox''production' (default)
Portal opened in the modalhttps://app.sandbox.remitian.comhttps://app.remitian.com
  • Region. The widgets open the US portal only. They are not available for CA customers.

​
Widget Lifecycle

Remitian.create validates the configuration and returns a handler with three methods:

const widget = Remitian.create(config);

widget.open(); // shows the modal
widget.exit(); // closes the modal (reusable; open() again later)
widget.destroy(); // removes everything; the handler cannot be reused
ErrorThrown when
RemitianConfigErrorcreate receives an invalid configuration. The message says what is wrong, and the widget does not open
RemitianStateErroropen or exit is called after destroy

Build the configuration with the builder of the flow, buildPayAllConfig or buildPayWithRemitianConfig. Each flow page lists its parameters.


​
Callbacks

The callbacks are optional and are the same for every flow. The payload of onSuccess, onError and onEvent depends on the flow.

CallbackFires whenPayload
onSuccess(result)Payments were approved in the widgetSee Pay All or Pay with Remitian
onError(error)Something failed inside the widget{ message, code?, ... }. The codes are listed on each flow page
onExit(reason)The widget closed{ reason }
onEvent(event)Every widget event, for analytics{ name, ... } with the payload of that event

​
Exit Reasons

reasonMeaning
user_closedThe user closed the widget from its close button
manualYour code called widget.exit()

widget.exit() calls onExit with manual and does not send an exit event to onEvent.

onExit is never a success signal. It only means the widget closed. Treat a payment as approved only when it comes back in onSuccess, or through the tax payment status on the Public API and Webhooks.

​
Event Names

onEvent receives every event, including the ones that also call another callback:

nameMeaningAlso calls
readyThe widget finished loading
step_changedThe user moved to another step
approvedPayments were approvedonSuccess
rejectedThe user closed the widget without approving
errorSomething failedonError
exitThe widget closed from its close buttononExit

Each flow page says which events the flow sends and with which payload.

​
Message Format

The portal and the SDK exchange messages through the browser postMessage API. The SDK only accepts messages that come from the Remitian portal origin of your environment and ignores any other. Use the callbacks instead of listening to these messages yourself: the callbacks are the supported contract.