Maksu VPOSClient JavaScript SDK : Class: VPOSClient

new VPOSClient()

VPOSClient provides secure communication between the merchant page and embedded VPOS iframes (Card Encryption, Google Pay, Apple Pay). It handles: - Encrypted card data retrieval - Wallet session initialization - postMessage communication - Callback dispatching

Methods

getOrigin(iframe) → {string}

Builds origin string from Location object.

Parameters:

Name	Type	Description
`iframe`	frame	Browser iframe element object

Returns:

Origin string (protocol://hostname:port)

Type: string

initWalletSession(orderInfo, options, callbackFunction1)

Initializes wallet (Google Pay / Apple Pay) session.

Parameters:

Name Type Description

orderInfo

Object

Order information

Properties

Name	Type	Description
`orderId`	string	Merchant order ID
`currency`	string	Currency code (EUR, USD, etc.)
`orderTotal`	string \| number	Order total amount

options Object Wallet configuration options

callbackFunction1 function Callback invoked when wallet flow ends

Example

vposClient.initWalletSession(
  { orderId: "123", currency: "EUR", orderTotal: "10.00" },
  { environment: "TEST" },
  function(result){
    console.log("Wallet result:", result);
  }
);

(static) clearCardDataInIframe() → {boolean}

Clears card data inside the iframe.

Returns:

true if request sent

Type: boolean

(static) create3DS2Data() → {Object}

Creates and returns a 3DS 2.x data browser parameters This method collects browser and device information required for EMV 3-D Secure 2.x, such as screen size, color depth, language, timezone, and JavaScript support, and formats it into a structure suitable for submission to the 3DS Server.

Returns:

A 3DS2 data object containing device and browser attributes used for risk assessment and authentication.

Type: Object

Example

const threeDSData = vposClient.create3DS2Data();
sendAuthRequest({ threeDSData });
these properties are to be send in AuthenticationReques attributes while
attribute name is property name and attribute value is poperty value

(static) getEncryptedCardDataFromIframe(cvvRequired, nameRequired, callbackFunctionCardData)

Requests encrypted card data from the iframe.

Parameters:

Name	Type	Description
`cvvRequired`	boolean	Whether CVV is mandatory
`nameRequired`	boolean	Whether cardholder name is mandatory
`callbackFunctionCardData`	function	Callback receiving encrypted card result

Example

vposClient.getEncryptedCardDataFromIframe(true, true, function(result){
  if(result.cardEncData){
    console.log("Encrypted card:", result.cardEncData);
  } else {
    console.error(result.errorCardEncData);
  }
});

(static) handle3DSMethod(tdsContent, continueAuthenticationCallBack)

Handles the 3DS Method execution step in the 3D Secure authentication flow. This method processes the provided 3DS Method content (usually HTML or an iframe payload) and invokes the given callback once the method execution is completed or times out.

Parameters:

Name	Type	Description
`tdsContent`	string	The 3DS Method content returned by service in first authentication response Typically an HTML snippet that must be rendered, it will be injected to dom, to allow the issuer to collect device information. Once processed callbackfunction to continue is called (typ. up to 5 seconds)
`continueAuthenticationCallBack`	function	Callback function invoked after the 3DS Method step is finished. This continues the authentication flow. The callback receives no parameters.

Example

vposClient.handle3DSMethod(tdsHtmlContent, function () {
  console.log("3DS Method completed, continuing authentication...");
  continueAuthenticationFlow();
});

(static) initCSEIframe(cvvRequired, nameRequired) → {void}

Initializes the Card Security iframe with CSE used for secure card data entry. This method configures cse iframe to validate name and cvv requirements and establisches merchant origin. The iframe isolates sensitive card input fields from the merchant page and enables PCI-compliant data capture.

Parameters:

Name	Type	Description
`cvvRequired`	boolean	Indicates whether the CVV (Card Verification Value) is required for submission.
`nameRequired`	boolean	Indicates whether the cardholder name field required for submission.

Returns:

Type: void

Examples

// Initialize iframe with CVV and cardholder name fields enabled
vposClient.initCSEIframe(true, true);

// Initialize iframe without cardholder name field
vposClient.initCSEIframe(true, false);

(static) setText(key, text) → {void}

Sets or overrides a localized UI text value used by the payment interface. This method updates the internal text dictionary for a given key and allows dynamic customization of button labels, messages, and other UI strings at runtime.

Parameters:

Name	Type	Description
`key`	string	Text identifier (for example: `btns.cancel`, `authenticate.with.bank`).
`text`	string	The localized text value to associate with the given key.

Returns:

Type: void

Examples

// Override Cancel button label
vposClient.setText("btns.cancel", "Cancel payment");

// Set estonian localization
vposClient.setText("btns.cancel", "Loobu");
vposClient.setText("authenticate.with.bank", "Tuvasta end pangas");
vposClient.setText("btns.close", "Sulge");

(static) start3DSChallengeFlow(authRes, challengeCallBackFunction, iframed) → {void}

Starts the 3D Secure Challenge flow based on the authentication result. Opens overlayed challenge dialog and blocks remaining of page until completed or canceled. This method initiates the Challenge (CReq/CRes) step by rendering the ACS challenge UI either in an iframe or as a full-page redirect, depending on the `iframed` flag. When the challenge is completed, the provided callback function is invoked to continue the payment authorization flow.

Parameters:

Name	Type	Description
`authRes`	Object	Authentication response returned from the Service. Contains challenge data such as ACS URL, CReq payload, and transaction identifiers.
`challengeCallBackFunction`	function	Callback function invoked when the challenge flow is completed or terminated. The callback receives the final challenge result object with status SUCCESS, FAIL, CANCELED.
`iframed`	boolean	If true, the challenge is rendered inside an embedded iframe (default). If false, the user is redirected or a full-page challenge UI is displayed. Then the callback handling is by caller supplied callBackURL

Returns:

Type: void

Example

vposClient.start3DSChallengeFlow(authResponse, function (challengeResult) {
  console.log("3DS Challenge finished:", challengeResult);
  if (challengeResult.status=="SUCCESS")
  {
	    continueAuthorization(challengeResult);
  }
}, true);