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

❗️
Requirements

Click to Pay Service connected (sandbox mode) via PowerBoard Dashboard.

Click to Pay Registration completed in the PowerBoard Dashboard

MPGS Service connected (sandbox mode) via PowerBoard Dashboard.

Your integration will utilise the following components:

PowerBoard Client-SDK ('Widget')

PowerBoard REST API

Steps to Enable in PreProduction Dashboard:

Step 1) Add Click to Pay Registration

Registrations are used to 'register' with the 3rd party provider for the feature.

Navigate to “Registrations”
Click on “Add New”
Click “Activate”
Fill out the SRC Registration
- Label (This is the display name of the registration in PowerBoard. This will be
  referenced when setting up the gateway service)
- Select Supported Card Schemes(Visa, Mastercard, AMEX, Discover)
- Primary Website URL
- Company Primary Legal Name (This must be unique)
- Country
- Environment (Sandbox for Testing & Production for Production)
- Company Address 1, Company Address 2, Company City, Company State are
  not mandatory.
Click “Connect”

Registration is now complete.

📘
Note:
There may be a small delay with the service being added in PowerBoard and the
registration being propagated to the chosen schemes. This is reflected in the info icon
that is shown next to the 'status' field of the registration and will be removed/disappeared
after 5 minutes, in which you should now be registered with the schemes.
In the event that the same Company Primary Legal Name is provided for a different
registration, the new registration will not be allowed & fail with an error in the UI.

Step 2) Add Click to Pay Service

Navigate to “Services”
Click on “Add New”
Select “SRC Services” from the dropdown
Click “Activate”
Fill out the SRC Service details
- Label (This is the display name of the service in PowerBoard)
- Select Registration (Select the SRC Registration you created in the previous
  step. You can use the same registration for multiple SRC Services.)
- Registration ID (This will be automatically populated based on the SRC Registration you select)
- Type (This will be automatically populated)
- Group (This will be automatically populated)
- Environment
Click “Connect”

Your SRC Service is now created and there will be an 'ID' associated with the service which can be used in the integration.

Steps to Integrate Click to Pay into your Payments ecosystem:

Click to Pay Widget - Recommended Implementation

This is the main recommended optimised integration method that enhances background loading and deferred customer data injection, ensuring merchants can now load the SDK concurrently with other checkout processes. This leads to noticeably improved perceived performance and a smoother user experience for your customers.

Key Benefits

Background Loading: The new hold_for_customer_data parameter enables the Click to Pay SDK to load in the background, allowing merchants to parallelise SDK initialisation with their checkout flow.
Deferred Customer Data Injection: The injectCustomerData method allows for customer data to be injected later in the Click to Pay flow, supporting the new optimisation pattern.
Improved Performance: Merchants can start the SDK loading early in their checkout process while collecting customer information in parallel.

Optimised Widget Implementation

<div id="clicktopay-widget"></div>
<script src="https://widget.powerboard.commbank.com.au/sdk/latest/widget.umd.js"></script>
<script>
// Recommended optimised configuration for the least frictionless flow
var meta = {
  disable_summary_screen: true,
  checkout_experience: "WITHIN_CHECKOUT",
  hold_for_customer_data: true, // Enable background loading
  dpa_transaction_options: {
    dpa_billing_preference: "NONE",
    confirm_payment: false,
    dpa_locale: "en_AU"
  }
}

// Initialise widget with background loading enabled
var widget = new cba.ClickToPay("#clicktopay-widget", 'SERVICE_ID', 'YOUR_PUBLIC_KEY', meta);

widget.setEnv("preproduction_cba") // the environment will default to sandbox if not explicitly set. Please ensure you explicitly set it to production in your production environment.
widget.useAutoResize();

// Listen for key events
widget.on("iframeLoaded", () => {
  console.log("iframeLoaded - Iframe is loaded but waiting for customer data");
});

widget.on("checkoutReady", () => {
  console.log("checkoutReady - Checkout is ready after customer data injection");
  // Optional: Show the checkout when ready
  // widget.showCheckout();
});

widget.on("checkoutCompleted", (data) => {
  console.log("checkoutCompleted", data);
});

widget.on("checkoutError", (data) => {
  console.log("checkoutError", data);
});

// Start background loading early in the checkout flow
widget.load();

// Optional: Hide until ready
widget.hideCheckout();

// Later, when customer data is available (collected from your checkout form)
// Call this when you have the customer information ready
widget.injectCustomerData({
  email: "[email protected]",
  first_name: "John",
  last_name: "Doe",
  phone: {
          country_code: "+61",
          phone: "0412345678",
        },
});
</script>

Implementation Flow

