This document will guide you on how to correctly integrate Authorisation/Capture card payments via PowerBoard.
Important to know
As a merchant, you need to have the Pre-Auth feature enabled in your PowerBoard account before you can use this feature.
Please reach out to our support team if you need help enabling this feature or have any queries.
What is the Purpose of Authorisation (Use Case)?
Authorisation is a process that sets aside funds on a payment card, allowing for a transaction to be completed or cancelled at a later stage. This precautionary measure provides reassurance by ensuring that the customer will have sufficient funds available when the payment is due.
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
- Begin by including PowerBoard's Hosted JavaScript library in your page and creating a container for the PowerBoard widget.
- 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.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>
</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 a PowerBoard Session Vault token using One-Time Token
Use the payment_source returned from the Widget in your session vault API 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: "paymentsource": "c2a69078-110c-4081-a927-167d9d1b2f04". vault_type - _string - Indicates type of token to create. Example: “type:” “session” |
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.
{
"token": "c2a69078-110c-4081-a927-167d9d1b2f04",
"vault_type": "session"
}
{
"status": 201,
"error": null,
"resource": {
"type": "payment_source",
"data": {
"vault_type": "session",
"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 Authorisation with PowerBoard REST API
Use the vault_token returned from the sessionin your API Tokenise request, see below example:
| API Endpoint | https://api.preproduction.powerboard.commbank.com.au/v1/charges?capture=false |
|---|---|
| HTTP Method | POST |
| Query Parameter | capture=false This must be set to allow PowerBoard to create Authorisation and not a Charge |
| 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'. 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. (optional field) customer.first_name - _string - Customer first name. (optional field) customer.last_name - _string - Customer last name. (optional field) customer.phone - string - Customer phone number.(optional field) customer.email - string - Customer email address. (optional field) customer.payment_source.vault_token - string - Token containing stored customer card information customer.payment_source.gateway_id - string - Unique identifier for Payment Processor customer.payment_source.address_line1 - string - Customer address, line 1. (optional field) customer.payment_source.address_line2 - string - Customer address, line 2. (optional field) customer.payment_source.city - string - Customer city. (optional field) customer.payment_source.state - string - Customer state. (optional field) customer.payment_source.postcode - string - Customer postcode. (optional field) customer.payment_source.country - string - Customer country. (optional field) |
Once you have submitted your API Authorisation request, PowerBoard will respond accordingly with a 201 Created. The response including the "_id" should be stored against your database or relevant payments ecosystem.
Note: _id value from the response should be stored against your database or relevant payment ecosystem. This value is required to capture the payment later.
{
"amount": "10.00",
"currency": "AUD",
"reference": "Invoice 123456789",
"customer": {
"first_name": "John",
"last_name": "Citizen",
"phone": "0412123123",
"email": "[email protected]",
"payment_source": {
"vault_token": "c90dbe45-7a23-4f26-9192-336a01e58e59",
"gateway_id": "5dde1f3799cfea21ed2fc942",
"address_line1": "123 Test Street",
"address_line2": "Unit 123",
"address_city": "Sydney",
"address_state": "NSW",
"address_postcode": "2000",
"address_country": "Australia"
}
}
}
{
"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": {
"type": "card",
"gateway_id": "63cf37b142194166721498e9",
"gateway_name": "CommWeb",
"gateway_type": "MasterCard",
"ref_token": "9146465599609659",
"card_number_last4": "1118",
"card_number_bin": "51111111",
"expire_month": 1,
"expire_year": 2039,
"card_scheme": "mastercard",
"items": []
}
},
"type": "financial",
"status": "pending",
"capture": false,
"authorization": true,
"archived": false,
"one_off": true,
"_source_ip_address": "130.41.62.108",
"_id": "64b0869c1e04e51be27f163e",
"amount": 100,
"currency": "AUD",
"items": [],
"transactions": [
{
"type": "sale",
"status": "pending",
"_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": "64b0869c1e04e51be27f163f",
"currency": "AUD",
"amount": 100,
"amount_fee": null,
"amount_surcharge": null,
"amount_original": null,
"created_at": "2023-07-13T23:19:56.279Z",
"external_id": "a2c14d0d-ad02-43ec-9bd3-58465d73aed2:a35e41e2-c28b-43ff-b07b-b428e3b52991",
"external_reference": "319423032474",
"pended_at": "2023-07-13T23:49:57.533Z"
}
],
"company_id": "63cf32a154a870183bf2398a",
"amount_surcharge": null,
"amount_original": null,
"updated_at": "2023-07-13T23:19:57.543Z",
"created_at": "2023-07-13T23:19:56.279Z",
"__v": 0,
"external_id": "a2c14d0d-ad02-43ec-9bd3-58465d73aed2:a35e41e2-c28b-43ff-b07b-b428e3b52991"
}
}
}
Step 5) Capture an Authorisation on PowerBoard
When you, as a merchant, are ready to capture the already authorised funds on a customer's card you will need to call our 'Capture API' to do so.
Supplying an amount will allow you to capture a specified amount of the funds authorised. Supplying no amount will capture the full amount authorised.
| API Endpoint | https://api.preproduction.powerboard.commbank.com.au/v1/charges/{id}/capture |
|---|---|
| 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 - Amount to capture for the transaction (optional) Supplying an amount will allow you to capture a specified amount of the funds authorised. Supplying no amount will capture the full amount authorised. |
{
"amount": "100.00"
}
{
"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": {
"type": "card",
"gateway_id": "63cf37b142194166721498e9",
"gateway_name": "CommWeb",
"gateway_type": "MasterCard",
"ref_token": "9146465599609659",
"card_number_last4": "1118",
"card_number_bin": "51111111",
"expire_month": 1,
"expire_year": 2039,
"card_scheme": "mastercard",
"items": []
}
},
"type": "financial",
"status": "complete",
"capture": true,
"authorization": true,
"archived": false,
"one_off": true,
"_source_ip_address": "130.41.62.108",
"_id": "64b0869c1e04e51be27f163e",
"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": true,
"_id": "64b0869c1e04e51be27f163f",
"currency": "AUD",
"amount": 100,
"amount_fee": null,
"amount_surcharge": null,
"amount_original": null,
"created_at": "2023-07-13T23:19:56.279Z",
"external_id": "a2c14d0d-ad02-43ec-9bd3-58465d73aed2:cf739887-0c2a-49a0-9d00-363a52d78c72",
"external_reference": "319423032474",
"pended_at": "2023-07-13T23:49:57.533Z"
},
{
"type": "capture",
"status": "complete",
"_source_ip_address": "127.0.0.1",
"gateway_specific_code": null,
"gateway_specific_description": null,
"error_message": null,
"error_code": null,
"status_code": null,
"status_code_description": null,
"include_authorization": true,
"_id": "64b08afd1e04e51be27f1645",
"amount": 100,
"currency": "AUD",
"external_id": "a2c14d0d-ad02-43ec-9bd3-58465d73aed2:cf739887-0c2a-49a0-9d00-363a52d78c72",
"amount_fee": null,
"amount_surcharge": null,
"amount_original": null,
"created_at": "2023-07-13T23:38:37.843Z",
"external_reference": "319423032474"
}
],
"company_id": "63cf32a154a870183bf2398a",
"amount_surcharge": null,
"amount_original": null,
"updated_at": "2023-07-13T23:38:39.850Z",
"created_at": "2023-07-13T23:19:56.279Z",
"__v": 1,
"external_id": "a2c14d0d-ad02-43ec-9bd3-58465d73aed2:cf739887-0c2a-49a0-9d00-363a52d78c72"
}
}
}
You will now see the orginial authorisation status updated to complete in the PowerBoard Merchant Dashboard.
Cancel Authorised Transaction
In the event that you need to cancel an authorised transaction, you will need to use our 'cancel authorised' API to do this.
You will need to identify the ChargeID from the initial authroisation transaction in the API endpoint.
| API Endpoint | https://api.preproduction.powerboard.commbank.com.au/v1/charges/{id}/capture |
|---|---|
| HTTP Method | DELETE |
| 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. |
{
"status": 200,
"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": {
"type": "card",
"gateway_id": "63cf37b142194166721498e9",
"gateway_name": "CommWeb",
"gateway_type": "MasterCard",
"ref_token": "9019685872991441",
"card_number_last4": "1118",
"card_number_bin": "51111111",
"expire_month": 1,
"expire_year": 2039,
"card_scheme": "mastercard",
"items": []
}
},
"type": "financial",
"status": "cancelled",
"capture": false,
"authorization": true,
"archived": false,
"one_off": true,
"_source_ip_address": "140.168.79.1",
"_id": "64af90d01e04e51be27f0fbc",
"amount": 100,
"currency": "AUD",
"items": [],
"transactions": [
{
"type": "sale",
"status": "cancelled",
"gateway_specific_code": null,
"gateway_specific_description": null,
"error_message": null,
"error_code": null,
"status_code": null,
"status_code_description": null,
"_id": "64af90d01e04e51be27f0fbd",
"currency": "AUD",
"amount": 100,
"amount_fee": null,
"amount_surcharge": null,
"amount_original": null,
"created_at": "2023-07-13T05:51:12.686Z",
"external_id": "44e6c377-c95b-41af-9441-b0360b2f8bbd:2cf98fb0-c778-4312-9ee0-94613e11a034",
"external_reference": "319405036476",
"pended_at": "2023-07-13T06:21:14.118Z"
},
{
"type": "cancel",
"status": "complete",
"gateway_specific_code": null,
"gateway_specific_description": null,
"error_message": null,
"error_code": null,
"status_code": null,
"status_code_description": null,
"_id": "64af98e61e04e51be27f1019",
"amount": 100,
"currency": "AUD",
"external_id": "44e6c377-c95b-41af-9441-b0360b2f8bbd:2cf98fb0-c778-4312-9ee0-94613e11a034",
"amount_fee": null,
"amount_surcharge": null,
"amount_original": null,
"created_at": "2023-07-13T06:25:42.248Z",
"external_reference": "319406036476"
}
],
"company_id": "63cf32a154a870183bf2398a",
"amount_surcharge": null,
"amount_original": null,
"updated_at": "2023-07-13T06:25:43.721Z",
"created_at": "2023-07-13T05:51:12.686Z",
"__v": 1,
"external_id": "44e6c377-c95b-41af-9441-b0360b2f8bbd:2cf98fb0-c778-4312-9ee0-94613e11a034"
}
}
}
FAQs
The duration for which funds are held in the cardholder's account depends on the financial institution that issued the card. Each card issuer establishes a specific period, known as the authorization expiry period, during which they retain the funds while awaiting the capture transaction. Typically, this period ranges from 5 to 8 processing days. After this timeframe, the authorization is removed from the cardholder's account, and the funds become accessible to the cardholder once again.
No, you cannot refund an Authorised transaction. However, you can cancel it.