Implementation guide - Resurs Docs

The Resurs Payment Widget is a standard Web Component for integrating Resurs payment methods into your checkout flow. It is flexible, fully compliant, and easy to integrate.. The widget renders your Resurs payment methods, and emits a JavaScript event when the user selects one of them.

Quick Start

This is a quick start, for more in-depth information, skip ahead to the Full Guide.*

The following steps outline how to integrate the Resurs Payment Widget into your checkout page:

Obtain a session token from the Resurs Widget API. You will need to supply this token when setting up the widget.
Add the necessary script tag in your webpage to load the widget source.
Invoke the web component(s) to render the Payment Widget*.

*There are modular options for those who want an even more flexible approach. See Composing with Modular Components.

Step 1. Obtain a session token

Before rendering the widget, you must obtain a session token from the Resurs Widget API. See the Backend Integration Guide.

Step 2. Add the script tag

<script
  id="resurs-payment-widget"
  data-customer-type="NATURAL"
  data-locale="sv-SE"
  type="module"
  crossorigin="anonymous"
  src="https://payment-static.checkout.prod.resurs.cloud/resurs-payment-widget.js"
></script>

See Script Attributes for a detailed explanation of configuration options. The following example shows the web component tag for the Payment Widget with a payment amount of 5000.

Currency is determined by the Resurs payment methods configured for the store relative to the session ID.

<resurs-payment-method-selector
  token="your-session-token"
  amount="5000"
></resurs-payment-method-selector>

4. Listen for payment method selection

The selection is a standard JavaScript Event. Below is an example.

window.addEventListener("resursPaymentMethodSelected", (event) => {
  const { methodId, type } = event.detail;
  // Use methodId and type with Resurs' Merchant API
});

Full Guide

Everything you need to know about the Resurs Payment Widget and its modular components.

Obtain a Session Token

Before rendering the widget, you must obtain a session token from the Resurs Widget API. See the Backend Integration Guide.

Add the Script Tag

Add the Resurs Payment Widget script tag to your webpage:

<script
  id="resurs-payment-widget"
  data-customer-type="NATURAL"
  data-locale="sv-SE"
  type="module"
  crossorigin="anonymous"
  src="https://payment-static.checkout.int.resurs.cloud/resurs-payment-widget.js"
></script>

Script Attributes

Attribute	Type	Required	Description
`id`	`string`	Yes	Must be `resurs-payment-widget`.
`data-customer-type`	`string`	Yes	Customer type: `NATURAL` or `B2C` (consumers), or `LEGAL` or `B2B` (businesses).
`data-locale`	`string`	Yes	Locale: `sv-SE`, `da-DK`, `no-NO`, `fi-FI`, or `en`.
`type`	`string`	Yes	Must be `module`.

Source URLs

Environment	URL
Production	`https://payment-static.checkout.prod.resurs.cloud/resurs-payment-widget.js`
Integration	`https://payment-static.checkout.int.resurs.cloud/resurs-payment-widget.js`

Rendering Components

The easiest way to use the Resurs Payment Widget is by adding the <resurs-payment-method-selector> web component; however, the script also provides more modular web components for those who need to integrate with their own checkout flow. See Composing with Modular Components.

Interactive Example

`<resurs-payment-method-selector>`

The full payment selector displays all available payment methods for the supplied session token and customer type. Example:

<resurs-payment-method-selector
  token="your-session-token"
  amount="5000"
  customerType="Customer Type"
></resurs-payment-method-selector>

Attributes

Attribute	Type	Required	Description
`amount`	`string`	Yes	Total purchase amount
`token`	`string`	Yes	Session token from the Widget API (`/session` endpoint). Example: `rpmw_3jZ8k9Xy7Vb2N5mQ1rT6W`.
`customerType`	`string`	No	Customer type: `NATURAL` or `B2C` (consumers), or `LEGAL` or `B2B` (businesses).

Features

Automatically fetches and displays all available payment methods.
Renders loading states while fetching data.
Shows error states for failed requests.
Dispatches selection events.
Built-in accessibility support.

Composing with Modular Components

See Composing with Modular Components

Events

`resursPaymentMethodSelected`

When using <resurs-payment-method-selector> or <resurs-payment-method defaultStyling showHeader>, the component emits an event when a payment method is selected or deselected.

When the payment method type is RESURS_PART_PAYMENT_SELECT_NOW, the component always emits an event for a selected part-payment.

When Selected

The component emits a custom event whose detail property is an object with the following structure:

{
  methodId: string,  // UUID of the selected payment method
  type: string       // Payment method type
}

Examples

JavaScript example

window.addEventListener("resursPaymentMethodSelected", (event) => {
  const { methodId, type } = event.detail;
  // Use methodId with Resurs' Merchant API
});

TypeScript example

window.addEventListener(
  "resursPaymentMethodSelected",
  (event: CustomEventInit<object>) => {
    const { methodId, type } = event?.detail;
    // Use methodId with Resurs' Merchant API
  }
);

When “Deselected”

The component will emit a custom event whose detail property is null.

Example

window.addEventListener("resursPaymentMethodSelected", (event) => {
  if (event.detail == null) {
    // A payment method was “deselected”
  }
});

To update the components with new amount or session token, you can update either the amount and token of the component directly, or you can call on the script’s helper function and use that to update everything at once. The update function takes a JavaScript object as its parameter with three optional fields: amount, token, and customerType.

Example

window.resurs.updatePaymentMethods({
  amount: "(optional) amount as string",
  token: "(optional) string that starts with rpmw_",
  customerType: "(optional) NATURAL or LEGAL",
});

