Our Hosted Mandates offer the simplest way to integrate mandate authorization on your website. Make a single API request to create a mandate and redirect your customer to the URL provided in the response. Banked manages the entire process, including data collection, bank selection, and mandate authorization, ensuring a seamless experience for you and your customers.
The Hosted Mandates experience handles the following:
- Renders the UI for your user to choose their bank.
- Displays Banked's Terms and Conditions.
- Collects mandate consent and payment terms.
- Gives the ability for user's to consent on their banking app.
Supported Regions:
- AU
Integration Guide:
Before integrating Banked Hosted Mandates, ensure you have read 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 a Mandate
When a customer wants to set up a mandate, create a Mandate using POST /v2/mandates. Refer to the following documentation 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"
}
}
}
}
]
}
The redirect_url on the mandate creation request will be used to redirect the customer back to your application once the Mandate journey ends. This parameter is optional.
{
"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"
}
2. Direct the User to the Mandate URL
Direct the customer to the url provided in the mandate response. The customer will then complete mandate authorization through our Hosted Mandates experience.
3. Handle Mandate Redirect
After a customer exits the mandate flow, the checkout redirects them to the redirect_url provided during mandate creation. Banked appends the following parameters to the redirect url to provide context on the mandate, customer action and resulting mandate status:
| Parameters | Description |
|---|---|
banked-result | See Banked Result |
For detailed information on how to handle the Mandate Redirect see:
Checkout Redirects