Card Payments using a Vault Token

This document will guide you on how to correctly integrate card payments using a Vault Token via PowerBoard.

Card Payments with Vault Token

This document will guide you on how to correctly integrate card payments using a Vault Token via PowerBoard.

vault icon

📘

What is the Vault Token?

Click here to learn about Vault Token.

👍

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:

  1. Login to the PowerBoard Merchant Dashboard.
  2. Click on the ‘My Company’ link and proceed to the ‘API and Security’ heading.
  3. 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

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.

a. Begin by including PowerBoard's Hosted JavaScript library in your page and creating a container for the PowerBoard widget.

b. 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', 'not_configured');
    widget.setEnv("preproduction_cba");
    widget.load();
</script>
  
<div id="widget"></div>
widget

Step 2) Customising your Widget

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

See below methods and their definitions:

MethodDescription
.onFinishInsertAfter the 'finish' event of the widget, the 'payment_source' object will be inserted into the input (selector).
.setEnvMethod to change PowerBoard environments.
.useAutoResizeMethod to change PowerBoard environments.
.setTextsAllows you to set custom texts inside the widget.
.setStylesAllows you to set custom styling for the widget.
.onEvent 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', 'not_configured');

    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

<!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.js"></script>
    <script>
    var widget = new cba.HtmlWidget('#widget', 'YOUR_PUBLIC_KEY', 'not_configured');
  
    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"
}

❗️

Get the payment_source value from the Finish event response


Step 3) Create Vault Token using One-Time-Token with PowerBoard REST API

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

API Endpointhttps://api.preproduction.powerboard.commbank.com.au/v1/vault/payment_sources
HTTP Method
POST
Headersx-user-secret-key- POWERBOARD_SECRET_KEY - This is your PowerBoard API Secret Key.
Content-Type - application/json - Content-Type will always be application/json.
Request Parameterstoken - string - payment source string returned from the widget following the "finish" event. Example: "payment_source": "251985e6-a368-4168-8e1a-bfb30c3e4bab"

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

{
    "token": "251985e6-a368-4168-8e1a-bfb30c3e4bab"
}

{
    "status": 201,
    "error": null,
    "resource": {
        "type": "payment_source",
        "data": {
            "type": "card",
            "_source_ip_address": "54.86.50.139",
            "expire_month": 1,
            "expire_year": 2023,
            "card_name": "John  Citizen",
            "card_number_last4": "4242",
            "card_number_bin": "42424242",
            "card_scheme": "visa",
            "ref_token": "cus_hyyau7dpojJttR",
            "status": "active",
            "created_at": "2021-08-05T07:04:25.974Z",
            "company_id": "5d305bfbfac31b4448c738d7",
            "vault_token": "c90dbe45-7a23-4f26-9192-336a01e58e59",
            "updated_at": "2021-08-05T07:05:56.035Z"
        }
    }
}

Step 4) Process transaction using Vault Token via PowerBoard REST API

You can now utilize the returned "vault_token" to charge the customers card via the PowerBoard API. See below example request and response.

API Endpointhttps://api.preproduction.powerboard.commbank.com.au/v1/charges
HTTP Method
POST
Headersx-user-secret-key- POWERBOARD_SECRET_KEY - This is your PowerBoard API Secret Key.
Content-Type - application/json - Content-Type will always be application/json.
Request Parametersamount - string - Total amount for the transaction.
currency - string - Always set to 'AUD'.
customer.payment_source.vault_token - string - Token containing stored customer card information
customer.payment_source.gateway_id - string - Unique identifier for Payment Processor

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. The vault token can continue to be called upon to charge a customer's card.

