Our Embedded Mandates provide you with more control over your customer's account-to-account mandate creation 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.
Supported Regions:
- AU
Integration Guide:
Before integrating Banked Embedded Mandates, 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 mandate creation 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 Mandates to comply with our Content Security Policy
Example:
{
"domains": ["https://checkout.example.com"]
}
{
"domains": [
"https://checkout.example.com"
],
"token": "a815d44f669d7ac44f29a4a4642c3cd9",
"id": "e86282f5-322d-4b2b-8380-9944adf76e26"
}
2. Create a mandate
When a customer wants to set up a mandate, create a mandate using POST /v2/mandate. Refer to the following links for detailed instructions on creating mandates:
Example:
{
"currency": "AUD",
"external_reference": "54a4fa72-d7b1-4328-b8c2-5a35c730cc2b",
"description": "mandate for your shopping account",
"destination": {
"account_type": "banked_bank_account",
"bank_account_id": "d8e74781-5fdb-40c8-9d08-54da83495efb",
"ultimate_party": {
"name": "Gerald Wiley Senior"
}
},
"payment_terms": {
"terms_type": "variable",
"frequency": "adhoc",
"count": 10,
"max_amount": 3000
},
"validity_start_date": "2023-01-01",
"validity_end_date": "2023-12-31",
"redirect_url": "https://www.example.com",
"actions": [
{
"action_type": "create_mandate_attempt",
"payload": {
"customer_ip_address": "127.0.0.1",
"source": {
"account_type": "plain_bank_account",
"account_owner_name": "Gerald Wiley",
"account_identifier": {
"identifier_type": "BSBAccountNumber",
"bsb": "111111",
"account_number": "0312345678"
}
}
}
}
]
}
When the mandate journey is complete, Banked redirects the customer to the redirect_url you specified in the mandate request. Alternatively, override this behavior with callBack functions.
{
"id": "8086851c-14ac-4341-97dd-bfa17da0f045",
"token": "550e8400-e29b-41d4-a716-446655440000",
"mode": "test",
"state": "created",
"created_at": "2023-08-01T12:32:00.000Z",
"currency": "AUD",
"external_reference": "54a4fa72-d7b1-4328-b8c2-5a35c730cc2b",
"description": "mandate for your shopping account",
"payment_terms": {
"terms_type": "variable",
"frequency": "adhoc",
"max_amount": 3000,
"count": 10
},
"validity_start_date": "2023-01-01",
"validity_end_date": "2023-12-31",
"latest_action": {
"id": "bf409f6f-e060-454c-8c09-2f6adcb2554b",
"mandate_id": "8086851c-14ac-4341-97dd-bfa17da0f045",
"action_type": "create_mandate_attempt",
"status": "in_progress",
"created_at": "2023-08-01T12:30:00.000Z"
},
"next_actions": {
"completion_paths": [
{
"action_type": "await"
}
],
"alternate_paths": [
{
"action_type": "cancel_mandate"
}
]
},
"url": "https://mandates.banked.com/mandate/8086851c-14ac-4341-97dd-bfa17da0f045?token=token123"
}
You must store the mandate id and pass it into the mandate_id prop on the Banked Mandates Component.
3. Implement Embedded Mandates:
After creating a mandate, follow these two steps to integrate Banked Embedded Mandates:
- Include the
<script>Tag: Add the<script>tag withsrc="https://js.banked.com/v3/mandates.js". This script loads the necessary resources to initialize and run the Embedded Mandates component. - Configure
<banked-mandate>Element : Place the<banked-mandate>element within the<body>tag of your page:
<banked-mandate
api-key="YOUR_CLIENT_KEY"
mandate-id="YOUR_MANDATE_ID"
></banked-mandate>
#### Example
```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/mandates.js");
return (
// 2. Include the mandates element on your page, where you would like the UI to be rendered
typeof window !== "undefined" &&
bankedSDK === "ready" (
<banked-mandate
api-key="YOUR_CLIENT_KEY"
mandate-id="YOUR_MANDATE_ID"
></banked-mandate>
)
);
}
export default App;
<head>
<title>Your Application</title>
</head>
<body>
<!-- 1. Include our <script> tag on your page -->
<script
src="https://js.banked.com/v3/mandates.js"
type="text/javascript"
async
defer
></script>
<!-- 2. Include the mandates element on your page, where you would like the UI to be rendered -->
<banked-mandate
api-key="YOUR_CLIENT_KEY"
mandate-id="YOUR_MANDATE_ID"
></banked-mandate>
</body>
Once the Mandates Component is successfully configured, it handles the following:
- Renders the UI for your user to fill in their banking details.
- Displays Banked's Terms and Conditions.
- Collects mandate consent and payment terms.
- Initiate the mandate; users will receive notifications on their banking provider app to authorize the mandate.
4. Handle Mandate Redirect
After a customer completes the authorization step with their bank, the mandates flow redirects them to the redirect_url provided during mandate creation. For more information about how and when redirects occur, please see Checkout Redirects. You can override the default redirects by using the callback function onCompletion. Specifying these callback function disables the automatic redirect, allowing your application to handle the event directly.
Callback functions:
onCompletion (optional) Called when the mandate creation process is completed.
{
type: "completed";
data: {
result: "success" | "failure" | "pending" | "user_cancelled";
redirectUrl?: 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.mandateResult | string | See Glossary: Mandate Result |
data.mandateID | string | See Glossary: Mandate ID |
To use this override behavior, call the .init function:
window.BankedGlobalMandates.init({ onSuccess, onError })
Example:
import { useScript } from "@uidotdev/usehooks";
import React, { useEffect } from "react";
function App() {
const bankedSDK = useScript("http://js.banked.com/v3/mandates.js");
// You only need to call init with onSuccess/onError if you want to override the default redirect functionality
// when a mandate has succeeded or failed.
useEffect(() => {
if (bankedSDK === "ready") {
window.BankedGlobalMandates.init({
onSuccess: (eventData) => console.log(eventData),
onError: (eventData) => console.log(eventData),
});
}
}, [bankedSDK]);
return (
<>
{bankedSDK === "loading" && <div>Loading...</div>}
{bankedSDK === "ready" && (
<banked-mandate
api-key="YOUR_CLIENT_KEY"
mandate-id="YOUR_MANDATE_ID"
></banked-mandate>
)}
</>
);
}
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 mandate ID.
Is this secure?
Yes. The mandate is still created on your server and so can't be tampered with. Only the mandate 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 Mandates?
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 Mandates 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 Mandates 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 mandates component to your page. If you continue seeing the error, contact our support team.