👍
Before you begin
When sending requests to PowerBoard’s API, you must provide either a Public Key and/or Secret Key depending on your use case.
API keys are generated via PowerBoard’s Merchant Dashboard, in three easy steps:

Login to the PowerBoard Merchant Dashboard.

Click on the ‘My Company’ link and proceed to the ‘API and Security’ heading.

On screen, you’ll see both Public and Secret Key required to send requests to PowerBoard’s API.

Your integration will utilise the following components:

PowerBoard Hosted JavaScript Library ('Widget')
PowerBoard REST API

Overview

PowerBoard subscriptions lets you create and manage recurring payments. Subscriptions allow you to charge a customer on a recurring basis without them needing to re-enter their payment details every time.

Subscriptions can be configured to end after a specified date, number of payments, or after a certain amount (e.g. $500) depending on the needs of your business.

Integration Steps

Step 1) Creating and initialising the Widget

You should begin by including PowerBoard's Hosted JavaScript library in your page and creating a container for the PowerBoard widget

<script src="https://widget.preproduction.powerboard.commbank.com.au/sdk/latest/widget.umd.min.js"></script> 
<script>
       var widget = new cba.HtmlWidget('#widget', 'YOUR_PUBLIC_KEY', 'GATEWAY_ID');
</script> 
<div id="widget"></div>

Initialise the PowerBoard Widget by calling the .load method and the widget's environment to 'preproduction_cba'.

<script src="https://widget.preproduction.powerboard.commbank.com.au/sdk/latest/widget.umd.min.js"></script> 
<script>
    var widget = new cba.HtmlWidget('#widget', 'YOUR_PUBLIC_KEY', 'GATEWAY_ID');
    widget.setEnv("preproduction_cba");
    widget.load();
</script> 
<div id="widget"></div>

Step 2) Customising the widget

You can use pre-defined methods and parameters to allow you to customise the fields and set styles of the widget. Additionally, you are able to monitor real-time customer interactions through the use of the widget's event call-backs.

See below methods and their definitions:

Method	Description
.onFinishInsert	After the 'finish' event of the widget, the 'payment_source' object will be inserted into the input (selector).
.setEnv	Method to change PowerBoard environments.
.useAutoResize	Method to change PowerBoard environments.
.setTexts	Allows you to set custom texts inside the widget.
.setStyles	Allows you to set custom styling for the widget.
.on	Event listener for the widget, valid events include: - afterLoad - submit - finish - validationError - systemError - metaChange - resize

<script src="https://widget.preproduction.powerboard.commbank.com.au/sdk/latest/widget.umd.min.js"></script>  
 
<script>
   var widget = new cba.HtmlWidget("#widget", "YOUR_PUBLIC_KEY", "GATEWAY_ID");
    
   widget.onFinishInsert('input[name="payment_source"]', "payment_source");
   widget.setEnv("preproduction_cba");
   widget.useAutoResize();
    
   widget.setTexts({submit_button: "Submit Card"});
   widget.setStyles({background_color: "#FFFFFF", border_color: "#000000", button_color: "#000000"});
    
   widget.load();
    
   widget.on("finish", function(data) {console.log("Widget Response", data);})
</script> 
 
<div id="widget"></div>

📘
Our Widget is extensively customisable
Please refer to Widget Customisation guide to learn more about it.

Full example with HTML

This example shows how you can use PowerBoard's pre-defined methods to customise your widget.

<!DOCTYPE html>
<html lang="en">
 
  <head>
    <meta charset="UTF-8">
    <title>PowerBoard Widget Example - Card Payments</title>
    <style>
    iframe {
        border: 0;
        width: 100%;
        height: 400px;
    }
    </style>
  </head>
  <body>
    <!-- Container for PowerBoard Widget -->
    <div id="widget"></div>
    <!-- Payment Source Textbox -->
    <center>
      <label for="payment_source"><b>PowerBoard Payment Source</b></label>
    </center>
    <center>
      <input type="text" size="33" id="payment_source" name="payment_source">
    </center>
    <script
      src="https://widget.preproduction.powerboard.commbank.com.au/sdk/latest/widget.umd.min.js"></script>
    <script>
    var widget = new cba.HtmlWidget("#widget", "YOUR_PUBLIC_KEY", "GATEWAY_ID");
 
    widget.onFinishInsert('input[name="payment_source"]', "payment_source");
    widget.setEnv("preproduction_cba");
    widget.useAutoResize();
    widget.setTexts({submit_button: "Submit Card"});
    widget.setStyles({background_color: "#FFFFFF", border_color: "#000000", button_color: "#000000"});
 
    widget.load();
 
    widget.on("finish", function(data) {console.log("Widget Response", data);});
    </script>
  </body>
</html>

After submission of card details, the widget will return a "finish" event containing the below parameters within the object:

{
    "event": "finish",
    "purpose": "payment_source",
    "message_source": "widget.paydock",
    "ref_id": "",
    "widget_id": "012aa127-6b01-2e9e-f3c8-8d54e54c3ece",
    "payment_source": "251985e6-a368-4168-8e1a-bfb30c3e4bab"
}