{
    "amount": "10.00",
    "currency": "AUD",
    "customer": {
        "payment_source": {
            "vault_token": "c90dbe45-7a23-4f26-9192-336a01e58e59",
            "gateway_id": "5dde1f3799cfea21ed2fc942"
        }
    }
}
{
    "status": 201,
    "error": null,
    "resource": {
        "type": "charge",
        "data": {
            "transfer": {
                "items": []
            },
            "customer": {
                "payment_source": {
                    "type": "card",
                    "card_name": "John Citizen",
                    "card_number_last4": "4242",
                    "card_number_bin": "42424242",
                    "expire_month": 1,
                    "expire_year": 2023,
                    "gateway_id": "5dde1f3799cfea21ed2fc942",
                    "vault_token": "8617374d-2a5f-405b-aa9e-a9e942dd7c95",
                    "card_scheme": "visa",
                    "gateway_name": "CommBank",
                    "gateway_type": "CommBank",
										"card_funding_method": "CREDIT",
                  	"card_issuer": "FISERV SOLUTIONS, LLC",
             
                }
            },
            "status": "complete",
            "capture": true,
            "authorization": false,
            "archived": false,
            "one_off": true,
            "_id": "60a193b2079e3f2cb2d9ba5a",
            "company_id": "5d305bfbfac31b4448c738d7",
            "amount": 10,
            "currency": "AUD",
            "items": [],
            "transactions": [
                {
                    "type": "sale",
                    "status": "complete",
                    "gateway_specific_code": null,
                    "gateway_specific_description": null,
                    "error_message": null,
                    "error_code": null,
                    "status_code": null,
                    "status_code_description": null,
                    "_id": "60a193b2079e3f2cb2d9ba5a",
                    "created_at": "2021-01-21T14:46:10.849Z",
                    "amount": 10,
                    "currency": "AUD",
                    "external_id": "ch_1DC3QJIXZXv8Hpj44W7I00eOr",
                    "remittance_date": "2021-01-22T14:46:10.852Z",
                  	"authorization_code": "821802"
                }
            ],
            "updated_at": "2021-01-21T14:46:11.804Z",
            "created_at": "2021-01-21T14:46:10.852Z",
            "__v": 0,
            "external_id": "ch_1DC3QJIXZXv8Hpj44W7I00eOr"
        }
    }
}

3D Secure using a Vault token

Step 1) Follow the above steps using the JS library to create the PowerBoard widget.

Use the above intialiation steps to create the PowerBoard card forms using our JavaScript Library.

Step 2) Use the OTT returned from the widget to generate a vault token

📘

Note

Creating a customer using our customers endpoint will generate a vault token along with a customer account. We recommend using this if you intend to create a customer with the tokenised card details.

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

API Endpointhttps://api.preproduction.powerboard.commbank.com.au/v1/vault/payment_sources
HTTP Method
POST
Headersx-user-secret-key- POWERBOARD_SECRET_KEY - This is your PowerBoard API Secret Key.
Content-Type - application/json - Content-Type will always be application/json.
Request Parameterstoken - string - payment source string returned from the widget following the "finish" event. Example: "payment_source": "251985e6-a368-4168-8e1a-bfb30c3e4bab"

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

{
    "token": "251985e6-a368-4168-8e1a-bfb30c3e4bab"
}

{
    "status": 201,
    "error": null,
    "resource": {
        "type": "payment_source",
        "data": {
            "type": "card",
            "_source_ip_address": "54.86.50.139",
            "expire_month": 1,
            "expire_year": 2023,
            "card_name": "John  Citizen",
            "card_number_last4": "4242",
            "card_number_bin": "42424242",
            "card_scheme": "visa",
            "ref_token": "cus_hyyau7dpojJttR",
            "status": "active",
            "created_at": "2021-08-05T07:04:25.974Z",
            "company_id": "5d305bfbfac31b4448c738d7",
            "vault_token": "c90dbe45-7a23-4f26-9192-336a01e58e59",
            "updated_at": "2021-08-05T07:05:56.035Z"
        }
    }
}

Step 3) 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
Headersx-user-secret-key- POWERBOARD_SECRET_KEY - This is your PowerBoard API Secret Key.
Content-Type - application/jsonContent - Type will always be application/json.
Request Parametersamount - string - Total amount for the transaction.
currency - string. Always set to 'AUD'.
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

Sample request

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. The resource._3ds.token will need to be captured and used in the Canvas object of the widget to render the canvas.

