POWERBOARD DEVELOPER HUB
PowerBoard Status PagePowerBoard Merchant Portal

Zip

This document will guide you on how to correctly integrate Zip with 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:

  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.

🚧

Third-Party Requirements

Your integration will utilise the following components:

  • PowerBoard Client-SDK ('Widget')
  • PowerBoard REST API

Integration Steps

Step 1) Create and initialise the PowerBoard Widget

Embed PowerBoard's Client-SDK on your page.

Create a button container for the PowerBoard widget.

<script src="https://widget.preproduction.powerboard.commbank.com.au/sdk/latest/widget.umd.min.js"></script>
 
<button type="button" id="button-zip">Click to launch ZipPay!</button>

Step 2) Configure Client-SDK

Configure the following parameters within the cba.ZipmoneyCheckoutButton class:

  • setBackdropDescription
    • Description which can be shown in the checkout page.
  • setBackdropTitle
    • Title which can be shown in overlay of the checkout page.
  • setEnv('preproduction_cba')
    • Sets Client-SDK ('Widget') to PowerBoard Pre-Production (test) environment.
<script src="https://widget.preproduction.powerboard.commbank.com.au/sdk/latest/widget.umd.min.js"></script>
 
<button type="button" id="button-zip">Click to launch ZipPay!</button>

<script>
var button = new cba.ZipmoneyCheckoutButton('#button-zip', 'YOUR_PUBLIC_KEY', 'GATEWAY_ID');
 
button.setBackdropDescription('PowerBoard Zip Demo');
button.setBackdropTitle('Zip Transaction');
button.setEnv('preproduction_cba');
</script>

Step 3) Event Handling

PowerBoard allows for event handling through the Client-SDK, please see below valid event types and examples.

Event NameExample
clickbutton.on('click', function (data) {
console.log('click');
});
popupRedirectbutton.on('popupRedirect', function (data) {
console.log('popupRedirect');
});
acceptedbutton.on('accepted', function (data) {
console.log('accepted');
});
finishbutton.on('finish', function (data) {
console.log('finish event', data);
});
errorbutton.on('error', function (data) {
console.log('error');
});
closebutton.on('close', function(data) {
console.log('close');
});
<script src="https://widget.preproduction.powerboard.commbank.com.au/sdk/latest/widget.umd.min.js"></script>
 
<button type="button" id="button-zip">Click to launch ZipPay!</button>

<script>
var button = new cba.ZipmoneyCheckoutButton('#button-zip', 'YOUR_PUBLIC_KEY', 'GATEWAY_ID');
 
button.setBackdropDescription('PowerBoard Zip Demo');
button.setBackdropTitle('Zip Transaction');
button.setEnv('preproduction_cba');
 
button.on('click', function (data) {
    console.log('click');
});
 
button.on('finish', function (data) {
    console.log('finish event', data);
});
 
button.on('popupRedirect', function (data) {
    console.log('popupRedirect');
});
 
button.on('accepted', function (data) {
    console.log('accepted');
});
 
button.on('error', function (data) {
    console.log('error');
});
 
button.on('close', function (data) {
    console.log('close');
});
</script>

Step 4) Construct meta information for the checkout page

Use .setMeta method to provide information about your Zip transaction with the following parameters:

FieldRequiredTypeDescription
first_nameYstringCustomer first name
last_nameYstringCustomer last name
tokenizeNstringTokenize transaction flag
emailYstringCustomer email address
genderNstringCustomer gender
charge.amountYstringTotal amount for the transaction
charge.currencyYstringAlways set to 'AUD'
shipping_address.first_nameYstringShipping first name
shipping_address.last_nameYstringShipping last name
shipping_address.line1YstringShipping Address, line 1
shipping_address.line2YstringShipping Address, line 2
shipping_address.countryYstringShipping Address, country
shipping_address.postcodeYstringShipping Address, postcode
shipping_address.cityYstringShipping Address, city
shipping_address.stateYstringShipping Address, state
billing_address.first_nameYstringBilling first name
billing_address.last_nameYstringBilling last name
billing_address.line1YstringBilling Address, line 1
billing_address.line2YstringBilling Address, line 2
billing_address.countryYstringBilling Address, country
billing_address.postcodeYstringBilling Address, postcode
billing_address.cityYstringBilling Address, city
billing_address.stateYstringBilling Address, state
items.nameYstringName of item within the charge
items.amountYstringAmount of item within the charge
items.quantityYstringQuantity of items within the charge
items.referenceYstringReference for items within the charge
<script src="https://widget.preproduction.powerboard.commbank.com.au/sdk/latest/widget.umd.js"></script>
 
<button type="button" id="button-zip">Click to launch ZipPay!</button>

<script>
var button = new cba.ZipmoneyCheckoutButton('#button-zip', 'YOUR_PUBLIC_KEY', 'GATEWAY_ID');
 