Early Initialisation: Call widget.load() as early as possible in your checkout flow with hold_for_customer_data: true
Background Loading: The SDK loads in the background while you collect customer information
Data Injection: When customer data is ready, call widget.injectCustomerData() with the customer information
Checkout Ready: The checkoutReady event fires when the widget is fully initialised and ready for customer interaction

Best Practices for Widget Optimisation

Early Loading: Call widget.load() as early as possible in your checkout flow
Hide Until Ready: Keep the checkout hidden until the checkoutReady event fires
Validate Data: Validate customer data before calling injectCustomerData()
Error Handling: Implement proper error handling for edge cases
Parallel Processing: Use the hold_for_customer_data optimisation to parallelise SDK initialisation with your checkout flow

Alternative Basic Implementation

If you prefer to pass customer data immediately (traditional approach):

<div id="src-widget"></div>
<script src="https://widget.powerboard.commbank.com.au/sdk/latest/widget.umd.js"></script>
<script>
var meta = {
  disable_summary_screen: false,
  dpa_transaction_options: {
    dpa_billing_preference: "FULL",
    dpa_locale: "en_AU"
  },
  customer: {
    email: "[email protected]",
    phone: {
      phone: '+61411111111'
    },
    first_name: "Test",
    last_name: "User"
  }
}

var widget = new cba.ClickToPay('#src-widget', 'SERVICE_ID', 'YOUR_PUBLIC_KEY', meta);
 
widget.setEnv("preproduction_cba");
widget.useAutoResize();
widget.on("iframeLoaded", () => console.log("iframeLoaded"));
widget.on("checkoutReady", () => console.log("checkoutReady"));
widget.on("checkoutCompleted", (data) => console.log("checkoutCompleted", data));
widget.on("checkoutError", (data) => console.log("checkoutError", data));
widget.load();
</script>

Widget Event Handlers

[iframeLoaded] - This event handler will be triggered when the widget iframe begins to load. In optimisation mode, this fires when the iframe is loaded but waiting for customer data.

[checkoutReady] - This event handler will be triggered when the widget is fully loaded. In optimisation mode, this fires after customer data has been injected and the checkout is ready for customer interaction.

[checkoutCompleted] - This event handler will be triggered when the transaction has completed. It will return your One-Time-Token.

[checkoutError] - This event handler will be triggered when the transaction has encountered an error.

[injectCustomerData] - This method allows you to provide customer information when available, supporting the optimised background loading pattern.

Widget Styling Customisation

You can customise the styling of the Click to Pay widget using the styling methods below:

widget.setStyles({
 enable_src_popup: true, //boolean
 primary_button_color: 'red', // string
 secondary_button_color: 'red', // string
 primary_button_text_color: 'red', // string
 secondary_button_text_color: 'red', // string
 font_family: 'Arial', // font
});

Parameter	Description	Values
enable_src_popup	Boolean flag to make the Click to Pay checkout show in a popup window instead of embedded in iframe.	Boolean (True or False)
primary_button_color	Colour for the primary button	String Colours (e.g. red, blue or hexadecimal colour value.)
secondary_button_color	Colour for the secondary button	String Colours (e.g. red, blue or hexadecimal colour value.)
primary_button_text_color	Colour for the primary colour text	String Colours (e.g. red, blue or hexadecimal colour value.)

After embedding the widget in your environment, it will render with the ability to surface 4 separate workflows. All of these flows are handled by the Click to Pay widget.

Recognised User Flow

User has used Click to Pay previously and has opted to store their card for future use.
Click to Pay Widget will identify the cookie and automatically display the users' stored cards.
User can select which stored card to use and continue to complete the Click to Pay Process.

Unrecognised user flow:

User does not have click to pay cookie stored in their browser
User enters email address/phone number into provided field
User will be required to authenticate via registered Click To Pay phone number or email
Once code is entered user will be provided with their stored cards and complete Click to Pay process.

Unregistered user flow:

User enters email address/phone number into provided field
User will register their personal and card details with Click to Pay
User will have the option to save card details with their Click to Pay
Post confirming contact details user will follow standard checkout flow

At the end of the above flows, customers will be presented with the summary screen where they click “Continue” and the One Time Token will be generated and returned in the ‘checkoutCompleted’ event in the data.token field.

Manual Card Entry (Guest) flow:

User is prompted to log into Click to Pay and selects ‘Manual Card Entry’
User adds card details into the provided fields and selects ‘Continue’, generating an OTT and completing this flow

❗️
Note: - When the ‘checkoutCompleted’ event is returned, the Click to Pay summary screen will not automatically disappear. It is the merchant's responsibility to clear the element and or navigate the end-user to a processing screen.

Process Click to Pay Transaction

Click to Pay with 3D Secure 2.0

1. Convert One-Time-Token to Session Token