{
    "amount": "100",
    "currency": "AUD",
    "customer": {
        "payment_source": {
            "vault_token": "VAULT_TOKEN",
            "gateway_id": "GATEWAY_ID"
        }
    },
    "_3ds": {
        "browser_details": {
            "name": "CHROME",
            "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_number_last4": "0008",
                    "card_number_bin": "51234500",
                    "card_scheme": "mastercard",
                    "expire_month": 1,
                    "expire_year": 2039,
                    "gateway_id": "GATEWAY_ID",
                    "gateway_type": "MasterCard",
                    "gateway_name": "MasterCard",
                    "type": "card",
                    "vault_token": "VAULT_TOKEN",
                    "card_number_hash_uuid": "a82b8a86-3d9f-43d5-8034-8f62f678cea6",
                    "items": [],
                  	"card_funding_method": "CREDIT",
                  	"card_issuer": "FISERV SOLUTIONS, LLC",
                  	
                }
            },
            "_3ds": {
                "id": "e139a49a-0858-4af8-a6ae-d4f94c2c992c",
                "token": "eyJjb250ZW50IjoiPGRpdiBpZD1cInRocmVlZHNDaGFsbGVuZ2VSZWRpcmVjdFwiIHhtbG5zPVwiaHR0cDovL3d3dy53My5vcmcvMTk5OS9odG1sXCIgc3R5bGU9XCIgaGVpZ2h0OiAxMDB2aFwiPiA8Zm9ybSBpZCA9XCJ0aHJlZWRzQ2hhbGxlbmdlUmVkaXJlY3RGb3JtXCIgbWV0aG9kPVwiUE9TVFwiIGFjdGlvbj1cImh0dHBzOi8vbXRmLmdhdGV3YXkubWFzdGVyY2FyZC5jb20vYWNzL21hc3RlcmNhcmQvdjIvcHJvbXB0XCIgdGFyZ2V0PVwiY2hhbGxlbmdlRnJhbWVcIj4gPGlucHV0IHR5cGU9XCJoaWRkZW5cIiBuYW1lPVwiY3JlcVwiIHZhbHVlPVwiZXlKMGFISmxaVVJUVTJWeWRtVnlWSEpoYm5OSlJDSTZJakl4TW1JNU1ERTFMV1V3Tm1VdE5EQTRPUzA0WkRBNExXVmpNMk0wTnpGa1pXTTVZeUo5XCIgLz4gPC9mb3JtPiA8aWZyYW1lIGlkPVwiY2hhbGxlbmdlRnJhbWVcIiBuYW1lPVwiY2hhbGxlbmdlRnJhbWVcIiB3aWR0aD1cIjEwMCVcIiBoZWlnaHQ9XCIxMDAlXCIgPjwvaWZyYW1lPiA8c2NyaXB0IGlkPVwiYXV0aGVudGljYXRlLXBheWVyLXNjcmlwdFwiPiB2YXIgZT1kb2N1bWVudC5nZXRFbGVtZW50QnlJZChcInRocmVlZHNDaGFsbGVuZ2VSZWRpcmVjdEZvcm1cIik7IGlmIChlKSB7IGUuc3VibWl0KCk7IGlmIChlLnBhcmVudE5vZGUgIT09IG51bGwpIHsgZS5wYXJlbnROb2RlLnJlbW92ZUNoaWxkKGUpOyB9IH0gPC9zY3JpcHQ+IDwvZGl2PiIsImZvcm1hdCI6Imh0bWwiLCJjaGFyZ2VfM2RzX2lkIjoiZTEzOWE0OWEtMDg1OC00YWY4LWE2YWUtZDRmOTRjMmM5OTJjIn0="
            },
            "logs_migrated": false,
            "status": "pre_authentication_pending",
            "type": "financial",
            "capture": true,
            "authorization": false,
            "archived": false,
            "one_off": true,
            "_source_ip_address": "10.0.0.0",
            "_id": "65b993ce02f40c0ef72d4e54",
            "amount": 100,
            "currency": "AUD",
            "company_id": "649a6edfb848941bea648bd6",
            "items": [],
            "transactions": [
                {
                    "_3ds": {
                        "gateway_status": "AUTHENTICATION_PENDING",
                        "challenge": true
                    },
                    "_id": "65b993ce02f40c0ef72d4e57",
                    "status": "complete",
                    "type": "3ds",
                    "amount": 100,
                    "currency": "AUD",
                    "service_logs": [],
                    "created_at": "2024-01-31T00:26:54.836Z",
                    "updated_at": "2024-01-31T00:26:57.340Z",
                    "amount_fee": null,
                    "processed_at": "2024-01-31T00:26:57.340Z",
                    "authorization_code": "821802"
                }
            ],
            "created_at": "2024-01-31T00:26:54.806Z",
            "updated_at": "2024-01-31T00:26:57.360Z",
            "amount_surcharge": null,
            "amount_original": null,
            "__v": 1,
            "external_id": "13ba6ca9-bb2d-430c-b27a-111407e1c44a:6344246d-cd3f-461e-9c16-934524d22ccf"
        }
    }
}

Step 4) 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.

Step 5) Event handling and charging the customer through PowerBoard

Follow steps 2-4 above to handle the various 3DS statuses returned and to proceed to charge the customer.


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.