Step 3) Create a subscription using the PowerBoard API

Use the payment_source returned from the Widget in your API charge request, see below example:

📘
Go to the charge endpoint page.

API Endpoint	https://api.preproduction.powerboard.commbank.com.au/v1/subscriptions
HTTP Method	POST
Headers	x-user-secret-key- POWERBOARD_SECRET_KEY - This is your PowerBoard API Secret Key. Content-Type - application/jsonContent - Type will always be application/json.
Request Parameters	amount - string - Total amount for the subscription transaction. currency - string. Always set to 'AUD'. reference - string - Reference for the transaction. This reference may assist to identify the transaction in your back-end systems. For example, a purchase order number or invoice number. token - string - payment source string returned from the widget following the "finish" event. Example: "paymentsource": "c2a69078-110c-4081-a927-167d9d1b2f04". customer.first_name - _string - Customer first name. customer.last_name - string - Customer last name. customer.phone - string - Customer phone number. customer.email - string - Customer email address. customer.payment_source.address_line1 - string - Customer address, line 1. customer.payment_source.address_line2 - string - Customer address, line 2. customer.payment_source.city - string - Customer city. customer.payment_source.state - string - Customer state. customer.payment_source.postcode - string - Customer postcode. customer.payment_source.country - string - Customer country.* schedule.frequency - string - A number value for how often a subscription charge is processed (default = "1") schedule.interval - string - The interval of the subscription; allowed values: day, week, month, year schedule.start_date - string - The start date of the subscription in the ISO 8601 format (yyyy-mm-ddThh:mm:ss.sssZ) or in a short type of date (yyyy-mm-dd) schedule.end_date - string - The end date of the subscription in the ISO 8601 format (yyyy-mm-ddThh:mm:ss.sssZ) or in a short type of date (yyyy-mm-dd)

Once you have submitted your API charge request, PowerBoard will respond accordingly with a 201 Created. The response should be stored against your database or relevant payments ecosystem.

Sample body

{
    "amount": "22.99",
    "currency": "AUD",
    "reference": "subscip_ref",
    "description": "Test subscription",
    "token": "6bf026ed-38f9-4cc1-8787-1fc45f65d665",
    "schedule": {
        "frequency": "1",
        "interval": "day",
        "start_date": "2023-08-08",
        "end_date": "2023-08-09"
    }
}

{
    "status": 201,
    "error": null,
    "resource": {
        "type": "subscription",
        "data": {
            "schedule": {
                "frequency": 1,
                "retry_count": 0,
                "held_count": 0,
                "completed_count": 0,
                "locked": false,
                "interval": "day",
                "start_date": "2023-08-08T00:00:00.000Z",
                "end_date": "2023-08-09T00:00:00.000Z",
                "end_amount_after": 0,
                "end_amount_before": 0,
                "end_amount_total": 0,
                "next_assessment": "2023-08-08T00:00:00.000Z",
                "next_assessment_planned": "2023-08-08T00:00:00.000Z",
                "first_assessment": "2023-08-08T00:00:00.000Z",
                "status": "inprogress"
            },
            "statistics": {
                "successful_transactions": 0,
                "total_collected_amount": 0
            },
            "currency": "AUD",
            "archived": false,
            "_id": "64d180b71e04e51be27fc81f",
            "amount": 22.99,
            "description": "Test subscription",
            "reference": "subscrip_ref",
            "customer": {
                "customer_id": "64d180b71e04e51be27fc81c"
            },
            "_service": {
                "customer_default_gateway_id": "649a6f111e04e51be27e9a91",
                "tags": "undefined undefined undefined"
            },
            "status": "active",
            "updated_at": "2023-08-07T23:39:35.308Z",
            "created_at": "2023-08-07T23:39:35.308Z",
            "__v": 0
        }
    }
}

Once the subscription has been created, a new subscription will be created under your powerboard merchant account detailing the subscription and its status.

subscription example

Available Subscription Statuses

Below is a list of the possible statuses a subscription can have:

Status	Description
Active	The subscription is active and there are remaining payments within the subscription dates.
Held	The subscription has been manually put on hold.
Expired	The subscription that has expired beyond its specified end date.
Completed	The subscription that is completed and all payments have been taken.
Failed	The subscription has failed payment and has exceeded the maximum number of retries.
Deleted	The subscription has been removed.

Modifying the Subscription

You can modify subscriptions based on a number of available parameters,

Step 1) Use the PowerBoard API to modify subscription details

Supply the Subscription ID for the subscription you would like to update on your PowerBoard account.

