Dintero Checkout JavaScript SDK for frontend applications

Use this SDK in your frontend application to

• embed an existing Dintero Checkout payment session in an iframe on your website
• redirect the end user to the full page version of the Dintero Checkout for an existing payment session

Note that this SDK is for redirecting or embedding existing payment sessions. You cannot use this SDK to send requests to the Checkout API or to crate new payment sessions.

Learn more about the Dintero Checkout at docs.dintero.com

Before you start

We cannot guarantee the delivery of events from the embedded checkout to the SDK client runtime. The sessions machine-to-machine callback_url will be delivered at least once. Read more about the callback_url parameter in our api spec.

For payments on devices with the Vipps app installed, after payment is completed in the Vipps app, the end user will be returned to the browser where the return_url on the payment is opened in a new browser tab leaving the site that has the embedded checkout still open in a background browser tab on the device. In this case the SDK cannot guarantee that the handlers for onPaymentAuthorized or onPaymentError will be called.

If no custom handler are added for onPaymentError, onPaymentAuthorized and onPaymentCanceled the SDK will redirect the user to the return_url in the payment session.

Installation

NPM package

npm install @dintero/checkout-web-sdk

Using the SDK for an embedded checkout

The Dintero Checkout will be added to the <div id="checkout-container"></div> DOM-node.

Minimal example

When payment is completed, the SDK will redirect the end user to the return_url defined in the payment session.

<script type="text/javascript">
    const container = document.getElementById("checkout-container");

    dintero.embed({
        container,
        sid: "T11223344.<short-uuid>",
    });
</script>

Full inline HTML JavaScript example

The checkout sdk will add a polyfill for promises if the browser does not support promises natively.

<script type="text/javascript">
    const container = document.getElementById("checkout-container");

    dintero
        .embed({
            container,
            sid: "T11223344.<short-uuid>",
            popOut: false, // optional parameter to enable pop out mode
            language: "no", // optional parameter, an ISO 639-1 two-letter language code
            debug: false, // optional parameter, log SDK activity to the console, do not use for production
            onSession: function (event, checkout) {
                console.log("session", event.session);
            },
            onPayment: function (event, checkout) {
                console.log("transaction_id", event.transaction_id);
                console.log("href", event.href);
                checkout.destroy();
            },
            onPaymentError: function (event, checkout) {
                console.log("href", event.href);
                checkout.destroy();
            },
            onSessionCancel: function (event, checkout) {
                console.log("href", event.href);
                checkout.destroy();
            },
            onSessionNotFound: function (event, checkout) {
                console.log("session not found (expired)", event.type);
                checkout.destroy();
            },
            onSessionLocked: function (event, checkout, callback) {
                console.log("pay_lock_id", event.pay_lock_id);
                callback(); // refresh session
            },
            onSessionLockFailed: function (event, checkout) {
                console.log("session lock failed");
            },
            onActivePaymentType: function (event, checkout) {
                console.log(
                    "payment product type selected",
                    event.payment_product_type,
                );
            },
            onAddressCallback: function (event, checkout, callback) {
                console.log("address callback to handle express session address updates", event.session);
                callback({
                    success: true,
                    error: undefined,
                });
            },
            onValidateSession: function (event, checkout, callback) {
                console.log("validating session", event.session);
                callback({
                    success: true,
                    clientValidationError: undefined,
                });
            },
            onAgeVerificationStarted: function (event, checkout) {
                console.log("age verification started");
            },
            onAgeVerificationFailed: function (event, checkout) {
                console.log("age verification failed", event.error);
            },
            onAgeVerificationEnded: function (event, checkout) {
                console.log("age verification ended", event.result);
            },
        })
        .then(function (checkout) {
            console.log("checkout", checkout);
        });
</script>

Typescript example

import {
    embed,
    SessionLoaded,
    SessionUpdated,
    SessionPayment,
    SessionPaymentError,
    SessionCancel,
    SessionNotFound,
    AgeVerificationStarted,
    AgeVerificationFailed,
    AgeVerificationEnded,
} from "@dintero/checkout-web-sdk";

const container = document.getElementById("checkout-container");

