Embedded Checkout

Our Embedded Checkout provides you with more control over your customer's account-to-account payment experience. It is implemented as a web-component. Web components provide isolated and fully responsive UI elements, ensuring they do not conflict with other styles or JavaScript on the page.

See Our Embedded Checkout in action

Supported Regions:

Integration Guide:

Before integrating Banked Embedded Checkout, ensure you have read and implemented the Authentication section in Welcome to Banked. Once you have obtained your authentication keys, follow these steps to embed our checkout into your application:

1. Create Client Keys

Generate a set of client keys associated with the domain(s) where you plan to embed the Banked Checkout to comply with our Content Security Policy

See `Client Key API` Docs

Example:

POST /v2/client_keys (json)

{
  "domains": ["https://checkout.example.com"]
}

Response (201) (json)

{
  "domains": [
    "https://checkout.example.com"
  ],
  "token": "a815d44f669d7ac44f29a4a4642c3cd9",
  "id": "e86282f5-322d-4b2b-8380-9944adf76e26"
}

2. Create a Payment Session

When a customer confirms their order, create a Payment Session using POST /v2/payment_sessions. Refer to the following links for detailed instructions on creating payment sessions:

See `Payment Session` Docs

Example:

POST /v2/payment_sessions (json)

{
  "reference": "Test Payment Session",
  "error_url": "http://example.com/error",
  "success_url": "http://example.com/success",
  "email_receipt": false,
  "line_items": [{
      "name": "Candles",
      "amount": 200,
      "currency": "GBP",
      "quantity": 1
  }],
  "payee": {
      "name": "Current Account",
      "account_number": "12345678",
      "sort_code": "010203"
  },
  "payer": {
      "name": "Test",
      "email": "foo@baa.com"
  }
}

When the checkout journey is complete, Banked redirects the customer to the success_url or error_url you specified in the payment session request. Alternatively, override this behavior with callBack functions.

Response: 201 (json)

{
  "amount": 400,
  "created_at": "2019-11-01 15:48:26 UTC",
  "currency": "GBP",
  "end_to_end_id": "728d061b-8e47-4052-be4f-5f9bcdee39ff",
  "error_url": "http://example.com/error",
  "id": "1ae1ce03-dfa9-4593-b487-65c656991cb5",
  "line_items": [
    {
      "amount": 200,
      "currency": "GBP",
      "description": null,
      "name": "Candles",
      "quantity": 1
    }
  ],
  "live": true,
  "payee": {
    "name": "Current Account",
    "account_number": "12345678",
    "sort_code": "010203"
  },
  "payer": {
    "email": "demo+0.4371035245462651@banked.com",
    "name": "Checkout Demo User"
  },
  "reference": "Test Payment Session",
  "state": "awaiting_provider",
  "success_url": "http://example.com/success",
  "url": "https://checkout.banked.com/uk/1ae1ce03-dfa9-4593-b487-65c656991cb5?token={unique-access-token}",
  "email_receipt": true
}

You must store the payment session id and pass it into the payment_id prop on the Banked Checkout Component.

3. Implement Embedded Checkout:

After creating a payment session, follow these two steps to integrate Banked Embedded Checkout:

Include the <script> Tag: Add the <script> tag with src="https://js.banked.com/v3/checkout.js". This script loads the necessary resources to initialize and run the Embedded Checkout component.
Configure <banked-checkout> Element : Place the <banked-checkout> element within the <body> tag of your page:

  <banked-checkout
    api-key="YOUR_CLIENT_KEY"
    payment-id="YOUR_PAYMENT_ID"
    options="{OPTIONS}"
  ></banked-checkout>

Parameters	Validation	Description
`api-key`	`string`	The client key for the Application which the payment belongs to.
`payment-id`	`string`	Unique identifier for the payment session. Please refer to the Merchant API documentation or the Partner API documentation for more information on how to create a payment session.
`options`	`string`	To explore available options for customizing the Embedded Checkout, refer to Checkout Options

Example

React (js)

  import { useScript } from "@uidotdev/usehooks";
  import React, { useEffect } from "react";

  function App() {

    // 1. Include our <script> tag on your page
    const bankedSDK = useScript("http://js.banked.com/v3/checkout.js");
    const options = {
      is_graceful_exit_disabled: true,
    };

    return (
      // 2. Include the checkout element on your page, where you would like the UI to be rendered
      typeof window !== "undefined" &&
      bankedSDK === "ready" (
        <banked-checkout
          api-key="YOUR_CLIENT_KEY"
          payment-id="YOUR_TRANSACTION_ID"
          options={JSON.stringify(options)}
        ></banked-checkout>
      )
    );
  }

  export default App;

HTLM (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"
    options="{OPTIONS}"
  ></banked-checkout>
</body>

Once the Checkout Component is successfully configured, it handles the following:

Renders the UI for your user to choose their bank.
Displays Banked's Terms and Conditions.
Redirects users to their bank's authorization flow, either through mobile handoff, or a web redirect.

4. Handle Checkout Redirect

After a customer completes the authorization step with their bank, the checkout redirects them to the success_url or error_url provided during payment session creation. For more information about how and when redirects occur, please see Checkout Redirects. You can override the default redirects by using the callback functions onSuccess and onError. Specifying these callback functions disables the automatic redirect, allowing your application to handle the event directly.

Callback functions:

onSuccess (optional) Called when the checkout process is successfully completed.

{
  type: "success",
  data: {
    redirectUrl: "{success_url}",
    bankedCheckoutResult: "success || pending",
    paymentResult: "sent || pending",
    paymentID: "string"
  }
}

onError (optional) Called when a user cancels the checkout or an error has occured when making a payment attempt.

{
  type: "error",
  data: {
    redirectUrl: "{error_url}",
    bankedCheckoutResult: "failure || user-cancelled",
    paymentResult: "awaiting_provider || awaiting_payment_consent || initiated || failed ",
    paymentID: "string"
  }
}

Parameters	Validation	Description
`type`	`string`	The Callback function object type (`success` or `error`).
`data.redirectUrl`	`string`	See Checkout Redirects
`data.bankedCheckoutResult`	`string`	See Glossary: Banked Checkout Result
`data.paymentResult`	`string`	See Glossary: Payment Result
`data.paymentID`	`string`	See Glossary: Payment ID

To use this override behavior, call the .init function:

window.BankedGlobalCheckout.init({ onSuccess, onError })

Example:

React (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"
          options="{OPTIONS}"
        ></banked-checkout>
      )}
    </>
  );
}

export default App;

FAQs

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

Yes. The Web Components specification just works - as long as the <script> tag is loaded before you try to initialize 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 the entire authorization 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?

Our status page shows the current statistics. The JavaScript 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 Checkout 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 our checkout to your page. If you continue seeing the error, contact our support team.

Integration Guide:Copy URL

1. Create Client KeysCopy URL

Example:Copy URL

2. Create a Payment SessionCopy URL

Example:Copy URL

3. Implement Embedded Checkout:Copy URL

ExampleCopy URL

4. Handle Checkout RedirectCopy URL

Callback functions:Copy URL

Example:Copy URL

FAQsCopy URL

Integration Guide:

1. Create Client Keys

Example:

2. Create a Payment Session

Example:

3. Implement Embedded Checkout:

Example

4. Handle Checkout Redirect

Callback functions:

Example:

FAQs