API Endpoint	https://api.preproduction.powerboard.commbank.com.au/v1/subscriptions/:id
HTTP Method	POST
Headers	x-user-secret-key- POWERBOARD_SECRET_KEY - This is your PowerBoard API Secret Key. Content-Type - application/jsonContent - Type will always be application/json.
Path Parameters	id - The ID of the subscription to be modified
Request Parameters	amount - string - Total amount for the transaction. status - string - The current status of the subscription; available values: 'Active', 'held', 'expired'. payment_source_id - string - The payment source to pay for the subscription schedule.start_date - string - A start date can be provided in the ISO 8601 format (yyyy-mm-ddThh:mm:ss.sssZ) or in a short type of date (yyyy-mm-dd) schedule.end_date - string - A end date can be provided in the ISO 8601 format (yyyy-mm-ddThh:mm:ss.sssZ) or in a short type of date (yyyy-mm-dd)

Once you have submitted your API charge request, PowerBoard will respond accordingly with a 201 Created. The response should be stored against your database or relevant payments ecosystem.

Sample body

{
    "status": "held"
}

{
    "status": 200,
    "error": null,
    "resource": {
        "type": "subscription",
        "data": {
            "schedule": {
                "frequency": 1,
                "retry_count": 0,
                "held_count": 0,
                "completed_count": 0,
                "locked": false,
                "interval": "day",
                "start_date": "2023-08-10T00:00:00.000Z",
                "end_date": "2023-08-20T00:00:00.000Z",
                "end_amount_after": 0,
                "end_amount_before": 0,
                "end_amount_total": 0,
                "next_assessment": "2023-08-10T00:00:00.000Z",
                "next_assessment_planned": "2023-08-10T00:00:00.000Z",
                "first_assessment": "2023-08-10T00:00:00.000Z",
                "status": "inprogress",
                "end_transactions": null
            },
            "statistics": {
                "successful_transactions": 0,
                "total_collected_amount": 0
            },
            "customer": {
                "customer_id": "64d186be1e04e51be27fc882"
            },
            "currency": "AUD",
            "archived": false,
            "_id": "64d186bf1e04e51be27fc885",
            "company_id": "649a6edfb848941bea648bd6",
            "amount": 79,
            "description": "Test subscription notification",
            "reference": "Fuga consequuntur sint ab magnam",
            "status": "active",
            "updated_at": "2023-08-08T01:54:11.613Z",
            "created_at": "2023-08-08T00:05:19.033Z",
            "held_at": "2023-08-08T01:16:20.180Z",
            "last_change_by": "manual",
            "gateway_type": "MasterCard",
            "gateway_name": "MasterCard",
            "gateway_mode": "test"
        }
    }
}

Retrying a subscription payment

PowerBoard allows you to setup custom retry behaviour on individual or all subscriptions to re-attempt a subscription payment before moving it to a failed status.

Retry behaviour can be configured globally on all subscriptions via the PowerBoard Merchant dashboard, or setup on each individual subscription via the PowerBoard API.

Configure global retry behaviour via the merchant portal.

Step 1. Navigate to Subscriptions → Settings within the PowerBoard merchant portal

Step 2. Configure the retry count and retry interval fields with your preferred values.
Retry Count: Number of times a failed payment will be attempted before change to a failed subscription result.
Retry Interval: How often (in hours) a subscription payment will retry.

Retry configuration

Step 3. Click the Update button to save your configuration to PowerBoard.

🚧
Important
This configuration will apply this retry behaviour to all active and new subscriptions unless otherwise configured via our API.

Configure individual retry behaviour via the PowerBoard API.

PowerBoard has a number of fields available in our Create and Modify subscription API endpoints that let you specify specific conditions on how that subscription will be retried.

See the below example of how these can be appended to the request body.

Configurable Request Parameters:

Field	Type	Description
retry.limit	string	Maximum number of times a subscription attempt will be retried
retry.frequency	string	Time between each retry attempt in hours/days
retry.interval	string	Interval at which the subscription payment attempt will be tried; Allowed values: hours, days
retry.fail_status	string	The status the subscription will be changed to after the maximum retry limit is reached.

Subscriptions

Subscriptions

👍
Before you begin

Overview

Integration Steps

Step 1) Creating and initialising the Widget

Step 2) Customising the widget

📘
Our Widget is extensively customisable

Full example with HTML

Step 3) Create a subscription using the PowerBoard API

📘

Sample body

Available Subscription Statuses

Modifying the Subscription

Step 1) Use the PowerBoard API to modify subscription details

Sample body

Retrying a subscription payment

Configure global retry behaviour via the merchant portal.

🚧
Important

Configure individual retry behaviour via the PowerBoard API.

Subscriptions

👍Before you begin

Overview

Integration Steps

Step 1) Creating and initialising the Widget

Step 2) Customising the widget

📘Our Widget is extensively customisable

Full example with HTML

Step 3) Create a subscription using the PowerBoard API

📘

Sample body

Available Subscription Statuses

Modifying the Subscription

Step 1) Use the PowerBoard API to modify subscription details

Sample body

Retrying a subscription payment

Configure global retry behaviour via the merchant portal.

🚧Important

Configure individual retry behaviour via the PowerBoard API.

👍
Before you begin

📘
Our Widget is extensively customisable

🚧
Important