Programmatically selecting and deselecting payment methods

There are two functions you may call on to select and deselect items respectively. The selector function window.resurs.dispatchSelected('TYPE', 'paymentMethodId') takes two arguments, a type and a paymentMethodId (UUID). To deselect, you just call window.resurs.dispatchDeselected().

Payment Method Types

The widget supports the following payment method types:

RESURS_INVOICE
RESURS_PART_PAYMENT_SELECT_LATER
RESURS_PART_PAYMENT_SELECT_NOW
RESURS_CARD
RESURS_REVOLVING_CREDIT
RESURS_NEW_REVOLVING_CREDIT

Available payment methods depend on your store configuration, customer type, and the specified amount. The widget only displays applicable methods.

Customization

Styling

The widget provides two styling modes:

Default Styling
Custom Styling

Default Styling

With the defaultStyling attribute, the widget applies Resurs’ branding with outlines and standard spacing:

<resurs-payment-method
  type="RESURS_REVOLVING_CREDIT"
  token="your-session-token"
  amount="5000"
  defaultStyling
  showHeader
  showSubtitle
>
</resurs-payment-method>

Custom Styling

Omit defaultStyling to render without Resurs’ styling, allowing full integration with your design system:

<resurs-payment-method
  type="RESURS_REVOLVING_CREDIT"
  token="your-session-token"
  amount="5000"
>
</resurs-payment-method>

CSS Variable Names

The widget with default styling uses these CSS variables for theming:

:root {
  /** The main accent color  */
  --resurs-checkout-accent-color: light-dark(#8ca101, #a7c080);

  /** Text color */
  --resurs-checkout-text-color: light-dark(#272e33, #d2c5a9);

  /** Background color of the widget */
  --resurs-checkout-background: light-dark(#fff, #212529);

  /** Border Radius, a value between 0-30px or equivalent unit of your choice */
  --resurs-checkout-border-radius: 8px;

  /** Secondary vars */
  /** Header and subtitle color; defaults to primary foreground */
  --resurs-checkout-header-color: light-dark(#272e33, #d2c5a9);

  /** Hyperlink color; defaults to primary foreground */
  --resurs-checkout-link-color: light-dark(#272e33, #d2c5a9);

  /** Radiobutton color; defaults to primary color */
  --resurs-checkout-checkbox-color: light-dark(#8ca101, #a7c080);

  /**Radiobutton dot color; defaults to primary color */
  --resurs-checkout-checkbox-checkmark: light-dark(#8ca101, #a7c080);
}

Performance

The widget automatically caches payment method data.
Only one API request is made per amount change.

Accessibility

The widget includes ARIA labels and keyboard navigation.
Use semantic HTML around the widget.
Ensure sufficient color contrast if customizing styles.

Troubleshooting

Check script tag ID:

<!-- Correct -->
<script id="resurs-payment-widget" ...></script>

<!-- Incorrect -->
<script id="payment-widget" ...></script>

Verify attributes:

data-customer-type must be one of: NATURAL, B2C, LEGAL, B2B.
data-locale must be one of: sv-SE, da-DK, no-NO, fi-FI, en.
token must be a valid session token from the Widget API (format: rpmw_*).

Session or API Errors

If you see errors in the browser console: “Unauthorized” or 401 errors:

Session token is invalid or expired. Obtain a new token as described here.

“Invalid session token” errors:

Verify the session token format (should start with rpmw_).
Ensure the session token hasn’t expired.

Events Not Firing?

For standalone components, ensure header is visible:

<!-- Events work with showHeader or showSubtitle -->
<resurs-payment-method
  type="RESURS_INVOICE"
  amount="5000"
  showHeader
></resurs-payment-method>

<!-- For RESURS_PART_PAYMENT_SELECT_NOW, events fire when selecting installment options -->
<resurs-payment-method
  type="RESURS_PART_PAYMENT_SELECT_NOW"
  amount="5000"
></resurs-payment-method>

Frontend

Backend

API Reference

​Resurs Payment Widget

​Quick Start

​Step 1. Obtain a session token

​Step 2. Add the script tag

​3. Render the payment widget

​4. Listen for payment method selection

​Full Guide

​Obtain a Session Token

​Add the Script Tag

​Script Attributes

​Source URLs

​Rendering Components

​Interactive Example

​<resurs-payment-method-selector>

​Attributes

​Features

​Composing with Modular Components

​Events

​resursPaymentMethodSelected

​When Selected

Examples

​When “Deselected”

Example

​Updating the Widget with new Amount or Session Token

​Example

​Programmatically selecting and deselecting payment methods

​Payment Method Types

​Customization

​Styling

​Default Styling

​Custom Styling

​CSS Variable Names

​Performance

​Accessibility

​Troubleshooting

​Widget Not Rendering?

​Session or API Errors

​Events Not Firing?

Resurs Payment Widget

Quick Start

Step 1. Obtain a session token

Step 2. Add the script tag

3. Render the payment widget

4. Listen for payment method selection

Full Guide

Obtain a Session Token

Add the Script Tag

Script Attributes

Source URLs

Rendering Components

Interactive Example

`<resurs-payment-method-selector>`

Attributes

Features

Composing with Modular Components

Events

`resursPaymentMethodSelected`

When Selected

When “Deselected”

Updating the Widget with new Amount or Session Token

Example

Programmatically selecting and deselecting payment methods

Payment Method Types

Customization

Styling

Default Styling

Custom Styling

CSS Variable Names

Performance

Accessibility

Troubleshooting

Widget Not Rendering?

Session or API Errors

Events Not Firing?