With the data.token returned from the user Clicking the Continue button, make an API call which converts the data.token to a Session Vault Token.

API Endpoint	https://api.preproduction.powerboard.commbank.com.au/v1/vault/payment_sources
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	token - string - data.token returned from the previous step. vault_type - string - Type of token to be created.

{
    "token":"YOUR_OTT",
    "vault_type": "session"
}

{
    "status": 201,
    "error": null,
    "resource": {
        "type": "payment_source",
        "data": {
            "vault_token": "YOUR_SESSION_TOKEN",
            "type": "card",
            "company_id": "665f9e972908950f42173ac0",
            "card_number_last4": "1118",
            "card_number_bin": "51111111",
            "card_scheme": "mastercard",
            "status": "active",
            "expire_month": 1,
            "expire_year": 2039,
            "created_at": "2024-06-07T01:30:10.150Z",
            "updated_at": "2024-06-07T01:30:29.180Z",
            "_source_ip_address": "130.41.2.209",
            "vault_type": "session"
        }
    }
}

Store the returned ‘vault_token’ for use in the next step.

2. Make a request to the 3DS endpoint using the vault token

You can now use the 3DS endpoint to initialise a 3d Secure pre-authorisation using the vault token you generated in the previous step.

This will return a 3DS token that is required to render the 3DS iFrame to the customer.

API Endpoint	https://api.preproduction.powerboard.commbank.com.au/v1/charges/3ds
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 transaction. currency - string. Always set to 'AUD'. 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.vault_token - string - Token containing stored customer card information customer.payment_source.gateway_id - string - Unique identifier for Payment gateway service in PowerBoard _3ds.browser_details.name - string - The name of the customer's browser. _3ds.browser_details.java_enabled - string - Indicates whether the customer has Java enabled on their browser. _3ds.browser_details.language - string - the language in the customers browser, i.e. 'en-us' _3ds.browser_details.screen_height - string - The screen height of the customer's browser _3ds.browser_details.screen_width - string - The screen width of the customer's browser. _3ds.browser_details.time_zone - string - This is the timezone-offset in minutes between UTC and the local time of the customer's browser. _3ds.browser_details.color_depth - string - This is the bit depth of the colour palette for displaying images, in bits per pixel. Available values: 1, 4, 8, 15, 16, 24, 32, 48

{
    "amount": "100",
    "currency": "AUD",
    "customer": {
        "first_name": "Test ",
        "last_name": "User",
        "phone": "+61111111111",
        "email": "[email protected]",
        "payment_source": {
            "vault_token": "37a6a120-9393-42fb-b1da-874a98dc50d9",
            "gateway_id": "665f9eac9df8b911e0dbe120"
        }
    },
    "_3ds": {
        "browser_details": {
            "name": "EDGE",
            "java_enabled": "true",
            "language": "en-US",
            "screen_height": "640",
            "screen_width": "480",
            "time_zone": "273",
            "color_depth": "24"
        }
    }
}

