Card Payments with Authorisation/Capture flow

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:

  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

  • 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:

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.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_source value 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 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/jsonContent - Type will always be application/json.
Request Parameterstoken - 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 Endpointhttps://api.preproduction.powerboard.commbank.com.au/v1/charges?capture=false
HTTP Method
POST
Query Parametercapture=false
This must be set to allow PowerBoard to create Authorisation and not a Charge
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'.
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 Endpointhttps://api.preproduction.powerboard.commbank.com.au/v1/charges/{id}/capture
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 - 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 Endpointhttps://api.preproduction.powerboard.commbank.com.au/v1/charges/{id}/capture
HTTP Method
DELETE
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.
{
    "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.