const checkout = await embed({
    container,
    sid: "T11223344.<short-uuid>",
    popOut: false, // optional parameter to enable pop out mode
    language: "no", // optional parameter, an ISO 639-1 two-letter language code
    debug: false, // optional parameter, log SDK activity to the console, never in production
    onSession: (event: SessionLoaded | SessionUpdated) => {
        console.log("session", event.session);
    },
    onPayment: (
        event: SessionPaymentAuthorized | SessionPaymentOnHold,
        checkout,
    ) => {
        console.log("transaction_id", event.transaction_id);
        console.log("href", event.href);
        checkout.destroy();
    },
    onPaymentError: (event: SessionPaymentError, checkout) => {
        console.log("href", event.href);
        checkout.destroy();
    },
    onSessionCancel: (event: SessionCancel, checkout) => {
        console.log("href", event.href);
        checkout.destroy();
    },
    onSessionNotFound: (event: SessionNotFound, checkout) => {
        console.log("session not found (expired)", event.type);
        checkout.destroy();
    },
    onSessionLocked: (event: SessionLocked, checkout, callback) => {
        console.log("pay_lock_id", event.pay_lock_id);
        callback(); // refresh session
    },
    onSessionLockFailed: (event: SessionLockFailed, checkout) => {
        console.log("session lock failed");
    },
    onActivePaymentType: function (event: ActivePaymentProductType, checkout) {
        console.log(
            "payment product type selected",
            event.payment_product_type,
        );
    },
    onAddressCallback: function (event: AddressCallback, checkout, callback) {
        console.log("address callback to handle express session address updates", event.session);
        callback({
            success: true,
            error: undefined,
        });
    },
    onValidateSession: function (event: ValidateSession, checkout, callback) {
        console.log("validating session", event.session);
        callback({
            success: true,
            clientValidationError: undefined,
        });
    },
    onAgeVerificationStarted: (event: AgeVerificationStarted, checkout) => {
        console.log("age verification started");
    },
    onAgeVerificationFailed: (event: AgeVerificationFailed, checkout) => {
        console.log("age verification failed", event.error);
    },
    onAgeVerificationEnded: (event: AgeVerificationEnded, checkout) => {
        console.log("age verification ended", event.result);
    },
});

Setting payment product type

The payment product type can be set with the returned setActivePaymentProductType()function when embedding the checkout.

Select "vipps" payment product type:

checkout.setActivePaymentProductType("vipps");

Resetting selection (so no option is selected in the checkout):

checkout.setActivePaymentProductType();

Handling Checkout Express address updates using the onAddressCallback

If the onAddressCallback is provided the checkout will not perform the machine to machine address update callback defined in the payment session object at express.shipping_address_callback_url. Instead the SDK runtime has to handle the address update flow.

The onAddressCallback function is invoked when an end user submits their address details (the shipping and billing addresses) in an embedded Checkout Express session. The callback function is invoked with an updated session that is not yet persisted in the Dintero backend. The checkout will be locked and payment will be paused until the provided callback function is called, or checkout.submitAddressCallbackResult is called with the result.

When onAddressCallback is invoked you will have to perform a server-to-server session update with shipping options or other details that have changed. Once the session has been updated you need to call the provided callback function with a result.

When session has been updated successfully, return a successful result:

{
    success: true;
}

If the session update failed, return the result with an error message:

{
   success: false,
   error: "<reason for session update failure>"
}

Example implementation:

onAddressCallback: function(event, checkout, callback) {
     // Perform a server-to-server session update
     getShippingOptionsForAddressAndUpdateSession(event.session).then(() => {
        callback({
            success: true,
        });
     }).catch((err) => {
        callback({
            success: false,
            error: toErrorMessage(err), 
        });
     });
},

Note: When implementing the onAddressCallback, there is no need to manually lock the session and refresh it. The checkout will automatically lock the payment and refresh the session when the callback function is used to return a result.

Updating an Checkout Express-session

To update an existing Checkout Express-session, follow these steps:

1. Lock the session with the SDK
2. Perform a server-to-server session update
3. Refresh the session with the SDK

Locking the session

Call lockSession on the checkout object:

checkout
    .lockSession()
    .then(function (sessionLockedEvent) {
        // initiate server side session update and then refresh the session
    })
    .catch(function (sessionLockFailedEvent) {
        // handle failure to lock
    });

lockSession() returns a promise that is resolved when the SessionLocked event is received from the checkout or rejected if the SessionLockFailed event is received.

When the session is successfully locked, you'll get a callback at onSessionLocked. If locking the session fails, there will be a callback at onSessionLockFailed.

While the session is locked, all editing and paying in the checkout is disabled.

Perform a server-to-server session update

See session update for details on what parts of the session can be updated, and how.

Refreshing the session

After updating the session, call refreshSession on the checkout object:

checkout.refreshSession();

or use the callback in onSessionLocked:

onSessionLocked: (event, checkout, callback) => {
    console.log("pay_lock_id", event.pay_lock_id);
    callback(); // refresh session
};

refreshSession() returns a promise that is resolved when the SessionUpdated event is received from the checkout.

Editing and paying in the checkout is enabled again when a session without a pay_lock is loaded by the checkout.