{
    "status": 201,
    "error": null,
    "resource": {
        "type": "charge",
        "data": {
            "transfer": {
                "items": []
            },
            "schedule": {
                "stopped": false
            },
            "statistics": {
                "total_refunded_amount": 0,
                "full_refund": false,
                "need_sync": true
            },
            "customer": {
                "payment_source": {
                    "card_name": "Test Test",
                    "card_number_last4": "1019",
                    "card_number_bin": "450875",
                    "card_scheme": "visa",
                    "expire_month": 1,
                    "expire_year": 2039,
                    "gateway_id": "MPGS_GATEWAY_ID",
                    "gateway_type": "MasterCard",
                    "gateway_name": "MasterCard",
                    "type": "card",
                    "service_id": "665f9effa255f5aea5467dc8",
                    "service_name": "Click2PayTest1",
                    "service_type": "ClickToPay",
                    "service_group": "click_to_pay",
                    "vault_token": "37a6a120-9393-42fb-b1da-874a98dc50d9",
                    "vault_type": "session",
                    "items": [],
                    "card_funding_method": "DEBIT"
                },
                "first_name": "Test",
                "last_name": "User",
                "email": "[email protected]",
                "phone": "+61111111111"
            },
            "_3ds": {
                "id": "438413bf-3c28-48a8-9a34-b493d0e424d9",
                "token": "eyJjb250ZW50IjoiPGRpdiBpZD1cInJlZGlyZWN0VG8zZHMxQWNzU2ltcGxlXCIgeG1sbnM9XCJodHRwOi8vd3d3LnczLm9yZy8xOTk5L2h0bWxcIj4gPGlmcmFtZSBpZD1cInJlZGlyZWN0VG8zZHMxRnJhbWVcIiBuYW1lPVwicmVkaXJlY3RUbzNkczFGcmFtZVwiIGhlaWdodD1cIjEwMCVcIiB3aWR0aD1cIjEwMCVcIiA+IDwvaWZyYW1lPiA8Zm9ybSBpZCA9XCJyZWRpcmVjdFRvM2RzMUZvcm1cIiBtZXRob2Q9XCJQT1NUXCIgYWN0aW9uPVwiaHR0cHM6Ly9tdGYuZ2F0ZXdheS5tYXN0ZXJjYXJkLmNvbS9hY3MvVmlzYUFDUy82ZDA4NWVjMy03NmFkLTQzZjctODJjNi02MjRiNWJkYzYxMzhcIiB0YXJnZXQ9XCJyZWRpcmVjdFRvM2RzMUZyYW1lXCI+IDxpbnB1dCB0eXBlPVwiaGlkZGVuXCIgbmFtZT1cIlBhUmVxXCIgdmFsdWU9XCJlQUZWVXR0dXdqQU1mVWZpSDZwcXJ6UkptMEtMVEJDRFRXTTNUUnRJRTI5ZDY5RnF0SVhlQkg4L3A5QmRYaUlmSCtmRVBnNU1qK25PYUxBb2t6eWJtTUxpcG9GWm1FZEp0cDJZNjlYdHdET25xdCtEVlZ3Z0x0NHdyQXRVOElSbEdXelJTS0tKNlVpUE8zU1lDbDVtcjNoUWNKRlRwR2Jad0RwSXQ0b3dEckpLUVJBZXJwZlBTdnFTdTFSeGdaQmlzVndvWVR2U0hZNjhRUmNBT3hPUUJTbXFCVGE0eS9jcFpwWFJLUUpyS1Fqek9xdUtrK0xPRUZnSG9DNTJLcTZxZlRsbUxEME5JbXdHSk5pMllvVjVhZ1UxTUYwRHJOT2pVV3BkVU5Lc3h5UlNYL2lZK21MemtId2M4Z2J4L2Y3ejlCTFpjVFBmM0V5QTZRcUlnZ3FWelczSmgwSWFYSTVkYnl4OFlHMGVnbFIzcG1icmhYRWxPTGM0cDZuUE9kanJwMlpuUUp5bS9xYUFMQzlvSjkxVUhRSTg3dk9NWEZEazRFOE03TGZ6K1oxMk9xeklVK2x5YitSeUx0eVJGRnozZFNHMFNrS09PVDRYcll3R3dQUlZkbGtudWRKdW16TC9ma0cvOXcyT0Y3bUVcIiAvPiA8aW5wdXQgdHlwZT1cImhpZGRlblwiIG5hbWU9XCJUZXJtVXJsXCIgdmFsdWU9XCJodHRwczovL210Zi5nYXRld2F5Lm1hc3RlcmNhcmQuY29tL2NhbGxiYWNrSW50ZXJmYWNlL2dhdGV3YXkvNzFiZWYxM2UyZjkwMTAwZmU4ZTIxMjA0MWI3MWVhM2VkN2YwZmNlMDU1ODcxMTkxNzUxNDAyYzFhN2ZjYWVlNVwiIC8+IDxpbnB1dCB0eXBlPVwiaGlkZGVuXCIgbmFtZT1cIk1EXCIgdmFsdWU9XCJcIiAvPiA8L2Zvcm0+IDxzY3JpcHQgaWQ9XCJhdXRoZW50aWNhdGUtcGF5ZXItc2NyaXB0XCI+IHZhciBlPWRvY3VtZW50LmdldEVsZW1lbnRCeUlkKFwicmVkaXJlY3RUbzNkczFGb3JtXCIpOyBpZiAoZSkgeyBlLnN1Ym1pdCgpOyBpZiAoZS5wYXJlbnROb2RlICE9PSBudWxsKSB7IGUucGFyZW50Tm9kZS5yZW1vdmVDaGlsZChlKTsgfSB9IDwvc2NyaXB0PiA8L2Rpdj4iLCJmb3JtYXQiOiJodG1sIiwiY2hhcmdlXzNkc19pZCI6IjQzODQxM2JmLTNjMjgtNDhhOC05YTM0LWI0OTNkMGU0MjRkOSJ9"
            },
            "logs_migrated": false,
            "status": "pre_authentication_pending",
            "type": "financial",
            "capture": true,
            "authorization": false,
            "archived": false,
            "one_off": true,
            "_source_ip_address": "130.41.2.225",
            "_id": "666bcdeabd42910b78c0be7d",
            "amount": 100,
            "currency": "AUD",
            "company_id": "665f9e972908950f42173ac0",
            "items": [],
            "transactions": [
                {
                    "_3ds": {
                        "gateway_status": "AUTHENTICATION_PENDING",
                        "challenge": true
                    },
                    "_id": "666bcdeabd42910b78c0be80",
                    "status": "complete",
                    "type": "3ds",
                    "amount": 100,
                    "currency": "AUD",
                    "service_logs": [],
                    "created_at": "2024-06-14T04:58:18.665Z",
                    "updated_at": "2024-06-14T04:58:20.750Z",
                    "processed_at": "2024-06-14T04:58:20.750Z"
                }
            ],
            "created_at": "2024-06-14T04:58:18.643Z",
            "updated_at": "2024-06-14T04:58:20.766Z",
            "__v": 1,
            "external_id": "f36279e9-48ca-4a27-afa2-3cc186391b40:af29c67c-144a-4c93-a21d-9d361f24aac1"
        }
    }
}

