👍
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.

You need to have a PayPal account setup as a connected service in PowerBoard Merchant Portal. Click here to go to how to add a service.

The gateway_id - which you can obtain from your Merchant Portal > Services > Connected Services.

🚧
Third-Party Requirements

PayPal connected (sandbox mode) via PowerBoard Dashboard.

PayPal developer account

Sandbox 'personal' PayPal account

Your integration will utilise the following components:

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

Integration Steps

Step 1) Create a PowerBoard 'Wallet' Token (API)

API Endpoint	<https://api.preproduction.powerboard.commbank.com.au/v1/charges/wallet?capture=false>
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 your PayPal 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. customer.first_name - string - Customer First Name. customer.last_name - string - Customer Last Name. customer.email - string - Customer email address. customer.payment_source.gateway_id - string - Unique Gateway ID for your PowerBoard PayPal service.
Query Parameters	capture=false This must be set to allow PowerBoard to create Authorisation and not a Charge

PowerBoard will return a '201 Created' response with the following fields:

{
    "customer": {
        "payment_source": {
            "gateway_id": "63cf464542194166721498ec" //your paypal service gateway id in PowerBoard
        }
    },
    "amount": "1.00",
    "currency": "AUD",
    "reference": "online sales"
}

{
    "status": 201,
    "error": null,
    "resource": {
        "type": "charge",
        "data": {
            "token": "YOUR_WALLET_TOKEN",
            "charge": {
                "_id": "63eaf72830e784778fe10728",
                "amount": 214,
                "currency": "AUD",
                "company_id": "63cf32a154a870183bf2398a",
                "type": "financial",
                "status": "wallet_initialized",
                "capture": true,
                "authorization": false,
                "one_off": true,
                "amount_surcharge": null,
                "amount_original": null,
                "created_at": "2023-02-14T02:51:20.826Z",
                "updated_at": "2023-02-14T02:51:20.826Z",
                "schedule": {
                    "stopped": false
                },
                "archived": false,
                "meta": {},
                "customer": {
                    "last_name": "Transaction",
                    "first_name": "Test",
                    "email": "[email protected]",
                    "payment_source": {
                        "type": "wallet",
                        "wallet_type": "paypal",
                        "gateway_id": "63cf464542194166721498ec",
                        "gateway_name": "PayPal",
                        "gateway_type": "Paypal"
                    }
                },
                "transactions": [],
                "shipping": {},
                "items": []
            }
        }
    }
}

Step 2) Create and initialise the PowerBoard Widget

Embed PowerBoard's Client-SDK in your page.
Create a container for the PowerBoard widget.
Set the PowerBoard Widget environment to 'preproduction_cba'.
Configure cba.WalletButtons class:
- amount_label
- country
  - Always set to: AU
- request_shipping (true/false)
  - Allows for shipping address listed on payer's PayPal account to be included in the PowerBoard transaction.
- pay_later (true / false)
  - Feature toggle for PayPal 'Pay in 4'
Style parameters listed in [PayPal's JavaScript SDK](PayPal's JavaScript SDK reference) reference, valid configurable style parameters:
- layout
  - color
  - shape
  - tagline
  - label
Callbacks
- onUnavailable
  - No wallet buttons available.
- onPaymentSuccessful
  - Payment was successful.
- onPaymentError
  - The payment was not successful.
- onPaymentInReview
  - The payment is in fraud review by the wallet service.
Initialise the Widget with the .load method.

<div id="widget-paypal"></div>

<script src="https://widget.preproduction.powerboard.commbank.com.au/sdk/latest/widget.umd.min.js"></script>

<script>
   let button = new cba.WalletButtons("#widget-paypal", "YOUR WALLET TOKEN",
        {
            amount_label: "Payment Amount",
            country: "AU",
            request_shipping: true,
            pay_later: true,
            style: {
                layout: 'vertical',
                color: 'gold',
                shape: 'pill',
                tagline: false
            },
        })
     button.setEnv('preproduction_cba');
     button.onUnavailable(() => console.log("No wallet buttons available"));
     button.onPaymentSuccessful((data) => console.log("Payment Successful", data));
     button.onPaymentError((data) => console.log("The payment was not successful", data));
     button.onPaymentInReview((data) => console.log("The payment is on fraud review", data));
     button.load();

