Maksu Logo

MaksuPay Buttons SDK JS API

Global

Methods

(async) addPSPPublicKey(pkPem) → {Promise.<void>}

Adds a PSP RSA public key, you can add multiple ones if PSP is in transtion from one to another.
If PSP provides its Public Key as X509 certificate extract public key as follows:
openssl x509 -in MaksuCert.pem -pubkey -noout > MaksuPublic.pem

The key is provided for SDK in PEM format and is converted into a `CryptoKey` instance for signature verification internally.
Parameters:
Name Type Description
pkPem string PSP public key in PEM format (`-----BEGIN PUBLIC KEY----- ... -----END PUBLIC KEY-----`).
Throws:
If the key is invalid, unsupported, or cannot be imported by the Web Crypto API.
Type
Error
Returns:
Resolves when the public key has been successfully imported.
Type
Promise.<void>

initSessionFromMessage(sessResMsg) → {boolean}

Initializes a payment session for Maksu Buttons.
Parameters:
Name Type Description
sessResMsg Object Whole `paySessRes` message received from the Maksu server
(i.e. `{ "message": { ... } }`).
First You need to send from backend a PaySessionRequest
then obtain its respponse (whole body) and pass as this parameter
See:
Throws:
If message parsing or session initialization fails.
Type
Error
Returns:
`true` if session initialization succeeds, `false` otherwise.
Type
boolean

setButtonVariant(v)

Sets the visual variant (style and size) of wallet buttons rendered by the Maksu Buttons SDK. The variant controls: - color theme (black / light) - shape (rounded / square) - size (sm / md / l) If not set explicitly, the SDK uses its default variant.
Parameters:
Name Type Description
v string Button variant identifier. Allowed values: - `"black-round-sm"` - `"black-round-md"` - `"black-round-l"` - `"light-round-sm"` - `"light-round-md"` - `"light-round-l"` - `"black-sm"` - `"black-md"` - `"black-l"` - `"light-sm"` - `"light-md"` - `"light-l"`
Throws:
If `v` is not a string or is not a supported variant.
Type
TypeError
Examples

Black rounded medium buttons

// Match merchant UI theme
vposButtons.setButtonVariant("black-round-md");
// Smaller buttons for compact layouts
vposButtons.setButtonVariant("light-sm");

setResultCallBack(rcf)

Registers a callback invoked when a payment result is available. The callback is called by the Maksu Buttons SDK when the payment flow finishes, either successfully, canceled by the user, or failed due to an error.
Parameters:
Name Type Description
rcf PaymentResultCallback Callback function receiving the final payment result: `(orderId, status, results)`.
Throws:
If `rcf` is not a function.
Type
TypeError

setShipping(shp)

Sets intial shipping information. Shipping consists of a numeric amount and a human-readable label. The amount is validated numerically but may be stored internally as a string, consistent with other monetary fields.
Parameters:
Name Type Description
shp Object Shipping information object.
Properties
Name Type Description
amount number | string Shipping amount in major currency units (e.g. `4.99`).
label string Shipping label (e.g. "Standard shipping", "Express delivery").
Throws:
If the shipping object or its fields are invalid.
Type
TypeError

setShippingCallBack(scf)

Registers a callback used to recalculate shipping based on address changes.
Parameters:
Name Type Description
scf ShippingCallback Callback function invoked when shipping data must be updated.
Throws:
If `scf` is not a function.
Type
TypeError

setSubTotalAmount(am)

Sets the subtotal amount for the current payment.
Parameters:
Name Type Description
am number Subtotal amount in major currency units (e.g. `1.25` for EUR).
Throws:
If the amount is not a valid number.
Type
TypeError

setSubTotalLabel(la)

Sets the subtotal label. This label is used for display purposes only (e.g. UI, receipts) and does not affect payment calculations.
Parameters:
Name Type Description
la string Subtotal label text (e.g. "Subtotal", "Items total").
Throws:
If the label is not a string.
Type
TypeError

setTax(ta)

Sets initial tax information. Tax consists of a numeric amount and a human-readable label. The amount is validated numerically but may be stored internally as a string, consistent with other monetary fields.
Parameters:
Name Type Description
ta Object Tax information object.
Properties
Name Type Description
amount number | string Tax amount in major currency units (e.g. `0.25`).
label string Tax label (e.g. "VAT 20%", "Sales tax").
Throws:
If the tax object or its fields are invalid.
Type
TypeError