3. Use the 3DS token generated to render the 3DS canvas in the PowerBoard widget

Using the 3DS Token captured from the previous step, initialise and render the 3DS canvas to the customer

<script src="https://widget.preproduction.powerboard.commbank.com.au/sdk/latest/widget.umd.min.js"></script>

<script>
  var canvas = new cba.Canvas3ds('#widget-3dsecure', resource._3ds.token);        
  canvas.load();
</script>

This will render a 3DS canvas using the tokenised card details from the customer.

PowerBoard's SDK will also provide a 'status' field within the preAuth() API response, see below workflows accordingly:

❗️
IMPORTANT
The below is only based on suggestions and should be relayed accordingly to your relevant business stakeholders.

Status Name	Summary	Suggested Workflow
pre-authenticated	3D-Secure authentication was successful, token id generated and passed back to your application	Proceed with ingesting the token id and process transaction accordingly.
not_authenticated	3D-Secure authentication was rejected and/or declined.	Do not proceed with the transaction.
authentication_not_supported	3D-Secure authentication is not supported by customer’s card issuing bank. Customer's card is not enrolled in 3D-Secure.	As per your business requirements, this transaction will NOT carry 3DSecure benefits as per EMV 3DS - CommBank.
pre_authentication_pending	3D-Secure authentication has not been completed and in a pending state.	Retry 3D Secure authentication, if still pending, route to authentication_not_supported workflow.

4. Event handling

PowerBoard allows for event handling through the Client-SDK, see below event types, examples and recommendations.

Event Name	Description	Example	Example Event Data
chargeAuthSuccess	3DSecure Authentication was successful.	canvas.on("chargeAuthSuccess", function(data) { console.log(data); });	{ "event": "chargeAuthSuccess", "purpose": "secure3d", "message_source": "widget.paydock", "ref_id": "", "widget_id": "f0676880-130a-49ca-8109-0ebbdf944f90", "charge_3ds_id": "f0676880-130a-49ca-8109-0ebbdf944f90", "status": "authenticated" }
chargeAuthReject	3DSecure Authentication was not successful.	canvas.on("chargeAuthReject", function(data) { console.log(data); });	{ "event": "chargeAuthReject", "purpose": "secure3d", "message_source": "widget.paydock", "ref_id": "", "widget_id": "d88db3dd-8c9b-43e6-a6e6-79ff7e8196d6", "charge_3ds_id": "d88db3dd-8c9b-43e6-a6e6-79ff7e8196d6", "status": "not_authenticated" }

5. Sending your transaction to PowerBoard after 3D-Secure Pre-Authentication

Use the 'charge_3ds_id' returned from the chargeAuthSuccess event in your API Charge request.

API Endpoint	https://api.preproduction.powerboard.commbank.com.au/v1/charges
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 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. _3ds.id - string - charge_3ds_id returned in the chargeAuthSuccess event from PowerBoard's Widget. Example: "_3ds.id": "d88db3dd-8c9b-43e6-a6e6-79ff7e8196d6"

Sample request/Response

{
    "amount": "100.00",
    "currency": "AUD",
    "reference": "Transaction1234",
    "_3ds": {
        "id": "YOUR_3DS_ID"
    }
}