</script>

After the payment is completed (successfully) the onPaymentSuccessful(data) call-back will trigger.

If the payment was not successful, the onPaymentError(data) call-back will trigger.

onPaymentSuccessful(data) example

{
    "status": 200,
    "error": null,
    "resource": {
        "type": "charge",
        "data": {
            "id": "63eb242930e784778fe10794",
            "amount": 100,
            "currency": "AUD",
            "status": "complete"
        }
    }
}

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

Step 3) Capture an Authorisation on PowerBoard

When you, as a merchant, are ready to capture the already authorised funds from a customer's PayPal account 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": {
					"gateway_id": "63168d40273eef3a501cf89b",
					"gateway_type": "Paypal",
					"gateway_name": "PayPal",
					"type": "wallet",
					"items": [],
					"external_payer_id": "BGGXK6DBNHS7J",
					"wallet_type": "paypal",
					"checkout_email": "[email protected]",
					"checkout_holder": "John Doe"
				}
			},
			"shipping": {
				"address_city": "Melbourne",
				"address_country": "AU",
				"address_postcode": "3001",
				"address_state": "Victoria",
				"address_line1": "1 Cheeseman Ave Brighton East"
			},
			"_id": "66b17615cde6c00f6e9b6580",
			"logs_migrated": false,
			"status": "complete",
			"type": "financial",
			"capture": true,
			"authorization": true,
			"archived": false,
			"one_off": true,
			"_source_ip_address": "130.41.2.209",
			"amount": 1,
			"currency": "AUD",
			"reference": "TESTonlinesales123",
			"company_id": "631580bf11ab9f3a99936d6b",
			"items": [],
			"transactions": [
				{
					"gateway_specific_code": null,
					"gateway_specific_description": null,
					"error_message": null,
					"error_code": null,
					"status_code": null,
					"status_code_description": null,
					"_source_ip_address": "140.168.79.2",
					"include_authorization": false,
					"_id": "66b1762a26b6100f130e1dac",
					"status": "complete",
					"type": "initialization",
					"amount": 1,
					"currency": "AUD",
					"created_at": "2024-08-06T01:02:34.122Z",
					"updated_at": "2024-08-06T01:02:35.940Z",
					"processed_at": "2024-08-06T01:02:35.940Z"
				},
				{
					"gateway_specific_code": null,
					"gateway_specific_description": null,
					"error_message": null,
					"error_code": null,
					"status_code_description": null,
					"_source_ip_address": "140.168.79.2",
					"include_authorization": true,
					"_id": "66b17635833288150064a314",
					"status": "complete",
					"type": "sale",
					"amount": 1,
					"currency": "AUD",
					"transaction_id": null,
					"created_at": "2024-08-06T01:02:45.097Z",
					"updated_at": "2024-08-06T01:02:47.903Z",
					"external_id": "95W56771619052840",
					"external_reference": "5VA26169P5972700X",
					"processed_at": "2024-08-06T01:02:47.903Z",
					"status_code": "created"
				},
				{
					"type": "capture",
					"status": "complete",
					"amount": 1,
					"currency": "AUD",
					"external_id": "95W56771619052840",
					"_source_ip_address": "130.41.2.209",
					"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": "66b1765f9ef8e873bcc56bea",
					"created_at": "2024-08-06T01:03:27.698Z",
					"external_reference": "95W56771619052840",
					"processed_at": "2024-08-06T01:03:30.737Z"
				}
			],
			"created_at": "2024-08-06T01:02:13.009Z",
			"updated_at": "2024-08-06T01:03:30.737Z",
			"__v": 3,
			"external_id": "95W56771619052840"
		}
	}
}

