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 flowYou can see the Banked.js integration in action in our demo e-commerce store
Get started with 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:
Are you using React? See an example implementation
<head> <title>Your Application</title> </head> <body> <!-- 1. Include our <script> tag on your page --> <script src="https://js.banked.com/v3/checkout.js" type="text/javascript" async defer ></script> <!-- 2. Include the checkout element on your page, where you would like the UI to be rendered --> <banked-checkout api-key="YOUR_CLIENT_KEY" payment-id="YOUR_PAYMENT_ID" ></banked-checkout> </body>
<head> <title>Your Application</title> </head> <body> <!-- 1. Include our <script> tag on your page --> <script src="https://js.banked.com/v3/" type="text/javascript" async defer ></script> <!-- 2. Include the checkout element on your page, where you would like the UI to be rendered --> <banked-checkout api-key="YOUR_CLIENT_KEY" payment-id="YOUR_PAYMENT_ID" ></banked-checkout> </body>
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.
There's also two optional callback functions exposed from the JS SDK:
The below callback functions will override our default success and error redirect functionality that's typically performed at the end of the checkout.
onSuccess
this function is called when a checkout session has reached the end of the flow successfully. This will be called with an object with the following structure:
{ type: "success", data: { redirectUrl: "https://example.com", } }
onError
this function is called when a checkout session has returned an error state at the end of the flow. This will be called with an object with the following structure:
{ type: "error", data: { redirectUrl: "https://example.com", } }
To use this override behaviour, call the SDK's .init
function:
window.BankedGlobalCheckout.init({ onSuccess, onError })
Customizing banked checkout
The checkout can be customized to show a logo for your brand. We recommend using this when you are working with our hosted checkout. In the embedded checkout your site will already be visible to the customer.
Current logo support is done internally and as a banked customer you can request this from our support team.
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
- a single language code from BCP 47 range, for example
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.
- This is a single ISO 3166 country code for example
Passing the parameters is done in the page HTML as shown below:
<banked-checkout api-key="YOUR_CLIENT_KEY" payment-id="YOUR_PAYMENT_ID" country-codes="DE" > </banked-checkout>
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:
<banked-checkout api-key="YOUR_CLIENT_KEY" payment-id="YOUR_PAYMENT_ID" lang="de" ></banked-checkout>
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:
- 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.
- 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).
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:
<banked-checkout api-key="YOUR_CLIENT_KEY" payment-id="YOUR_PAYMENT_ID" hide-header > </banked-checkout>
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.
Upgrading to our Global SDK
To upgrade to our new global SDK, its as simple as updating the SDK URL from https://js.banked.com/v3/
to https://js.banked.com/v3/checkout.js
.
Please note, some of the parameters available on the older SDK are now deprecated:
- lang
- country-codes
- hide-header
- show-all-providers
- show-line-items
ReactJS Example Usage
import { useScript } from "@uidotdev/usehooks"; import React, { useEffect } from "react"; function App() { const bankedSDK = useScript("http://js.banked.com/v3/checkout.js"); // You only need to call init with onSuccess/onError if you want to override the default redirect functionality // when a payment has succeeded or failed. useEffect(() => { if (bankedSDK === "ready") { window.BankedGlobalCheckout.init({ onSuccess: (eventData) => console.log(eventData), onError: (eventData) => console.log(eventData), }); } }, [bankedSDK]); return ( <> {bankedSDK === "loading" && <div>Loading...</div>} {bankedSDK === "ready" && ( <banked-checkout api-key="YOUR_CLIENT_KEY" payment-id="YOUR_TRANSACTION_ID" ></banked-checkout> )} </> ); } export default App;
FAQs
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.