{
    "status": 201,
    "error": null,
    "resource": {
        "type": "charge",
        "data": {
            "transfer": {
                "items": []
            },
            "schedule": {
                "stopped": false
            },
            "statistics": {
                "total_refunded_amount": 0,
                "full_refund": false,
                "need_sync": true
            },
            "customer": {
                "payment_source": {
                    "vault_token": "YOUR_SESSION_TOKEN",
                    "type": "card",
                    "card_name": "Test Test",
                    "card_number_bin": "FIRST_6",
                    "card_number_last4": "LAST_4",
                    "card_scheme": "mastercard",
                    "card_funding_method": "CREDIT",
                    "expire_month": 1,
                    "expire_year": 2039,
                    "gateway_id": "YOUR_MPGS_GATEWAY_ID",
                    "gateway_type": "MasterCard",
                    "gateway_name": "MasterCard",
                    "service_id": "665f9effa255f5aea5467dc8",
                    "service_name": "Click2PayTest1",
                    "service_type": "ClickToPay",
                    "service_group": "click_to_pay",
                    "vault_type": "session",
                    "items": []
                }
            },
            "_3ds": {
                "id": "d0d7af9d-340c-4427-a96b-92173632126a",
                "token": "eyJjb250ZW50IjoiPGRpdiBpZD1cInRocmVlZHNDaGFsbGVuZ2VSZWRpcmVjdFwiIHhtbG5zPVwiaHR0cDovL3d3dy53My5vcmcvMTk5OS9odG1sXCIgc3R5bGU9XCIgaGVpZ2h0OiAxMDB2aFwiPiA8Zm9ybSBpZCA9XCJ0aHJlZWRzQ2hhbGxlbmdlUmVkaXJlY3RGb3JtXCIgbWV0aG9kPVwiUE9TVFwiIGFjdGlvbj1cImh0dHBzOi8vbXRmLmdhdGV3YXkubWFzdGVyY2FyZC5jb20vYWNzL21hc3RlcmNhcmQvdjIvcHJvbXB0XCIgdGFyZ2V0PVwiY2hhbGxlbmdlRnJhbWVcIj4gPGlucHV0IHR5cGU9XCJoaWRkZW5cIiBuYW1lPVwiY3JlcVwiIHZhbHVlPVwiZXlKMGFISmxaVVJUVTJWeWRtVnlWSEpoYm5OSlJDSTZJbUZtTWpJNFpUVmlMVFppTldNdE5EQmpZUzA1WldOakxUUXhZelJrTlRsak1ESXhNQ0o5XCIgLz4gPC9mb3JtPiA8aWZyYW1lIGlkPVwiY2hhbGxlbmdlRnJhbWVcIiBuYW1lPVwiY2hhbGxlbmdlRnJhbWVcIiB3aWR0aD1cIjEwMCVcIiBoZWlnaHQ9XCIxMDAlXCIgPjwvaWZyYW1lPiA8c2NyaXB0IGlkPVwiYXV0aGVudGljYXRlLXBheWVyLXNjcmlwdFwiPiB2YXIgZT1kb2N1bWVudC5nZXRFbGVtZW50QnlJZChcInRocmVlZHNDaGFsbGVuZ2VSZWRpcmVjdEZvcm1cIik7IGlmIChlKSB7IGUuc3VibWl0KCk7IGlmIChlLnBhcmVudE5vZGUgIT09IG51bGwpIHsgZS5wYXJlbnROb2RlLnJlbW92ZUNoaWxkKGUpOyB9IH0gPC9zY3JpcHQ+IDwvZGl2PiIsImZvcm1hdCI6Imh0bWwiLCJjaGFyZ2VfM2RzX2lkIjoiZDBkN2FmOWQtMzQwYy00NDI3LWE5NmItOTIxNzM2MzIxMjZhIn0="
            },
            "_id": "66610c072908950f421743bc",
            "logs_migrated": false,
            "status": "complete",
            "type": "financial",
            "capture": true,
            "authorization": false,
            "archived": false,
            "one_off": true,
            "_source_ip_address": "130.41.2.213",
            "amount": 100,
            "currency": "AUD",
            "company_id": "665f9e972908950f42173ac0",
            "items": [],
            "transactions": [
                {
                    "_3ds": {
                        "gateway_status": "AUTHENTICATION_SUCCESSFUL",
                        "challenge": true,
                        "gateway_result": "SUCCESS",
                        "gateway_recommendation": "PROCEED"
                    },
                    "gateway_specific_code": null,
                    "gateway_specific_description": null,
                    "error_message": null,
                    "error_code": null,
                    "status_code": null,
                    "status_code_description": null,
                    "_id": "66610c072908950f421743bf",
                    "status": "complete",
                    "type": "3ds",
                    "amount": 100,
                    "currency": "AUD",
                    "created_at": "2024-06-06T01:08:23.376Z",
                    "updated_at": "2024-06-06T01:09:13.774Z",
                    "processed_at": "2024-06-06T01:08:25.343Z"
                },
                {
                    "type": "sale",
                    "status": "complete",
                    "amount": 100,
                    "currency": "AUD",
                    "gateway_specific_code": null,
                    "gateway_specific_description": null,
                    "error_message": null,
                    "error_code": null,
                    "status_code": null,
                    "status_code_description": null,
                    "_id": "66610c499df8b911e0dc2307",
                    "created_at": "2024-06-06T01:09:29.382Z",
                    "external_id": "61170db5-f35a-4b1e-ab6e-8e5698351698:7ed7758d-a084-4c59-a8eb-82c0b06143c4",
                    "external_reference": "415801186078",
                    "authorization_code": "186078",
                    "processed_at": "2024-06-06T01:09:30.821Z"
                }
            ],
            "created_at": "2024-06-06T01:08:23.349Z",
            "updated_at": "2024-06-06T01:09:30.821Z",
            "__v": 2,
            "external_id": "61170db5-f35a-4b1e-ab6e-8e5698351698:7ed7758d-a084-4c59-a8eb-82c0b06143c4"
        }
    }
}

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. You will also see the Charge presented in the PowerBoard Merchant Dashboard

