Partner Docs

Merchant Docs


Banked.js enables you to embed Banked's checkout into your web application, allowing your users to choose their bank and be redirected to its authorisation process without needing to go into Banked's hosted checkout.

Try out the checkout, and the different Banked.js configurations below:

Try our demo payment flow

You can see the Banked.js integration in action in our Top-ups demo and view its source code to understand the implementation.

How to implement Banked.js

Banked.js is implemented as a web-component, so it exposes a fully encapsulated DOM API. Using Web Components also allows it to further isolate its UI and avoid clashing with any other styles or JavaScript on the page. The components are fully responsive and have been tested across many device types.

Implementing Banked.js involves two steps: including our script tag anywhere on the page, and adding the custom checkout element to your HTML, within the <body> tag.

The example below shows a basic Banked.js integration:

  <title>Your Application</title>
  <!-- 1. Include our <script> tag on your page -->
  <!-- 2. Include the checkout element on your page, where you would like the UI to be rendered -->

You will need to pass some parameters into the banked-checkout component:

  • api-key is the client key for the Application which the payment belongs to.
  • payment-id should be generated on your application's back-end. There's an example of how to do this in our Top-up example using our Node.js library.

Customizing banked checkout

To set preferences for regions and language you can pass these parameters:

  • lang (optional)
    • a single language code from BCP 47 range, for example en-GB.
    • Details on languages are here
  • country-codes (optional)
    • This is a single ISO 3166 country code for example DE
    • This field will set priorities for available banks. For example, if you want to show your consumers German banks first, set DE as the value.

Passing the parameters is done in the page HTML as shown below:


To configure the number of sections in the banked checkout you can use these parameters:

  • hide-header (optional)
    • This is a flag you can use to hide the header in the checkout.
  • show-all-providers (optional)
    • This is a flag you can use to show all available bank providers. By default a search bar and a list of the most common providers will be shown instead.
  • show-line-items (optional)
    • This is a flag you can use to show individual line items of the order on the checkout page. By default only the total will be shown.

Passing the parameters is done in the page HTML as shown below:


Completing Checkout

Once given the payment ID and client key, the Banked components will handle the following functions:

  • Rendering the UI for your user to choose their bank.
  • Agreeing to Banked's Terms and Conditions.
  • Redirecting users to their bank's authorisation flow, either through mobile handoff, or a web redirect.

When a user completes the authorisation step with their bank, they'll be redirected to the success_url or error_url that were provided when the payment was created.

Specify the checkout language

Banked checkout currently supports the following languages:

  • English (en)
  • French (fr)
  • German (de)
  • Spanish (es)

If you want to control the language of banked checkout then pass the lang tag to the component like this:


Setting the lang tag to the same as your website will give users the best experience of the banked checkout. This is our recommended way to set the language on the web.

If you are unable to specify the language in your website, then banked checkout will try and set the language for you. The rules for this are evaluated in order; and the first one that succeeds will specify the language:

  1. Checkout looks for the available languages from the consumers browser.
    • If these exist the language is set to their preferred supported language among banked checkout supported languages.
    • This will give a consistent experience if your website also follows this web standard.
  2. If the banked checkout cannot find any language based hints it will use the be supported language for the region in which the payment is being made
    • For example a German payment will show the German language (de).


I have a Single Page App (SPA), will the component work?

Yes. The Web Components specification is just 'HTML + magic' so you shouldn't need to worry about initialising the component at the right time; as long as the <script> tag is loaded before you try to initialise the component on the page and you provide the component with a valid payment ID.

Is this secure?

Yes. The payment is still created on your server and so can't be tampered with. Only the payment ID is shared with the client; we handle all the authorisation process with your customer's bank securely via our API. Nothing sensitive is exposed in the client.

What availability do you support for this embedded checkout?

Take a look at our status page for the current statistics. The JavaScript itself is served via Cloudflare's CDN, and is backed by their 100% uptime SLA.

What browsers does embedded checkout support?

We support all modern browsers. We do not support IE11, but if you need it we suggest using the official polyfills from the WebComponents team.

I am seeing a CORS error when embedding Banked.js into my website

You may be using the incorrect API key. Check that you have set the client key as the api-key attribute when adding Banked.js to your page. If you continue seeing the error, reach out to our support team.
Dark Theme
© 2023