Card Payments with Vault Token
This document will guide you on how to correctly integrate card payments using a Vault Token via PowerBoard.
This document will guide you on how to correctly integrate card payments using a Vault Token via PowerBoard.
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:
- 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
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>
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:
| 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', '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_sourcevalue 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 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/json - Content-Type will always be application/json. |
| Request Parameters | token - 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 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/json - Content-Type will always be application/json. |
| Request Parameters | amount - 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 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/json - Content-Type will always be application/json. |
| Request Parameters | token - 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 |
| 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.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.