Email Notifications

This document will guide you on how to correctly integrate Email Notifications within PowerBoard.

Notifications - Emails

This document will guide you on how to correctly integrate Email Notifications within PowerBoard.

subscription-icon

📘

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 REST API

Overview

Use PowerBoards Notification service to get real-time updates on transaction events within your integration.


Types of events

Below is a list of events that PowerBoard currently send.

Event nameDescription
transaction_successOccurs when a transaction is processed successfully
transaction_failureOccurs when a transaction is processed unsuccessfully
subscription_transactionOccurs when a transaction is processed successfully via a subscription
subscription_transaction_failureOccurs when a transaction is processed unsuccessfully via a subscription
subscription_creation_successOccurs when a subscription is created successfully
subscription_creation_failureOccurs when a subscription is created unsuccessfully
subscription_updatedOccurs when a subscription was updated
subscription_finishedOccurs when a subscription has finished
subscription_failedOccurs when a subscription has failed
refund_requestedOccurs when a refund is requested
refund_successfulOccurs when a refund is processed successfully
refund_failureOccurs when a refund is processed unsuccessfully
card_expiration_warningOccurs when a stored card will be expiring in 1 month
standalone_fraud_check_in_reviewOccurs when a standalone Fraud Check is In review
standalone_fraud_check_successOccurs when a standalone Fraud Check is successful
standalone_fraud_check_failedOccurs when a standalone Fraud Check has failed
standalone_fraud_check_in_review_approvedOccurs when a standalone Fraud Check in review has been approved
standalone_fraud_check_in_review_declinedOccurs when a standalone Fraud Check in Review has been declined

Integration Steps

Steps to integrate notifications via Email

Step 1) Identify the required events for your integration.

You can find a list of them above.


Step 2) Create an Email notification template via the PowerBoard API.

Email notifications require a pre-defined template that will outline what will be included in the body of the notification. This can be developed using HTML and via our variables captured from the respective transaction.

We have a number of variables available that can be included in the template:

Variable
{{AMOUNT}}
{{BULK_REFERENCE}}
{{CHARGE_DESCRIPTION}}
{{CHARGE_ID}}
{{CHARGE_REFERENCE}}
{{CREATED_AT}}
{{CURRENCY}}
{{CUSTOMER_REFERENCE}}
{{EMAIL}}
{{FIRST_NAME}}
{{LAST_NAME}}
{{PHONE}}
{{TRANSACTION_AMOUNT}}
{{UPDATED_AT}}

API Request details:

API Endpointhttps://api.preproduction.powerboard.commbank.com.au/v1/notifications/templates)
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 Parameterslabel - string - Name of template.
body - string - Use custom text or/and predefined variables, in which PowerBoard automatically pulls values from customer, charge or subscription data objects.
notification_event - string - Event to trigger a notification.
type - string - Allowed values: message, fields. Default is message.
html - boolean - Body could be in html or plain text format. Allowed values true, false, default is false.
{
    "label": "Email template",
    "notification_event": "transaction_success",
    "body": "Charge {{CHARGE_ID}} with {{AMOUNT}} {{CURRENCY}} created successfully.",
    "type": "message"
}
{
    "status": 201,
    "error": null,
    "resource": {
        "type": "notification-templates",
        "data": {
            "_id": "64cb07f2f3b49c1c150f917e",
            "created_at": "2023-08-03T01:50:42.310Z",
            "updated_at": "2023-08-03T01:50:42.310Z",
            "scope_id": "649a6edfb848941bea648bd6",
            "scope": "company",
            "archived": false,
            "html": false,
            "body": "Charge {{CHARGE_ID}} with {{AMOUNT}} {{CURRENCY}} created.",
            "label": "Email third template",
            "notification_event": "transaction_success",
            "type": "message"
        }
    }
}

Step 3) Register your email notification

Register your email notification by making a request to our notification's endpoint, allowing the passed email to be notified of the required events.

API Endpointhttps://api.preproduction.powerboard.commbank.com.au/v1/notifications
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 Parameterstype - string - Type of notification: webhook, email

