- Widget Library
- SDK Setup
Widget Library
SDK Setup
Install the widget SDK, prepare the host page and handle the callbacks shared by every widget flow.
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.
environmentselects the portal the widget opens. Use a token generated in the same environment.
| Sandbox | Production | |
|---|---|---|
environment | 'sandbox' | 'production' (default) |
| Portal opened in the modal | https://app.sandbox.remitian.com | https://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
| Error | Thrown when |
|---|---|
RemitianConfigError | create receives an invalid configuration. The message says what is wrong, and the widget does not open |
RemitianStateError | open 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.
| Callback | Fires when | Payload |
|---|---|---|
onSuccess(result) | Payments were approved in the widget | See 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
reason | Meaning |
|---|---|
user_closed | The user closed the widget from its close button |
manual | Your 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:
name | Meaning | Also calls |
|---|---|---|
ready | The widget finished loading | |
step_changed | The user moved to another step | |
approved | Payments were approved | onSuccess |
rejected | The user closed the widget without approving | |
error | Something failed | onError |
exit | The widget closed from its close button | onExit |
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.