Customers
This document will guide you on how to correctly Create and Charge a customer via PowerBoard.
This document will guide you on how to correctly Create and Charge a customer via PowerBoard.
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
<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', '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.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.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.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 customer using the PowerBoard API
Use the payment_source returned from the Widget in your Create Customer API request, see below example:
Go to the charge endpoint page.
| API Endpoint | https://api.preproduction.powerboard.commbank.com.au/v1/customers |
|---|---|
| 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 | 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". first_name - _string - Customer first name. last_name - string - Customer last name. phone - string - Customer phone number. email - string - Customer email address. |
Sample body
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.
{
"first_name": "John",
"last_name": "Customer",
"email": "[email protected]",
"phone": "+61111111111",
"reference": "Customer 1",
"token": "b243799c-c9d6-43b8-80aa-689fc8179927"
}
{
"status": 201,
"error": null,
"resource": {
"type": "customer",
"data": {
"statistics": {
"successful_transactions": 0,
"total_collected_amount": 0
},
"_check_expire_date": false,
"archived": false,
"_source_ip_address": "130.41.62.108",
"_id": "64b09a3d1e04e51be27f16c5",
"company_id": "63cf32a154a870183bf2398a",
"email": "[email protected]",
"first_name": "John",
"last_name": "Customer",
"phone": "+61111111111",
"reference": "Customer 1",
"default_source": "64b09a341e04e51be27f16c2",
"_service": {
"default_gateway_id": "63cf37b142194166721498e9"
},
"payment_sources": [
{
"type": "card",
"_id": "64b09a341e04e51be27f16c2",
"expire_month": 1,
"expire_year": 2039,
"card_name": "John Customer",
"card_scheme": "mastercard",
"card_number_last4": "1118",
"card_number_bin": "51111111",
"ref_token": "9191664642213170",
"status": "active",
"created_at": "2023-07-14T00:43:32.375Z",
"gateway_id": "63cf37b142194166721498e9",
"gateway_type": "MasterCard",
"gateway_name": "CommWeb",
"vault_token": "b944dfb0-35f4-47d6-a306-2b79cebf34f3",
"updated_at": "2023-07-14T00:43:41.169Z"
}
],
"payment_destinations": [],
"updated_at": "2023-07-14T00:43:41.170Z",
"created_at": "2023-07-14T00:43:41.170Z",
"__v": 0
}
}
}
Once this process has been completed a new Customer will be created under your PowerBoard Merchant Dashboard along with a Vault Token. You can also view the customer along with their Payment Souce in the PowerBoard Merchant Dashboard
Step 4) Process Charge using Customer ID via PowerBoard API
You can utilize the returned "_id' from the previous step to process a charge.
Go to the charge endpoint page.
| 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 subscription transaction. currency - string. Always set to 'AUD'. customer_id - string - The customer _id string returned from the widget following the "finish" event. |
Sample body
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.
{
"amount":"100",
"currency":"AUD",
"customer_id":"5e4bfbd86d244b438451fbd7"
}
{
"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": {
"source_id": "64b09a341e04e51be27f16c2",
"type": "card",
"card_name": "John Customer",
"card_number_bin": "51111111",
"card_number_last4": "1118",
"card_scheme": "mastercard",
"expire_month": 1,
"expire_year": 2039,
"gateway_id": "63cf37b142194166721498e9",
"vault_token": "b944dfb0-35f4-47d6-a306-2b79cebf34f3",
"ref_token": "9191664642213170",
"items": [],
"gateway_name": "CommWeb",
"gateway_type": "MasterCard"
},
"customer_id": "64b09a3d1e04e51be27f16c5",
"first_name": "John",
"last_name": "Customer",
"phone": "+61111111111",
"email": "[email protected]",
"reference": "Customer 1"
},
"type": "financial",
"status": "complete",
"capture": true,
"authorization": false,
"archived": false,
"one_off": true,
"_source_ip_address": "130.41.62.108",
"_id": "64b0aa431e04e51be27f16cf",
"company_id": "63cf32a154a870183bf2398a",
"amount": 100,
"currency": "AUD",
"items": [],
"transactions": [
{
"type": "sale",
"status": "complete",
"_source_ip_address": "130.41.62.108",
"gateway_specific_code": null,
"gateway_specific_description": null,
"error_message": null,
"error_code": null,
"status_code": null,
"status_code_description": null,
"include_authorization": false,
"_id": "64b0aa431e04e51be27f16d0",
"created_at": "2023-07-14T01:52:03.621Z",
"amount": 100,
"currency": "AUD",
"amount_fee": null,
"amount_surcharge": null,
"amount_original": null,
"external_id": "b150c110-c29d-4c9f-a01d-a5620e04266a:81d1a982-3d9a-4ceb-89b5-297841d482c7",
"external_reference": "319501000027"
}
],
"amount_surcharge": null,
"amount_original": null,
"updated_at": "2023-07-14T01:52:05.315Z",
"created_at": "2023-07-14T01:52:03.643Z",
"__v": 0,
"external_id": "b150c110-c29d-4c9f-a01d-a5620e04266a:81d1a982-3d9a-4ceb-89b5-297841d482c7"
}
}
}
Additionally, you will see the charge appear in the PowerBoard Merchant Dashboard.
Modifying Customer Details
Supply the Customer ID for the customer who's details you would like to update in the API Endpoint.
| API Endpoint | https://api.preproduction.powerboard.commbank.com.au/v1/customers/: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 customer to be modified |
| Request Parameters | 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. first_name - _string - Customer first name. last_name - _string - Customer last name. phone - string - Customer phone number. email - string - Customer email address. |
{
"first_name": "Customer"
}
{
"status": 200,
"error": null,
"resource": {
"type": "customer",
"data": {
"_service": {
"default_gateway_id": "63cf37b142194166721498e9"
},
"statistics": {
"successful_transactions": 1,
"total_collected_amount": 100,
"currency": {
"AUD": {
"count": 1,
"total_amount": 100
}
}
},
"_check_expire_date": false,
"archived": false,
"_source_ip_address": "130.41.62.108",
"_id": "64b09a3d1e04e51be27f16c5",
"company_id": "63cf32a154a870183bf2398a",
"email": "[email protected]",
"first_name": "Customer",
"last_name": "Customer",
"phone": "+61111111111",
"reference": "Customer 1",
"default_source": "64b0d47261433926cd731e5e",
"payment_sources": [
{
"type": "card",
"_id": "64b09a341e04e51be27f16c2",
"expire_month": 1,
"expire_year": 2039,
"card_name": "John Customer",
"card_scheme": "mastercard",
"card_number_last4": "1118",
"card_number_bin": "51111111",
"ref_token": "9191664642213170",
"status": "active",
"created_at": "2023-07-14T00:43:32.375Z",
"gateway_id": "63cf37b142194166721498e9",
"gateway_type": "MasterCard",
"gateway_name": "CommWeb",
"vault_token": "b944dfb0-35f4-47d6-a306-2b79cebf34f3",
"updated_at": "2023-07-14T05:00:35.588Z"
},
{
"type": "card",
"_id": "64b0c97361433926cd731e43",
"vault_token": "fe9a7c8f-34e9-41fa-a7c8-80f84bd5356a",
"gateway_id": "63cf37b142194166721498e9",
"card_name": "Test Customer",
"expire_month": 1,
"expire_year": 2029,
"card_number_last4": "0026",
"card_scheme": "visa",
"ref_token": "9556554593532893",
"status": "active",
"created_at": "2023-07-14T04:05:07.513Z",
"updated_at": "2023-07-14T05:00:35.588Z"
},
{
"type": "card",
"_id": "64b0cee061433926cd731e54",
"vault_token": "6670fdf3-56cf-4cea-a8cd-dab230787b2d",
"gateway_id": "63cf37b142194166721498e9",
"card_name": "Test Customer",
"expire_month": 1,
"expire_year": 2039,
"card_number_last4": "0008",
"card_scheme": "mastercard",
"ref_token": "9994820265495069",
"status": "active",
"created_at": "2023-07-14T04:28:16.914Z",
"updated_at": "2023-07-14T05:00:35.589Z"
},
{
"type": "card",
"_id": "64b0d0a461433926cd731e57",
"gateway_id": "63cf37b142194166721498e9",
"vault_token": "6670fdf3-56cf-4cea-a8cd-dab230787b2d",
"card_name": "Test Customer",
"expire_month": 1,
"expire_year": 2039,
"card_number_last4": "0008",
"card_scheme": "mastercard",
"ref_token": "9330174694819124",
"status": "active",
"created_at": "2023-07-14T04:35:48.735Z",
"updated_at": "2023-07-14T05:00:35.589Z"
},
{
"type": "card",
"_id": "64b0d2cd1e04e51be27f17c6",
"vault_token": "6670fdf3-56cf-4cea-a8cd-dab230787b2d",
"gateway_id": "63cf37b142194166721498e9",
"card_name": "Test Customer",
"expire_month": 1,
"expire_year": 2039,
"card_number_last4": "0008",
"card_scheme": "mastercard",
"ref_token": "9271203793251532",
"status": "active",
"created_at": "2023-07-14T04:45:01.309Z",
"updated_at": "2023-07-14T05:00:35.589Z"
},
{
"type": "card",
"_id": "64b0d47261433926cd731e5e",
"gateway_id": "63cf37b142194166721498e9",
"vault_token": "b944dfb0-35f4-47d6-a306-2b79cebf34f3",
"card_name": "John Customer",
"expire_month": 1,
"expire_year": 2039,
"card_number_last4": "1118",
"card_scheme": "mastercard",
"ref_token": "9801682820321443",
"status": "active",
"created_at": "2023-07-14T04:52:02.160Z",
"updated_at": "2023-07-14T05:00:35.589Z"
}
],
"payment_destinations": [],
"updated_at": "2023-07-14T05:00:35.590Z",
"created_at": "2023-07-14T00:43:41.170Z",
"__v": 5
}
}
}
Adding a new customer payment source
Step 1) Generate One Time Token (OTT)
Please Reference steps 1 and 2 in this guide to see how to generate a One-Time-Token.
Step 2) Tokenize Customer Card details using OTT.
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/jsonContent - Type will always be application/json. |
| Request Parameters | token - string - payment source string returned from the widget following the "finish" event. Example: "payment_source": "c2a69078-110c-4081-a927-167d9d1b2f04". |
{
"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) Add Vault Token to Customer as a Payment Source
| API Endpoint | https://api.preproduction.powerboard.commbank.com.au/v1/customers/: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 customer to be modified |
| Request Parameters | gateway_id - string - The ServiceID of the gateway of which they payments will be processed through vault_token - string - vault_token returned from tokenize request |
{
"payment_source": {
"gateway_id": "63cf37b142194166721498e9",
"vault_token": "6670fdf3-56cf-4cea-a8cd-dab230787b2d"
}
}
{
"status": 200,
"error": null,
"resource": {
"type": "customer",
"data": {
"_service": {
"default_gateway_id": "63cf37b142194166721498e9"
},
"statistics": {
"successful_transactions": 1,
"total_collected_amount": 100,
"currency": {
"AUD": {
"count": 1,
"total_amount": 100
}
}
},
"_check_expire_date": false,
"archived": false,
"_source_ip_address": "130.41.62.108",
"_id": "64b09a3d1e04e51be27f16c5",
"company_id": "63cf32a154a870183bf2398a",
"email": "[email protected]",
"first_name": "John",
"last_name": "Customer",
"phone": "+61111111111",
"reference": "Customer 1",
"default_source": "64b0d47261433926cd731e5e",
"payment_sources": [
{
"type": "card",
"_id": "64b09a341e04e51be27f16c2",
"expire_month": 1,
"expire_year": 2039,
"card_name": "John Customer",
"card_scheme": "mastercard",
"card_number_last4": "1118",
"card_number_bin": "51111111",
"ref_token": "9191664642213170",
"status": "active",
"created_at": "2023-07-14T00:43:32.375Z",
"gateway_id": "63cf37b142194166721498e9",
"gateway_type": "MasterCard",
"gateway_name": "CommWeb",
"vault_token": "b944dfb0-35f4-47d6-a306-2b79cebf34f3",
"updated_at": "2023-07-14T04:52:02.185Z"
},
{
"type": "card",
"_id": "64b0c97361433926cd731e43",
"vault_token": "fe9a7c8f-34e9-41fa-a7c8-80f84bd5356a",
"gateway_id": "63cf37b142194166721498e9",
"card_name": "Test Customer",
"expire_month": 1,
"expire_year": 2029,
"card_number_last4": "0026",
"card_scheme": "visa",
"ref_token": "9556554593532893",
"status": "active",
"created_at": "2023-07-14T04:05:07.513Z",
"updated_at": "2023-07-14T04:52:02.185Z"
},
{
"type": "card",
"_id": "64b0cee061433926cd731e54",
"vault_token": "6670fdf3-56cf-4cea-a8cd-dab230787b2d",
"gateway_id": "63cf37b142194166721498e9",
"card_name": "Test Customer",
"expire_month": 1,
"expire_year": 2039,
"card_number_last4": "0008",
"card_scheme": "mastercard",
"ref_token": "9994820265495069",
"status": "active",
"created_at": "2023-07-14T04:28:16.914Z",
"updated_at": "2023-07-14T04:52:02.185Z"
},
{
"type": "card",
"_id": "64b0d0a461433926cd731e57",
"gateway_id": "63cf37b142194166721498e9",
"vault_token": "6670fdf3-56cf-4cea-a8cd-dab230787b2d",
"card_name": "Test Customer",
"expire_month": 1,
"expire_year": 2039,
"card_number_last4": "0008",
"card_scheme": "mastercard",
"ref_token": "9330174694819124",
"status": "active",
"created_at": "2023-07-14T04:35:48.735Z",
"updated_at": "2023-07-14T04:52:02.185Z"
},
{
"type": "card",
"_id": "64b0d2cd1e04e51be27f17c6",
"vault_token": "6670fdf3-56cf-4cea-a8cd-dab230787b2d",
"gateway_id": "63cf37b142194166721498e9",
"card_name": "Test Customer",
"expire_month": 1,
"expire_year": 2039,
"card_number_last4": "0008",
"card_scheme": "mastercard",
"ref_token": "9271203793251532",
"status": "active",
"created_at": "2023-07-14T04:45:01.309Z",
"updated_at": "2023-07-14T04:52:02.185Z"
},
{
"type": "card",
"_id": "64b0d47261433926cd731e5e",
"gateway_id": "63cf37b142194166721498e9",
"vault_token": "b944dfb0-35f4-47d6-a306-2b79cebf34f3",
"card_name": "John Customer",
"expire_month": 1,
"expire_year": 2039,
"card_number_last4": "1118",
"card_scheme": "mastercard",
"ref_token": "9801682820321443",
"status": "active",
"created_at": "2023-07-14T04:52:02.160Z",
"updated_at": "2023-07-14T04:52:02.185Z"
}
],
"payment_destinations": [],
"updated_at": "2023-07-14T04:52:02.185Z",
"created_at": "2023-07-14T00:43:41.170Z",
"__v": 5
}
}
}