setTaxCallBack(tcf)

Registers a callback used to calculate tax information.
Parameters:
Name Type Description
tcf TaxCallback Callback function invoked when tax must be calculated.
Throws:
If `tcf` is not a function.
Type
TypeError

Type Definitions

PaymentResultCallback(orderId, status, results)

Callback invoked by the Maksu Buttons SDK when a payment flow finishes. This callback is called when the payment is successfully completed, canceled by the user, or fails due to an error during processing. The implementation is expected to forward the result payload to the merchant backend for verification, signature validation, persistence, and business processing.
Parameters:
Name Type Description
orderId string Merchant order identifier associated with the payment.
status string Final payment status. Typical values include: - `"AUTORIZED" or "CAPTURED"` — payment completed successfully (provess and validate body) - `"ERROR"` — payment failed due to an error - `"CANCELED"` — user canceled the payment - `"REFUSED"` — payment declined by issuer - `"REFUSED3DS"` — payment declined in 3DS - `"ERROR3DS"` — payment flow erro in3DS
results PaymentResultData Result payload describing the payment outcome. Exactly one of the following cases applies: **Error / cancellation** - `results.error` is present - No cryptographic fields are included **Successful payment** - `results.error` is absent - All cryptographic fields are present: `body`, `signature`, `pkHash`, `senderId`

PaymentResultData

Payment result payload delivered to the merchant. This object acts as a discriminated union: - If `error` is present → payment failed or was canceled - If `error` is absent → payment succeeded and is cryptographically signed
Type:
  • Object
Properties:
Name Type Attributes Description
error Object <optional>
 Error information in case of failure or cancellation.
Properties
Name Type Attributes Description
message string <optional>
 Human-readable error message.
details Object <optional>
 Optional structured error details.
body string <optional>
 Base64-encoded response message body returned by the gateway.
signature string <optional>
 RS256 signature in format `RSA-SHA256;{base64 signature value}`.
pkHash string <optional>
 Base64-encoded public key hash used to verify the signature.
senderId string <optional>
 Sender identifier associated with the signed response.

PaymentResultData

Payment result payload delivered to the merchant. Exactly one of the following is present: - `error` → indicates an error or cancellation - cryptographic response fields (`body`, `signature`, `pkHash`, `senderId`)
Type:
  • Object
Properties:
Name Type Attributes Description
error string <optional>
 Error object wirh properites error a message, optional detials for more info
body string <optional>
 Base64-encoded response message body. if missing definitely a error, cancel case
signature string <optional>
 RS256 signature in format `RSA-SHA256;{base64 signature value}`. if missing definitely a error, cancel case
pkHash string <optional>
 Base64-encoded public key hash used to verify the signature. if missing definitely a error, cancel case
senderId string <optional>
 Sender identifier associated with the signed response. if missing definitely a error, cancel case

ShippingCallback(orderId, countryCode, zipCode, option) → {Object|null}

If shipping is required, you must define this callback. Callback invoked to calculate new shipping information when the shipping address or option changes. Returning `null` indicates that shipping is not available for the given address or option.
Parameters:
Name Type Description
orderId string Merchant order identifier.
countryCode string ISO 3166-1 alpha-2 country code (e.g. "DE", "AT").
zipCode string Postal / ZIP code.
option string Selected shipping option (e.g. "standard", "express").
Throws:
If shipping calculation fails unexpectedly.
Type
Error
Returns:
Shipping information object, or `null` if shipping is not available for the given input.
Type
Object | null

TaxCallback(orderId, countryCode, zipCode, amount) → {Object|null}

Callback invoked to calculate or update tax information. Returning `null` indicates that tax is not applicable for the given order or address.
Parameters:
Name Type Description
orderId string Merchant order identifier.
countryCode string ISO 3166-1 alpha-2 country code (e.g. "DE", "AT").
zipCode string Postal / ZIP code.
amount number | string Order amount (subtotal) in major currency units.
Throws:
If tax calculation fails unexpectedly.
Type
Error
Returns:
Tax information object, or `null` if tax is not applicable.
Type
Object | null