👍
You will now see the original authorisation status updated to complete in the PowerBoard Merchant Dashboard.

Cancel Authorised PayPal 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 authorisation 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": {
          "gateway_id": "63168d40273eef3a501cf89b",
          "gateway_type": "Paypal",
          "gateway_name": "PayPal",
          "type": "wallet",
          "items": [],
          "external_payer_id": "BGGXK6DBNHS7J",
          "wallet_type": "paypal",
          "checkout_email": "[email protected]",
          "checkout_holder": "John Doe"
        }
      },
      "shipping": {
        "address_city": "Melbourne",
        "address_country": "AU",
        "address_postcode": "3001",
        "address_state": "Victoria",
        "address_line1": "1 Cheeseman Ave Brighton East"
      },
      "_id": "66b1756f26b6100f130e1d6b",
      "logs_migrated": false,
      "status": "cancelled",
      "type": "financial",
      "capture": false,
      "authorization": true,
      "archived": false,
      "one_off": true,
      "_source_ip_address": "130.41.2.209",
      "amount": 1,
      "currency": "AUD",
      "reference": "onlinesales123123123123123",
      "company_id": "631580bf11ab9f3a99936d6b",
      "items": [],
      "transactions": [
        {
          "gateway_specific_code": null,
          "gateway_specific_description": null,
          "error_message": null,
          "error_code": null,
          "status_code": null,
          "status_code_description": null,
          "_id": "66b1759726b6100f130e1d82",
          "status": "complete",
          "type": "initialization",
          "amount": 1,
          "currency": "AUD",
          "created_at": "2024-08-06T01:00:07.388Z",
          "updated_at": "2024-08-06T01:00:09.984Z",
          "processed_at": "2024-08-06T01:00:09.984Z"
        },
        {
          "gateway_specific_code": null,
          "gateway_specific_description": null,
          "error_message": null,
          "error_code": null,
          "status_code_description": null,
          "_id": "66b175c3cde6c00f6e9b6567",
          "status": "cancelled",
          "type": "sale",
          "amount": 1,
          "currency": "AUD",
          "transaction_id": null,
          "created_at": "2024-08-06T01:00:51.525Z",
          "updated_at": "2024-08-06T01:00:54.096Z",
          "external_id": "6EM9028223266570P",
          "external_reference": "6EM9028223266570P",
          "processed_at": "2024-08-06T01:00:54.096Z",
          "status_code": "created"
        },
        {
          "type": "cancel",
          "status": "complete",
          "amount": 1,
          "currency": "AUD",
          "external_id": "6EM9028223266570P",
          "gateway_specific_code": null,
          "gateway_specific_description": null,
          "error_message": null,
          "error_code": null,
          "status_code": null,
          "status_code_description": null,
          "_id": "66b178a81bb2337b2c783140",
          "created_at": "2024-08-06T01:13:12.992Z",
          "processed_at": "2024-08-06T01:13:14.952Z"
        }
      ],
      "created_at": "2024-08-06T00:59:27.853Z",
      "updated_at": "2024-08-06T01:13:14.952Z",
      "__v": 3,
      "external_id": "80W20703FN703463E"
    }
  }
}

PayPal with Auth/Capture

PayPal with Auth/Capture

👍
Before you begin

🚧
Third-Party Requirements

Integration Steps

Step 1) Create a PowerBoard 'Wallet' Token (API)

Step 2) Create and initialise the PowerBoard Widget

onPaymentSuccessful(data) example

Step 3) Capture an Authorisation on PowerBoard

👍

Cancel Authorised PayPal Transaction

PayPal with Auth/Capture

👍Before you begin

🚧Third-Party Requirements

Integration Steps

Step 1) Create a PowerBoard 'Wallet' Token (API)

Step 2) Create and initialise the PowerBoard Widget

onPaymentSuccessful(data) example

Step 3) Capture an Authorisation on PowerBoard

👍

Cancel Authorised PayPal Transaction

👍
Before you begin

🚧
Third-Party Requirements