button.setBackdropDescription('PowerBoard Zip Demo');
button.setBackdropTitle('Zip Transaction');
button.setEnv('preproduction_cba');
 
button.on('click', function (data) {
    console.log('click');
});
 
button.on('popupRedirect', function (data) {
    console.log('popupRedirect');
});
 
button.on('accepted', function (data) {
    console.log('accepted');
});
 
button.on('error', function (data) {
    console.log('error');
});
 
button.on('close', function (data) {
    console.log('close');
});
 
button.setMeta({
    "first_name": "John",
    "tokenize": false,
    "last_name": "Citizen",
    "email": "[email protected]",
    "gender": "male",
    "charge": {
        "amount": "100.00",
        "currency": "AUD",
        "shipping_address": {
            "first_name": "John",
            "last_name": "Citizen",
            "line1": "123456 Test Street",
            "line2": "Unit 1",
            "country": "AU",
            "postcode": "2000",
            "city": "Sydney",
            "state": "NSW"
        },
        "billing_address": {
            "first_name": "John",
            "last_name": "Citizen",
            "line1": "123 Test Street",
            "line2": "Unit 123",
            "country": "AU",
            "postcode": "2000",
            "city": "Sydney",
            "state": "NSW"
        },
        "items": [{
            "name": "Shoes 1",
            "amount": "50.00",
            "quantity": 1,
            "reference": "My_Example_Merchant_Reference_01"
        }, {
            "name": "Shoes 2",
            "amount": "50.00",
            "quantity": 1,
            "reference": "My_Example_Merchant_Reference_02"
        }]
    }
});
</script>

Step 5) Send Payment Token to PowerBoard's API

The PowerBoard Client-SDK will trigger the 'finish' event once the end-user has completed the Zip workflow (see below).

FieldDescription
payment_source_tokenPowerBoard payment source token used in Charge API request.
checkout_emailPayer's email address listed on Zip account.
checkout_holderPayer's name listed on Zip account.
gateway_typePowerBoard gateway service type.
{
    "payment_source_token": "POWERBOARD_PAYMENT_SOURCE_TOKEN",
    "checkout_email": "[email protected]",
    "checkout_holder": "John Citizen",
    "gateway_type": "Zipmoney"
}

Use the 'Payment_Source_Token' from the 'finish' event within your Charge API request.

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/jsonContent - Type will always be application/json.
Request Parametersamount - string - Total amount for the transaction.
transactions.currency - string - Always set to 'AUD'.
token - string - payment_source_token returned from the 'finish' event. Example: "payment_source": "c2a69078-110c-4081-a927-167d9d1b2f04"

Charge Request with Zip Payment Source Token

PowerBoard will respond with a '201 Created', respectively. This response should be stored against your database or relevant payments ecosystem.

{
    "amount": "10.00",
    "currency": "AUD",
    "token": "251985e6-a368-4168-8e1a-bfb30c3e4bab"
}

{
    "_id": "63ec23f1a412be2c507ced2a",
    "transfer": {
        "items": []
    },
    "schedule": {
        "stopped": false
    },
    "statistics": {
        "total_refunded_amount": 0,
        "full_refund": false,
        "need_sync": true
    },
    "customer": {
        "payment_source": {
            "type": "checkout",
            "gateway_id": "63cf467933020e1cd63006d1",
            "gateway_name": "Zipmoney",
            "gateway_type": "Zipmoney",
            "ref_token": "type:Y2hlY2tvdXRfaWQ=.token:Y29fMVpQQ0xIaVBrVmhXMlM2c1FDa3VG",
            "address_line1": "123 Test Street",
            "address_line2": "Unit 123",
            "address_city": "Sydney",
            "address_postcode": "2000",
            "address_state": "NSW",
            "address_country": "AU"
        },
        "first_name": "John",
        "last_name": "Citizen",
        "email": "[email protected]"
    },
    "shipping": {
        "address_line1": "123 Test Street",
        "address_line2": "Unit 123",
        "address_country": "AU",
        "address_postcode": "2000",
        "address_city": "Sydney",
        "address_state": "NSW"
    },
    "type": "financial",
    "status": "complete",
    "capture": true,
    "authorization": false,
    "archived": false,
    "one_off": true,
    "_source_ip_address": "0.0.0.0",
    "amount": 0.4,
    "currency": "AUD",
    "items": [],
    "company_id": "63cf32a154a870183bf2398a",
    "amount_surcharge": null,
    "amount_original": null,
    "updated_at": "2023-02-15T00:14:43.454Z",
    "created_at": "2023-02-15T00:14:41.968Z",
    "__v": 0,
    "external_id": "ch_gyeg1v245884vek"
}

Additionally, you will see the charge appear in the PowerBoard Merchant Dashboard.

PowerBoard charge logs