Checkout SDK for branding

The Checkout SDK is a browser-side JavaScript module that powers a fully custom-branded checkout page hosted on the Payment Platform. Merchants who need more visual control than the admin-panel theming of the standard HPP page can build their own HTML / CSS / JavaScript form, drop in the SDK, and submit the project for review and hosting.

The SDK takes care of the payment session, secure card-data handling, the redirect flow for 3D-Secure, and Apple Pay / Google Pay buttons. Because the form is hosted on the Payment Platform, the merchant retains the PCI scope reduction of an HPP integration.

warning

Currently, only payment forms with CARD, ApplePay, and GooglePay payment methods are supported (where card data is entered on the form itself). P2P and debit payment forms are not supported.

Form project requirements

When developing your own payment page or adapting an existing one, the following conditions must be met:

Technology stack: HTML / CSS / JavaScript.
Project folder structure:
- /img
- /style
- /js
- / (project root for the HTML entry point)

Quickstart

1. Load the SDK

Include the pay-session.js module in your payment page:

<script src="https://{{CHECKOUT_URL}}/sdk/pay-session.js"></script>

2. Initialize a session

Create a new PaySession instance, passing the id of the <form> element and, optionally, on-the-fly input validation. Then call begin():

<script>
    const session = new PaySession({ formName: "paymentForm", validateOnInput: true });
    session.begin();
</script>

3. Link your form inputs

Inside the <form> tag, the SDK only interacts with <input> elements whose id matches one of the values below.

Field	`id`
Payment card number	`payer_card`
CVV code	`payer_cvv`
Expiry date	`payer_expiryDate`
Payer name	`payer_name`
ZIP code	`payer_zip`
Payer city	`payer_city`
Payer phone number	`payer_phone`
Payer email	`payer_email`
Payer state	`payer_state`
Payer address	`payer_address`
Payer country	`payer_country`

warning

At a minimum, the form must contain inputs with these IDs: payer_card, payer_cvv, payer_expiryDate, payer_name.

Constructor parameters

Parameter	Type	Required	Default	Description
`formName`	string	yes	-	`id` of the `<form>` element the SDK should bind to.
`validateOnInput`	boolean	no	`false`	When `true`, validates each linked input on the fly and emits `onInputValidation` events.
`sandbox`	boolean	no	`false`	When `true`, runs the SDK in sandbox mode with emulated backend responses.

Session API

The SDK exposes a set of methods for reading session context (order, billing address, card tokens, customer info, and reference data) and for selecting a stored card token.

Order and session info

`getOrderInfo()`

Returns the current order:

{ number: "111-222", amount: "10.00", currency: "USD", description: "Important gift" }

`getSessionExpiry()`

Returns the checkout session expiry date/time in Unix-time format:

1711378966

`getSessionState()`

Returns the current session status. Possible values: complete, redirect, waiting, decline. Example:

"decline"

`getDeclinesMax()`

Returns the configured limit on the number of declines on the payment page. The merchant defines this value in the Authentication request; after the limit is reached the customer is automatically redirected to cancel_url. Example:

`getCancelUrl()`

Returns the cancel_url passed by the merchant in the Authentication request. Example:

"https://example.domain.com/cancel"

`getBillingAddress()`

Returns the billing_address object from the merchant's Authentication request. Properties may be empty if the corresponding information was not provided. Example:

{ address: "Moore Building", city: "Los Angeles", country: "US", phone: "12345678", state: "", zip: "12345" }

`getCustomerInfo()`

Returns customer data:

{
    name: "John Doe",
    email: "[email protected]",
    birth_date: "1970-02-17"
}

`getCustomData()`

Returns the object passed in the custom_data parameter of the Authentication request.

Example value sent in the request:

"custom_data": {
    "provider": "akurateco",
    "brand": "visa",
    "domain": "en"
}

Returned by the method:

{ "brand": "visa", "domain": "en", "provider": "akurateco" }

`getUrlTarget()`

Returns the url_target value specified in the Authentication request. If no value was provided, an empty value is returned. Example:

"_top"

Card tokens

`getCardTokens()`

Returns an array of available stored payment card tokens:

[
    {
        "token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "last": "1111",
        "month": "01",
        "year": "2025",
        "brand": "visa",
        "cardholder_name": "John Doe"
    }
]

`setCardToken(token: string)`

Selects a specific token for the payment process. Stored card data in the token takes priority over card data entered in the form fields.

`getActiveCardToken()`

Returns the active token string if one was set via setCardToken, otherwise an empty value. Example:

"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

`clearCardToken()`

Deselects the active token. Call this when the customer wants to revert from a stored token to entering card data directly in the form.

Reference data

`getAvailableBrands()`

Returns the list of available alternative brands for the current session:

["googlepay", "applepay"]

`getCountries()`

Returns the full list of countries with regions:

[
    {
        regions: null,
        value: "AF",
        text: "Afghanistan"
    },
    {
        regions: [{ value: "ACT", text: "Australian Capital Territory" }, ...],
        value: "AU",
        text: "Australia"
    }
]

