Web Integration

You can integrate Straumur's client-side library which meets the requirements for most online payment integrations.

With component, you can render a list of available payment methods anywhere on your website and collect payment details from your shoppers.

Requirements

Before you begin to integrate, make sure you have followed the Basic Session Request guide.

Setting up your Frontend

Recommended Version

The recommended version of straumur-web-component is 1.0.0. This version includes the latest features and bug fixes.

Using the NPM Package

Use the Straumur Web npm package:

• npm install straumur-web-component@"^1.0.0" --save

• Import Straumur Web into your application:

  import { StraumurCheckout } from "straumur-web-component";

Embed the Script into your HTML

Work in progress! 👷🏻 ⚒️

In case you want a pre-released version of script, contact our support.

DOM Element for component

Create a DOM container element on your checkout page where you want to render component and assign it a descriptive id.

<div id="component-container"></div>

note

If you are utilizing JavaScript frameworks like Vue or React, ensure that you use references rather than selectors and avoid re-rendering the DOM element.

Setup component

Define a global configuration object to initialize the StraumurCheckout instance. This object should include configuration settings and event handlers.

Initialize the Payment Component Example

const paymentConfiguration = {
    environment: "test", // Change to 'live' for the live environment.
    // Use sessionId from /embeddedcheckout/session response
    sessionId: "ftsdre3h...e5h5as2q4",
    onPaymentCompleted: () => {
        console.info("onPaymentCompleted");
    },
    onPaymentFailed: () => {
        console.info("onPaymentFailed");
    },
};

const checkout = new StraumurCheckout(paymentConfiguration);

checkout.mount("#component-container");

Payment Component Parameters

Parameter	Description
environment	Use test for staging/testing environment. When you are ready to accept live payments, change to live.
sessionId	The payment sessionId identifier from your call to /embeddedcheckout/session.
onPaymentCompleted()	Create an event handler, called when the payment is completed.
onPaymentFailed()	Create an event handler, called when the payment failed.
locale	The language used in the component. Available values are: is and en. By default, this is the culture from your /embeddedcheckout/session request.
placeholders	The object used to override default placeholder values within the payment fields. For complete list of placeholders to override check our types on NPM: https://www.npmjs.com/package/straumur-web-component?activeTab=code under /dist folder.
localizations	The object used to override default localizations values of the component. For complete list of localizations to override check our types on NPM: https://www.npmjs.com/package/straumur-web-component?activeTab=code under /dist folder.
instantPayments	Defines which instant payment wallet buttons to display and in what order. Accepts googlepay and/or applepay.

Locale

const paymentConfiguration = {
    environment: "test", // Change to 'live' for the live environment.
    // Use sessionId from /embeddedcheckout/session response
    sessionId: "ftsdre3h...e5h5as2q4",
    onPaymentCompleted: () => {
        console.info("onPaymentCompleted");
    },
    onPaymentFailed: () => {
        console.info("onPaymentFailed");
    },
    locale: "en",
};

Placeholders

const paymentConfiguration = {
    environment: "test", // Change to 'live' for the live environment.
    // Use sessionId from /embeddedcheckout/session response
    sessionId: "ftsdre3h...e5h5as2q4",
    onPaymentCompleted: () => {
        console.info("onPaymentCompleted");
    },
    onPaymentFailed: () => {
        console.info("onPaymentFailed");
    },
    placeholders: {
      cardNumber: "1234 5678 9012 3456",
    },
};

Localization

const paymentConfiguration = {
    environment: "test", // Change to 'live' for the live environment.
    // Use sessionId from /embeddedcheckout/session response
    sessionId: "ftsdre3h...e5h5as2q4",
    onPaymentCompleted: () => {
        console.info("onPaymentCompleted");
    },
    onPaymentFailed: () => {
        console.info("onPaymentFailed");
    },
    localizations: {
      "en-US": {
        "cards.title": "Card Information",
      }
    }
};

Instant payments

const paymentConfiguration = {
    environment: "test", // Change to 'live' for the live environment.
    // Use sessionId from /embeddedcheckout/session response
    sessionId: "ftsdre3h...e5h5as2q4",
    onPaymentCompleted: () => {
        console.info("onPaymentCompleted");
    },
    onPaymentFailed: () => {
        console.info("onPaymentFailed");
    },
    instantPayments: ["applepay", "googlepay"],
};

Update config

const paymentConfiguration = {
    environment: "test", // Change to 'live' for the live environment.
    // Use sessionId from /embeddedcheckout/session response
    sessionId: "ftsdre3h...e5h5as2q4",
    onPaymentCompleted: () => {
        console.info("onPaymentCompleted");
    },
    onPaymentFailed: () => {
        console.info("onPaymentFailed");
    },
};

const paymentCheckout = new StraumurCheckout(paymentConfiguration);

// ...
// Mount the checkout component into container, either through reference or DOM selector depending if you are using some JavaScript frameworks or not.
paymentCheckout.mount("#paymentContainer");

// ...
// This will just re-render with the same/initial configuration.
paymentCheckout.updateConfig();

// ...
// This will re-render with the new configuration (in this case, locale/language).
paymentCheckout.updateConfig({ locale: "en-US" });

// ...
// This will re-render with the new configuration (in this case, locale/language and custom localization/translation).
paymentCheckout.updateConfig({ locale: "en-US", customLocalizations: { "en-US": { "cards.title": "My Card Title" } } });

Payment Flow

When component is created and mounted, the shopper uses the interface to finalize the payment. Component manages the entire payment process you set up upfront.

Payment Outcome

Once the component has processed the payment, you should inform the shopper of the payment status. Straumur will notify you of the payment result via a webhook. A declined attempt does not end the session — the shopper can try again, and each attempt sends its own Authorization event. Expect one or more success: "false" events before a successful one; see One checkout, several Authorization events.

Payment Result Before Webhook

To retrieve the payment result before receiving the webhook notification, follow these steps:

1. Obtain the checkoutReference from the /embeddedcheckout response.
2. Check the current payment status by following the Checkout Status Request.

Test Refusal Reason

Work in progress! 👷🏻 ⚒️

Apple Pay and Google Pay

If you wish to include Apple Pay and Google Pay as payment methods on your website, please contact our support at developers@straumur.is