Payment Gateway SDK¶

Use Payment Gateway to offer users embedded payments.

Payment Session¶

Create a payment session with the following mutation query:

Loading GraphiQL...

The token in the response can be now be passed to the payment component.

Payment Component¶

The component bundle is available as an IIFE module namespaced under kronor: The example uses Swish for the payment method, see the table below for a list of supported payment methods.

<script src="https://payment-gateway.kronor.io/iife/index.js"></script>

const $swishPaymentContainer = document.querySelector('#swish-payment-component')
const $swishPaymentStatus = document.querySelector('#swish-payment-status')

kronor.swishPaymentMcom({
  container: $swishPaymentContainer,
  authToken, // session payment token
  useComponentPage: false,
  returnUrl: 'http://localhost',
  onSuccess: () => {
    $swishPaymentStatus.innerHTML = 'Paid succesfully'
  },
  onError: error => {
    $swishPaymentStatus.innerHTML = `Error: ${error}`
  }
})

Or as an ESM module:

const $swishPaymentContainer = document.querySelector('#swish-payment-component')
const $swishPaymentStatus = document.querySelector('#swish-payment-status')

import('https://payment-gateway.kronor.io/esm/index.js')
  .then((kronor) => {
    kronor.swishPaymentMcom({
      container: $swishPaymentContainer,
      authToken, // session payment token
      useComponentPage: false,
      returnUrl: 'http://localhost',
      onSuccess: () => {
        $swishPaymentStatus.innerHTML = 'Paid succesfully'
      },
      onError: error => {
        $swishPaymentStatus.innerHTML = `Error: ${error}`
      }
    })
  });

Specify container to render the component into DOM and pass the session token as authToken.

Once rendered, the component will make a payment request and display a QR code the user can scan with the Swish app. Additionally, if used on mobile, there is a button to launch the Swish app.

After a successful payment the Swish app will redirect the user to returnUrl.

Use onSuccess/onError to handle payment flow events.

Set useComponentPage to true if you would like the user to be redirected to a separate page displaying the component instead of embedding it in your page.

When using a googlePayPayment, set googleMerchantName and googleMerchantId to the values of your google merchant’s merchantName and merchantId. You should see these values on the google business console page.

Supported Payment Methods¶

The table below lists the supported payment methods. Use the respective kronor.* function to render the component for a specific payment method.

Supported Payment Methods¶
Payment Method	Component function name
Swish	kronor.swishPaymentMcom
Bank Transfer	kronor.bankTransferPayment
Credit Card	kronor.creditCardPayment
MobilePay	kronor.mobilePayPayment
Vipps	kronor.vippsPayment
PayPal	kronor.payPalPayment
Przelewy24 (P24)	kronor.p24Payment
PointsPay	kronor.pointspayPayment
Google Pay	kronor.googlePayPayment
ApplePay	kronor.applePayPayment

Payment Component Page¶

A stand-alone page is available that renders the payment component. It can be used e.g. for providing a better experience on mobile devices with smaller screens.

The page can be accessed at:

Payment Component Page URLs¶
Environment	URL
Staging	https://payment-gateway.staging.kronor.io/payment
Production	https://payment-gateway.kronor.io/payment

Provide the following URL parameters when opening the page:

Page URL Parameters¶
Parameter	Description
env	The environment to use the component in: set to `staging` or `prod`
paymentMethod	supported values are `swish`, `creditCard`, `mobilePay`, `vipps`, `paypal`, `bankTransfer`, `p24`, `pointspay`, `googlePay`, `applePay`
token	The Payment Session token
merchantReturnUrl	The URL to redirect to after a completed payment

Saved Cards¶

Card-on-file lets a returning customer pay with a card they have used before, and manage the cards they have stored. It comes in three parts:

the checkout card selector, part of the credit card component, which lists the customer’s stored cards and offers to store the card they are paying with;
kronor.savedCards, a stand-alone list where a customer renames, re-defaults and removes their stored cards, for embedding on an account page;
kronor.defaultSavedCard, a read-only row showing just the card that is currently the default.

Storing a card at checkout¶

Stored cards belong to a customer, identified by a reference you choose. Create the payment session with that reference in additionalData.customerReference, and set saveCardDetails to true to offer the customer the choice of storing the card they are about to pay with:

{
  amount: 1337,
  idempotencyKey: '[randomnumber]',
  merchantReference: 'ref',
  message: 'message!',
  expiresAt: 'now() + 1 day',
  saveCardDetails: true,
  additionalData: {
    customerReference: 'customer-42'
  }
}

The same reference must be used every time that customer pays, since it is what ties the stored cards together. It is opaque to Kronor, so use an identifier that is stable for the customer and not guessable by others.

Then enable the selector on the component:

kronor.creditCardPayment({
  container: $creditCardPaymentContainer,
  authToken, // session payment token
  enableSavedCards: true,
  useComponentPage: false,
  returnUrl: 'http://localhost'
})

With enableSavedCards set, a customer who has stored cards is shown them first, and pays by picking one and entering its security code; entering a new card is always available as one further option in the list. With the flag unset the component behaves exactly as it did before card-on-file existed, and no stored cards are read.

The two settings are independent. saveCardDetails governs only whether this session offers to store a new card, so a session with it left off still lists — and pays with — the cards stored on earlier sessions, just without offering the checkboxes. A card is stored only if the customer ticks the box.

Managing stored cards¶

Both card-management components authenticate as one customer rather than as one payment. They take a token whose role is merchant-customer and whose claims name the merchant and the customer reference, so a token can only ever read and change the cards of the single customer it names. There is no payment involved and no session to create.

To obtain a customerSession token, follow the instructions in saved-cards.html.

kronor.savedCards renders the full list:

const $savedCardsContainer = document.querySelector('#saved-cards-component')

kronor.savedCards({
  container: $savedCardsContainer,
  authToken // customer session token, not a payment session token
})

Cards are listed with the default first, then most recently used. Selecting one opens a dialog where the customer can give it a nickname, make it their default card, or remove it.

kronor.defaultSavedCard renders only the card that is currently the default, as a single read-only row with no editing affordance — for an account overview or an order summary that just needs to show what will be charged:

const $defaultCardContainer = document.querySelector('#default-card-component')

kronor.defaultSavedCard({
  container: $defaultCardContainer,
  authToken // either a customer session token, or a payment session token
})

Card Management Component Options¶
Option	Description
container	The DOM element to render the component into
authToken	A customer token, as described above. Not a payment session token

Both components render nothing but their own markup, inheriting your page’s width, and pick their language from the browser’s, falling back to English where that language is not among the translations Kronor ships.

Behaviour worth knowing when embedding either component:

A customer with no stored cards is shown a short “no saved cards” placeholder, not an empty box.
A card past its expiry month is marked as expired but still listed, so the customer can see why it stopped working and remove it.
Removing a card takes the row away immediately, while the card itself is deleted from the vault a moment later. A list refreshed in that window may still report the card; the components account for this, but your own polling of the API should not treat it as a failed removal.
Nicknames are limited to 20 characters of letters, digits, spaces and _ - ! ' . — the components enforce this before sending, and the API rejects anything else.