Click to Pay without 3D Secure 2.0

1. Convert One-Time-Token to Session Token

With the data.token returned from the user Clicking the Continue button, make an API call which converts the data.token to a Session Vault Token.

API Endpoint	https://api.preproduction.powerboard.commbank.com.au/v1/vault/payment_sources
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	token - string - data.token returned from the previous step. vault_type - string - Type of token to be created.

{
    "token":"YOUR_OTT",
    "vault_type": "session"
}

{
    "status": 201,
    "error": null,
    "resource": {
        "type": "payment_source",
        "data": {
            "vault_token": "YOUR_SESSION_TOKEN",
            "type": "card",
            "company_id": "665f9e972908950f42173ac0",
            "card_number_last4": "1118",
            "card_number_bin": "51111111",
            "card_scheme": "mastercard",
            "status": "active",
            "expire_month": 1,
            "expire_year": 2039,
            "created_at": "2024-06-07T01:30:10.150Z",
            "updated_at": "2024-06-07T01:30:29.180Z",
            "_source_ip_address": "130.41.2.209",
            "vault_type": "session"
        }
    }
}

Store the returned ‘vault_token’ for use in the next step.

2. Process the Charge using returned Session Token

Using the Vault_Token returned in the previous step. Charge the Vault Token using the following API call.

API Endpoint	https://api.preproduction.powerboard.commbank.com.au/v1/vault/charges
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 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.. 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.vault_token - string - Token containing stored customer card information customer.payment_source.gateway_id - string - Unique identifier for Payment gateway service in PowerBoard

{
    "amount": "100",
    "currency": "AUD",
    "referemce": "Test_Reference",
    "customer": {
        "first_name": "Test",
        "last_name": "Test",
        "phone": "+61412123123",
        "email": "[email protected]",
        "payment_source": {
            "vault_token": "959d79e2-c80b-4b51-aa5a-0ca604ca96c2",
            "gateway_id": "665f9eac9df8b911e0dbe120"
        }
    }
}

{
    "status": 201,
    "error": null,
    "resource": {
        "type": "charge",
        "data": {
            "transfer": {
                "items": []
            },
            "schedule": {
                "stopped": false
            },
            "statistics": {
                "total_refunded_amount": 0,
                "full_refund": false,
                "need_sync": true
            },
            "customer": {
                "first_name": "Test",
                "last_name": "Test",
                "email": "[email protected]",
                "phone": "+61412123123",
                "reference": "4f339be7.9fc01bc3-0f0b-4630-9c25-0e4787903f20#0a4e0d3.4f339be7.786c2a0fc3adf2597d69c75eb54fcd55726160e5#4f339be7.9fc01bc3-0f0b-4630-9c25-0e4787903f20.1718234288",
                "payment_source": {
                    "vault_token": "959d79e2-c80b-4b51-aa5a-0ca604ca96c2",
                    "type": "card",
                    "card_name": "Test Test",
                    "card_number_bin": "51234500",
                    "card_number_last4": "0008",
                    "card_scheme": "mastercard",
                    "expire_month": 1,
                    "expire_year": 2039,
                    "address_line1": "11 Harbour Street",
                    "address_city": "Sydney",
                    "address_postcode": "2000",
                    "address_state": "NSW",
                    "address_country": "AU",
                    "gateway_id": "665f9eac9df8b911e0dbe120",
                    "gateway_type": "MasterCard",
                    "gateway_name": "MasterCard",
                    "service_id": "665f9effa255f5aea5467dc8",
                    "service_name": "Click2PayTest1",
                    "service_type": "ClickToPay",
                    "service_group": "click_to_pay",
                    "vault_type": "session",
                    "items": [],
                    "card_funding_method": "CREDIT"
                }
            },
            "_id": "666a2d24ea0b4cc082f35c98",
            "type": "financial",
            "amount": 100,
            "currency": "AUD",
            "status": "complete",
            "company_id": "665f9e972908950f42173ac0",
            "capture": true,
            "authorization": false,
            "archived": false,
            "one_off": true,
            "_source_ip_address": "137.83.240.54",
            "items": [],
            "transactions": [
                {
                    "created_at": "2024-06-12T23:20:04.532Z",
                    "type": "sale",
                    "status": "complete",
                    "amount": 100,
                    "currency": "AUD",
                    "_source_ip_address": "137.83.240.54",
                    "gateway_specific_code": null,
                    "gateway_specific_description": null,
                    "error_message": null,
                    "error_code": null,
                    "status_code": null,
                    "status_code_description": null,
                    "include_authorization": false,
                    "initialization_source": "internet",
                    "_id": "666a2d24ea0b4cc082f35c99",
                    "external_id": "151faf52-681f-44b8-9da5-8f2dae802764:be26b934-3903-44bd-a04a-d904b7d437e7",
                    "external_reference": "416423066892",
                    "authorization_code": "066892",
                    "processed_at": "2024-06-12T23:20:05.747Z"
                }
            ],
            "updated_at": "2024-06-12T23:20:05.748Z",
            "created_at": "2024-06-12T23:20:04.535Z",
            "__v": 0,
            "external_id": "151faf52-681f-44b8-9da5-8f2dae802764:be26b934-3903-44bd-a04a-d904b7d437e7"
        }
    }
}

