4. Add hosted fields

<div id="fields"></div>

Initialize the hosted fields

<script>
  epay
    .setSessionId("<SESSION_ID>")
    .setSessionKey("<SESSION_KEY>")
    .setCallbacks({
      clientReady: clientReadyCallback,
      invalidSession: invalidSessionCallback,
      challengeIssued: challengeIssuedCallback,
      transactionAccepted: transactionAcceptedCallback,
      transactionDeclined: transactionDeclinedCallback,
      feeUpdated: feeUpdatedCallback,
      clientRedirect: clientRedirectCallback,
      invalidInput: invalidInputCallback,
      inputValidity: inputValidityCallback,
      inputSubmit: inputSubmitCallback,
      sessionExpired: sessionExpiredCallback,
      error: errorCallback,
    })
    .init();

  epay.mountFields("fields", {
    theme: "default",
    language: "da", // Optional parameter ["da", "en", "sv", "no"]
    variables: {
      colorText: "#2e3033",
    },
  });
</script>

Cardholder name

By default, there is no input field for the cardholder name. If you need to collect this information, you can enable it when mounting the fields by passing the fields object.

A prefilled cardholder name can be given by sending the fields.name.value parameter.

epay.mountFields("fields", {
  theme: "default",
  fields: {
    name: { enabled: true, value: "" },
  },
});

Styling

Merchants can style the hosted fields to match their branding.

To stay compliant and protect cardholder data the styling options follow very strict validation requirements. ePay only allow simple styling rules such as color codes, css unit sizing and fonts.

Themes

Name	Description
default	The default ePay inspired styling.

Variables

General

Variable	Description
colorText	The font color of text, used for labels and input content.
borderRadius	The border radius for inputs and the window.
borderColor	The default border color for inputs and the window.
fontFamily	The font used for labels, input content, and placeholders.

Spacing between the input fields (horizontal and vertical)

Variable	Description
gridColumnSpacing	Horizontal spacing between input fields in the grid layout.
gridRowSpacing	Vertical spacing between input fields in the grid layout.
gridTemplateColumns	Defines the column structure of the grid layout.

Displaying icons and brands

Variable	Description
iconDisplay	Controls the visibility of icons in the fields (e.g., block or none).
cardBrandDisplay	Controls the visibility of card brand icons (e.g., block or none).

Label elements

Variable	Description
labelColor	The font color for labels.
labelFontSize	The font size for labels.
labelFontWeight	The font weight for labels.
labelMarginBottom	The spacing below labels.

Input elements

Variable	Description
inputColor	The font color for user input.
inputBorderRadius	The border radius for input fields.
inputBorderColor	The border color for input fields.
inputFocusBorderColor	The border color when an input field is in focus.
inputFontSize	The font size for input fields.
inputPadding	The padding inside input fields.
inputPlaceholderColor	The font color for placeholder text in input fields.
inputBackgroundColor	The background color for input fields.
inputBoxShadow	The box shadow for input fields.
inputFocusBoxShadow	The box shadow for input fields when they are in focus.
windowPadding	The padding around the window containing the hosted fields.
windowBackgroundColor	The background color of the window containing the hosted fields.
windowBorderStyle	The border style of the window containing the hosted fields.
windowBorderRadius	The border radius of the window containing the hosted fields.
windowBorderColor	The border color of the window containing the hosted fields.

Color specific

Variable	Description
colorDanger	The color used to indicate problems or input validation errors.
colorPrimary	The primary theme color for the hosted fields.

JavaScript events

The javascript functions below can be set to receive notifications from the client with information of the current transaction state.

Name	Description
clientReady	Dispatched once the client has verified the session id and secret.
invalidSession	Dispatched if the client cannot verify the session id and secret.
challengeIssued	Dispatched before a client redirect to the challenge page. Return false to cancel follow-up events.
transactionAccepted	Dispatched on transaction success. Funds are guaranteed.
transactionDeclined	Dispatched on transaction rejection.
feeUpdated	Dispatched when the transaction fee is calculated
clientRedirect	Dispatched before any client redirect. Return false to cancel redirect behaviour.
invalidInput	Dispatched if the payment method input cannot be used for processing.
inputValidity	Dispatched on end user payment method input during validity checks.
inputSubmit	Dispatched on user submit by submitting the fields directly within the fields.
sessionExpired	Dispatched if the session has expired. Return false to cancel follow-up events.
error	Dispatched on any error not covered by other events.

info

All events have a default handler that makes sure the payment is processed as expected.

If merchants wants to modify this flow, like handling redirects differently, they can register a handler with their own logic and return false to disable the default handler.

Do note that ePay cannot guarantee correct handling of events in this case.

Event Data

Each javascript function takes in one parameter, which is an object of data.

Dynamic Amount

To set the transaction amount when dynamicAmount is true, use the client method epay.setPaymentOptions({amount: 100}).

When directly integrating hosted fields with dynamic amounts enabled, merchants must allow end users to select their own payment amount.

Merchants can utilize pre-auth webhooks to accept or reject the selected transaction amount in case it falls outside acceptable ranges.

info

Most merchants are advised against using dynamic amounts due to increased integration complexity.

This requires server-side verification of the selected amount during the pre-authorization webhook. For simplicity, most merchants should have customers select the payment amount before initializing the payment session at ePay.