Developer

Partner Docs

Merchant Docs

Banked.JS

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 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

html
<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>

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 is the payment session ID which should be generated on your application's back-end. Please refer to the Merchant API documentation or the Partner API documentation for more information on how to create a payment session.

Callback Functions

The below callback functions will override our default success and error redirect functionality that's typically performed when the user exits the checkout flow. The callback function message fields are as follows:

  • type: Indicates the Callback function object type. It's either success or error.
  • data.redirectUrl: The URL for post-checkout redirect. Banked append a bankedCheckoutStatus={status} to detail what caused the redirect.
  • data.bankedCheckoutStatus: Details what caused the redirect. It can be one of success, pending, user-cancelled, failure

There's two optional callback functions exposed from the JS SDK:

1. onSuccess

This callback is optional and is called when the checkout process is successfully completed. The contents of the data object differs based on the following scenarios:

bankedCheckoutStatus: "success": When a payment attempt is successfully completed:

js
{
  type: "success",
  data: {
    redirectUrl: "https://www.example.com?banked-checkout-status=success",
    bankedCheckoutStatus: "success"
  }
}

bankedCheckoutStatus: "pending": When a payment attempt is being processed and confirmation is pending:

js
{
  type: "success",
  data: {
    redirectUrl: "https://www.example.com?banked-checkout-status=pending",
    bankedCheckoutStatus: "pending"
  }
}

2. onError

This function is called when a user cancels the checkout or an error has occured when making a payment attempt. The structure of the object differs based on the following scenarios:

bankedCheckoutStatus: "failure": When an non retry error occurs during a payment attempt:

js
{
  type: "error",
  data: {
    redirectUrl: "https://example.com/?banked-checkout-status=failure",
    bankedCheckoutStatus: "failure"
  }
}

bankedCheckoutStatus: "user-cancelled": When a user cancelled the payment attempt:

js
{
  type: "error",
  data: {
    redirectUrl: "https://example.com/?banked-checkout-status=user-cancelled",
    bankedCheckoutStatus: "user-cancelled"
  }
}

To use this override behaviour, call the SDK's .init function:

js
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.

Customizing embedded banked checkout

The embedded checkout can be customized via an options JSON string passed to the banked-checkout component. You can find available options below:

js
const options = {
  // default: false - user will have the option to cancel  out of the user experience  using a call to action button pay another way.
  // 
  // When value is true, graceful exit buttons are hidden from the checkout experience.
  // Where disabled you will be responsible for providing a cancellation journey.
  is_graceful_exit_disabled: true;
}

Please refer to the following examples for a better understanding of how to pass the options:

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. For more information about how and when redirects occurs, please see success and error redirect

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

js
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.

Next

Mandates

Previous

Libraries

support@banked.com
Dark Theme
© 2024