Appendix A) Hiding "Pre-Authentication" Result Placeholder

You may hide the "Pre-Authentication" result placeholder screen by calling the .hide method, see below example.

canvas.hide([saveSize = false, console.log("3D-Secure Widget Hidden")]);

This screen (rendered by PowerBoard) will be hidden.

Click to Pay

Click to Pay

🚧
Before you begin

❗️
Requirements

Steps to Enable in PreProduction Dashboard:

Step 1) Add Click to Pay Registration

📘
Note:

Step 2) Add Click to Pay Service

Steps to Integrate Click to Pay into your Payments ecosystem:

Click to Pay Widget - Recommended Implementation

Key Benefits

Optimised Widget Implementation

Implementation Flow

Best Practices for Widget Optimisation

Alternative Basic Implementation

Widget Event Handlers

Widget Styling Customisation

Recognised User Flow

Unrecognised user flow:

Unregistered user flow:

Manual Card Entry (Guest) flow:

❗️
Note: - When the ‘checkoutCompleted’ event is returned, the Click to Pay summary screen will not automatically disappear. It is the merchant's responsibility to clear the element and or navigate the end-user to a processing screen.

Process Click to Pay Transaction

Click to Pay with 3D Secure 2.0

1. Convert One-Time-Token to Session Token

2. Make a request to the 3DS endpoint using the vault token

3. Use the 3DS token generated to render the 3DS canvas in the PowerBoard widget

❗️
IMPORTANT

4. Event handling

5. Sending your transaction to PowerBoard after 3D-Secure Pre-Authentication

Click to Pay without 3D Secure 2.0

1. Convert One-Time-Token to Session Token

2. Process the Charge using returned Session Token

Appendix A) Hiding "Pre-Authentication" Result Placeholder

Click to Pay

🚧Before you begin

❗️Requirements

Steps to Enable in PreProduction Dashboard:

Step 1) Add Click to Pay Registration

📘Note:

Step 2) Add Click to Pay Service

Steps to Integrate Click to Pay into your Payments ecosystem:

Click to Pay Widget - Recommended Implementation

Key Benefits

Optimised Widget Implementation

Implementation Flow

Best Practices for Widget Optimisation

Alternative Basic Implementation

Widget Event Handlers

Widget Styling Customisation

Recognised User Flow

Unrecognised user flow:

Unregistered user flow:

Manual Card Entry (Guest) flow:

❗️Note: - When the ‘checkoutCompleted’ event is returned, the Click to Pay summary screen will not automatically disappear. It is the merchant's responsibility to clear the element and or navigate the end-user to a processing screen.

Process Click to Pay Transaction

Click to Pay with 3D Secure 2.0

1. Convert One-Time-Token to Session Token

2. Make a request to the 3DS endpoint using the vault token

3. Use the 3DS token generated to render the 3DS canvas in the PowerBoard widget

❗️IMPORTANT

4. Event handling

5. Sending your transaction to PowerBoard after 3D-Secure Pre-Authentication

Click to Pay without 3D Secure 2.0

1. Convert One-Time-Token to Session Token

2. Process the Charge using returned Session Token

Appendix A) Hiding "Pre-Authentication" Result Placeholder

🚧
Before you begin

❗️
Requirements

📘
Note:

❗️
Note: - When the ‘checkoutCompleted’ event is returned, the Click to Pay summary screen will not automatically disappear. It is the merchant's responsibility to clear the element and or navigate the end-user to a processing screen.

❗️
IMPORTANT