Validating session before payment

To validate the session and perform actions before the session is paid, use the onSessionValidation-handler.

The checkout will be locked and payment will be paused until the provided callback function is called, or checkout.submitValidationResult is called with the result.

When validated successfully, return a successful result:

{
    success: true;
}

If the validation is not successful, return the result with an error message:

{
   success: false,
   clientValidationError: "session is not in sync with cart"
}

Example implementation:

onValidateSession: function(event, checkout, callback) {
     // Call the ecommerce solution to make sure the session is sync with the cart
     callback({
         success: false,
         clientValidationError: "session is not in sync with cart",
     });
},

Debug logging

Set debug: true in the options passed to embed() or redirect() to make the SDK log what it is doing to the browser console. Every entry is written with console.log and prefixed with [dintero-checkout-web-sdk].

:warning: Never enable debug in production. The log entries contain the full, unredacted payloads the SDK receives, including the payment session with the name, e-mail, phone number, addresses and order lines of the end user.

The SDK logs:

• the options embed() or redirect() was called with, and the checkout url it resolved them to
• the parameters of every on<Event> handler, logged right before the handler is invoked
• the results submitted back to the SDK, both through the callback given to onValidateSession/onAddressCallback and through checkout.submitValidationResult()/checkout.submitAddressCallbackResult(), which are logged with the name of the function that was used
• the functions called on the checkout instance: lockSession(), refreshSession(), setActivePaymentProductType(), submitValidationResult(), submitAddressCallbackResult() and destroy(), including the event lockSession() and refreshSession() resolve with, or the reason they are rejected
• errors thrown by the handlers in the host application, which the SDK otherwise only reports with console.error

Example output for a session that is loaded, locked and refreshed:

[dintero-checkout-web-sdk] embed(options) {sid: "T11223344.<short-uuid>", debug: true, …}
[dintero-checkout-web-sdk] embed session url https://checkout.dintero.com/v1/view/…
[dintero-checkout-web-sdk] options.onSession() {type: "SessionLoaded", session: {…}} {…}
[dintero-checkout-web-sdk] checkout.lockSession()
[dintero-checkout-web-sdk] checkout.lockSession() resolved {type: "SessionLocked", …}
[dintero-checkout-web-sdk] options.onSessionLocked() {type: "SessionLocked", …} {…} f
[dintero-checkout-web-sdk] onSessionLocked callback()
[dintero-checkout-web-sdk] onSessionLocked callback() resolved {type: "SessionUpdated", …}

Nothing is logged when debug is left out or set to false. The wording of the log entries is a debugging aid and may change between releases.

Age verification events

If the payment session has age verification enabled, the checkout will show a gate that the end user must pass through an identity provider (eg. BankID) before the rest of the checkout is available. Use onAgeVerificationStarted, onAgeVerificationFailed and onAgeVerificationEnded to react to this flow from the embedding page.

• onAgeVerificationStarted is called when the end user clicks through to start the identity provider flow.
• onAgeVerificationFailed is called when verification could not be completed, eg. because the end user did not meet the minimum age requirement or authorization with the identity provider failed. The error field holds a reason, eg. "age-requirement-not-met". Note that the end user cancelling out of the identity provider is not treated as a failure - the gate is simply shown again so they can retry.
• onAgeVerificationEnded is called once verification has passed and the gate is lifted. The result field is currently always "passed".

While age verification is in progress, lockSession(), refreshSession(), and setActivePaymentProductType() throw synchronously. Avoid these calls until verification finishes, or handle the error with try/catch; promise rejection handlers do not catch it.

onAgeVerificationStarted: function (event, checkout) {
    console.log("age verification started");
},
onAgeVerificationFailed: function (event, checkout) {
    console.log("age verification failed", event.error);
},
onAgeVerificationEnded: function (event, checkout) {
    console.log("age verification ended", event.result);
},

Using the SDK for a redirect checkout

The user is redirected to the Dintero Checkout to complete payment.

import { redirect } from "dintero-checkout-web-sdk";

const checkout = redirect({
    sid: "T11223344.<short-uuid>",
});

Bugs

Bugs can be reported to https://github.com/Dintero/Dintero.Checkout.Web.SDK/issues

Security

Contact us at [email protected]

Browser support

All major browsers above version N - 1, where N is the most recent version.

The SDK includes a polyfill for promises that is added to the global scope if promises are not supported by the browser.

Building from source

make build

The Dintero Checkout SDK is built with tsdown.

Creating a new release

1. Enforce all commits to the master branch to be formatted according to the Angular Commit Message Format
2. When merged to master, it will automatically be released with semantic-release