Events

The SDK exposes a set of event listeners that fire over the lifetime of a session. Event handling is optional.

Event	When it fires	Returns
`onFormReady`	After the current session has been fetched.	-
`onSuccess`	When the payment processing response is `completed`, or when checking the session status returns `completed`.	`{ successUrl: string }`
`onDecline`	When the payment processing response is `declined`, or when checking the session status returns `declined`.	`{ message: string }`
`onUndefined`	When an unsupported case is received during payment or status check.	-
`onInputValidation`	On per-input validation errors (when `validateOnInput: true`) or on form submission.	`{ result: string, inputId: string }`
`handleError`	After an error occurs when sending the payment processing request.	error object

Examples

onFormReady

session.onFormReady = function () {
    document.querySelector(".form-wrapper").classList.add("show");
}

onSuccess

session.onSuccess = function (event) {
    location.href = event.successUrl;
}

onDecline

session.onDecline = function (event) {
    document.querySelector(".decline-message").innerText = event.message;
}

onUndefined

session.onUndefined = function (event) {
    document.querySelector(".decline-message").innerText = "Unsupported case occurred. To check the status of your payment, please contact support.";
};

onInputValidation

session.onInputValidation = function (event) {
    if (event.result === "error") {
        document.getElementById(event.inputId)?.classList.add("text-field--error");
        document.getElementById(event.inputId + "Error")?.classList.add("display-error");
    } else {
        document.getElementById(event.inputId)?.classList.remove("text-field--error");
        document.getElementById(event.inputId + "Error")?.classList.remove("display-error");
    }
};

Sandbox mode

When the sandbox parameter is set to true on the PaySession constructor, the SDK runs against an emulated backend instead of a live processing session. Useful during local form development.

<script>
    const session = new PaySession({
        formName: "paymentForm",
        validateOnInput: true, // optional
        sandbox: true          // optional, default: false
    });
    session.begin();
</script>

In sandbox mode:

Backend payment data is emulated (payment info, billing address, customer info, success/decline URLs, example token).
Emulation delay is 2 seconds.
A banner Sandbox mode enabled is displayed at the top of the page with z-index: 1000 for 4 seconds.
The expiry-date input (id="payer_expiryDate") drives the simulated outcome:

Expiry value	Outcome
`01/99`	Successful payment (triggers `onSuccess`)
`02/99`	Declined payment (triggers `onDecline`)
any other value	Console error: `Wrong expiry year for sandbox mode!`

Apple Pay

Create a container with id="applepay-container" and a child element for the Apple Pay button.

Container and button styles

<div id="applepay-container">
    <div class="applepay-button"></div>
</div>

@supports (-webkit-appearance: -apple-pay-button) {
    .applepay-button {
        display: block;
        width: 100%;
        height: 45px;
        -webkit-appearance: -apple-pay-button;
        -apple-pay-button-type: plain;
        -apple-pay-button-style: black;
        overflow: hidden;
    }
}

Add a click handler to the button:

<div id="applepay-container">
    <div class="applepay-button" onclick="handleApplePayClick()"></div>
</div>

Google Pay

Create a container with id="googlepay-container":

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

Customizing the button

Call setGooglePayButtonConfiguration() with a configuration object. Any fields you omit fall back to the defaults below.

const googlePayButtonConfig = {
    buttonColor: "white",
    buttonType: "short",
    buttonRadius: 8,
    buttonLocale: "uk",
    buttonSizeMode: "static",
};

session.setGooglePayButtonConfiguration(googlePayButtonConfig);

The configuration parameters mirror Google's ButtonOptions.

Default configuration

GOOGLE_PAY_BUTTON_CONFIGURATION_DEFAULT = {
    buttonColor: "default",
    buttonType: "buy",
    buttonRadius: 4,
    buttonLocale: "en",
    buttonSizeMode: "fill",
};

Submitting the form for review

Once your payment form is built, send the project archive (source code and all referenced assets) to your account manager for review, security testing, and hosting on the Payment Platform.

The hosted form is assigned a unique identifier. Pass it as form_id in the Checkout Authentication request so the platform serves your form to customers:

{ "form_id": "xxxxx-xxxxx-xxxxx" }

Example project

A complete example payment-form project is available for download: sdk-form-example.zip.

Form project requirements​

Quickstart​

1. Load the SDK​

2. Initialize a session​

3. Link your form inputs​

Constructor parameters​

Session API​

Order and session info​

getOrderInfo()​

getSessionExpiry()​

getSessionState()​

getDeclinesMax()​

getCancelUrl()​

getBillingAddress()​

getCustomerInfo()​

getCustomData()​

getUrlTarget()​

Card tokens​

getCardTokens()​

setCardToken(token: string)​

getActiveCardToken()​

clearCardToken()​

Reference data​

getAvailableBrands()​

getCountries()​

Events​

Examples​

Sandbox mode​

Apple Pay​

Google Pay​

Customizing the button​

Default configuration​

Submitting the form for review​

Example project​

See also​