destination - string - Where to send notification (secure https URL for webhook, email address for email)
Note: Setting this parameter to {{email}} will configure the notification to send to the buyer's email address.

event - string - Event to trigger a notification.

transaction_only - boolean -
If true, the payload of an event will include information on the latest transaction only and a charge ID. The rest of the fields will be omitted. By default, it is set to false.

template_id - string - Custom template, which can be used with email notifications

subject - string - Set subject of an email notification
{
    "event": "transaction_success",
    "destination": "{{EMAIL}}",
    "type": "email",
    "transaction_only": false
    "template_id": "CREATED_TEMPLATE_ID",
    "subject": "Your email notification subject"
}
{
    "status": 201,
    "error": null,
    "resource": {
        "type": "notification",
        "data": {
            "transaction_only": true,
            "_id": "64cb087edd42c226f9b6e0dc",
            "template_id": "64cb07f2f3b49c1c150f917e",
            "type": "email",
            "event": "transaction_success",
            "destination": "{{EMAIL}}",
            "created_at": "2023-08-03T01:53:02.978Z",
            "updated_at": "2023-08-03T01:53:02.978Z"
        }
    }
}

Step 4) Test your email notification

Test your email notification ensuring that it is receiving the correct response based on the subscribed event types. You can find steps to test your setup below.


Step 5) Deploy the notification setup into our production environment.

You will need to setup the notification in our production environment, if previously configured in pre-production.


Test your integration

Before going live with your email notifications it is important to ensure it is working correctly and as expected. Follow the below steps to test and verify.

Step 1) Ensure the Notification setup steps are completed to correctly setup your PowerBoard email notification.

Step 2) Complete a transaction or event that will trigger the event you are Subscribed to.

Step 3) Verify your email notification is receiving the correct response with the correct template.


Notification logs

You can view a list of all notification logs sent by PowerBoard via API, if required. These can be filtered by date, type, event, etc.

See below example:

API Endpointhttps://api.preproduction.powerboard.commbank.com.au/v1/notifications/
HTTP Method
GET
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.
Query Parameterslimit - Pagination parameter to limit output to n , default = 100 , maximum value = 1000
event - Parameter to filter notification events.
destination - Parameter to filter by email address or webhook URL.
type - Parameter to filter notification by type. Values: email, webhook
success - Parameter to filter success or failed notifications. Values: true/false
created_at.from - Parameter to filter notifications date range. Format: ISO 8601 (yyyy-mm-ddThh:mm:ss.sssZ) or short type of date (yyyy-mm-dd) or specify time offsets from UTC (yyyy-mm-ddThh:mm:ss+hh:mm).
created_at.to - Parameter to filter notifications date range. Format: ISO 8601 (yyyy-mm-ddThh:mm:ss.sssZ) or short type of date (yyyy-mm-dd) or specify time offsets from UTC (yyyy-mm-ddThh:mm:ss+hh:mm)
sortkey - Sorting key parameter i.e. created_at
sortdirection - Sorting order direction parameter ASC or DESC (DESC by default)

Unsubscribe to a notification

You can unsubscribe to a notification via our API or via the PowerBoard merchant dashboard.

Unsubscribe via API

Step 1) Identify the notification Events and ID’s you would like to unsubscribe to.

Step 2) Make a request to our DELETE notifications endpoint using the notification ID as a Path parameter.

See below example:

API Endpointhttps://api.preproduction.powerboard.commbank.com.au/v1/notifications/{id}
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.
Path Parametersid - YOUR_NOTIFICATION_ID - The ID of the notification provided when initially created

Step 3) Verify the event notification is longer being received by the registered destination.


Unsubscribe via the PowerBoard merchant dashboard

Step 1) Login to the PowerBoard merchant dashboard using your merchant user credentials.

Step 2) Using the left-hand side menu, navigate to the Notifications section.

Step 3) Identify the notification you would like to unsubscribe to. You can search through Notification or Event type via the Filters on the top of the page.

Step 4) On the notification you would like to delete. You will find an “Actions” button on the right-hand side of the page. Click this and select “Remove” from the dropdown.

unsubscribe notification

Step 5) Verify the event is no longer triggering a notification to the registered email destination.