Checkout Feature

This document will guide you on how to correctly integrate the Checkout feature via PowerBoard.

What is Checkout?

The Checkout feature revolutionizes the merchant's checkout process by offering a user-friendly, adaptable, and easily customisable checkout solution. This innovative approach streamlines transactions and provides a seamless experience for both merchants and customers. Through available customisation options, merchants can align the checkout interface with their brand identity, making it appear native to their e-commerce ecosystem. This includes matching colour schemes and fonts to create a cohesive shopping experience from browsing to purchase completion.

Key Benefits

• Ease of deployment and maintenance: Deployment of new features/capabilities with minimal code, providing simple integration and ease of additional features into your existing ecommerce ecosystem.
• Reduced Complexity: Eliminates the need for merchants to understand and manage complex business flows and payment gateway specifics by providing a single Master Widget that requires one API call for initialization.
• Centralized Customisation: Allows for consistent styling and layout configurations across different platforms with minimal code changes.
• Enhanced Monitoring: Provides a comprehensive overview of the user's payment journey, facilitating better tracking and troubleshooting.

Core Functionalities

• Presents a wide array of payment methods to customers
• Integrates value-added services seamlessly
• Facilitates a smooth and secure transaction flow

📘

Current Supported Services and Flows

Card Payments Flows:

• Card Payments with 3D Secure (Recommended)
• Card Payments without 3D Secure

Alternate Payment Methods:

• Afterpay v1 Direct Charge
• Zip Direct Charge

🚧

Before you begin:

When utilising the Checkout feature you will be required to create and use an Access Token.

Access Tokens are generated via PowerBoard’s Merchant Dashboard, in a few easy steps:

1. Login to the PowerBoard Merchant Dashboard.
2. Click on the ‘Access Tokens’ link in the navigation dropdown.
3. On screen, select the 'Create New' button.
4. Select the following permissions

• checkouts:create-intent
• checkouts:search
• checkouts:get
• checkouts:get-versions
• checkouts-templates:get
• checkouts-templates:search
• checkouts-templates:create
• checkouts-templates:update
• checkouts-templates:get-schemas

5. Click Save
6. Copy your Access Token and store it somewhere secure as once it has been generated it can no longer be accessed.

How to Setup Checkout

📘

You will need

Before beginning setup, ensure you grab your Gateway IDs for the relevant payment types as you will need these to complete setup.

1. Log into the PowerBoard Merchant Dashboard

2. Navigate to 'Checkout' in the navigation section

3. Select ' Create New'

   

4. From the 'Select Template Options' you will get the choice of

   1. Customisation - (Template designed specifically for customising the look and feel of your checkout experience)
   2. Configuration - (Templated designed specifically for selecting what workflows/payment services will be included in your checkout experience)
   3. Configuration & Customisation - (Allows you to create the 2 above templates simultaneously)

Select the template that you wish, for a first-time setup, we recommend using the Configuration & Customisation option.

5. On the next step, you will get the option to label your templates, we recommend that you keep these unique and call out if the template is for configuration or customisation. On configuration you will also get the option to select which version of the configuration template you want to create.

6. After selecting your API version this will bring up a list of services, for the service you wish to enable select a transaction flow associated with the service you wish to enable and add in the Service ID which you can find in the 'Services' screen

   

7. Once you have selected your workflows and entered the Service ID associated with each service, click 'Save and Next' (You will also have the ability to update an existing configuration template once it has been created)

8. You will need to label your customisation template, similar to Step 5, we recommend you keep the label for your configuration template unique and identify that it is a Configuration Template.

9. You will have the ability to customise the look and feel of your Checkout Widget via the following fields:

   1. Background Colour
   2. Border Colour
   3. Text Colour
   4. Button Colour
   5. Font Family
   6. Font Size

10. Apply and customization settings and click 'Save' (You will also have the ability to update an existing customisation template once it has been created)

    

11. You will now see the templates you just created appear in your Templates list with an associated ID which can be used in your integration.

12. If you wish to preview the templates that you have created, you can select the 'Preview' option on the Checkout page which will give you the ability to add some configuration data to render the widget within the Merchant Dashboard. (Note: Preview option is only currently available in the PreProduction environment)

13. Enter information into the provided fields and select the Configuration and Customisation templates you have just created. Once the information has been entered, hit 'Create' and this will render the widget into the 'Preview' column.

    

📘

Note

In the PreProduction environment the preview tab will allow you to run test transactions using your created templates you have created. For testing Card Payments, you can use our PowerBoard Test Cards

How to Integrate the Checkout Master Widget

Step 1) Create Configuration and Customisation Templates

Refer to the 'How to Setup Checkout' part of this guide to see how this can be done.

Step 2) Generate Intent Token via API

The Intent encapsulates the payment context for the transaction.

🚧

Note:

The intent call must also include customer specific information (collected during checkout or from
their customer profile) such as contact and address details.

{
    "customisation": {
        "template_id": "YOUR_CUSTOMISATION_TEMPLATE_ID",
    	    },
  	"configuration": {
      	"template_id": "YOUR_CUSTOMISATION_TEMPLATE_ID",
            },
    "customer": {
         "email": "[email protected]",
         "phone": "+6141111111",
         "billing_address": {
            "first_name": "Test",
            "last_name": "User",
            "address_line1": "123 Test Street",
            "address_line2": "Unit 123",
            "address_city": "Sydney",
            "address_state": "NSW",
            "address_country": "AU",
            "address_postcode": "2000",
     		 }
        },
    "amount": "100",
  	"version": '1',
  	"currency": "AUD",
  	"reference": "Order 12345678"
         
}

{
    "status": 201,
    "error": null,
    "resource": {
        "type": "checkout",
        "data": {
            "_id": "67107db89d218493ecc4e082",
            "version": 1,
            "status": "active",
            "reason": null,
            "amount": 120,
            "currency": "AUD",
            "reference": "ref121",
            "journey": [
                {
                    "sense": "info",
                    "title": "Workflow created",
                    "message": "Checkout process created ....",
                    "thread": "main",
                    "context": null,
                    "_id": "67107db89d218493ecc4e085",
                    "created_at": "2024-10-17T03:00:08.850Z",
                    "updatedAt": "2024-10-17T03:00:08.850Z"
                }
            ],
            "created_at": "2024-10-17T03:00:08.759Z",
            "updated_at": "2024-10-17T03:00:08.850Z",
            "token": "YOUR_INTENT_TOKEN"
        }
    }
}

Store the returned intent_token to utilise in the next step.

Note:'customisation.template_ID' and 'reference' fields are optional.

Step 3) Render the Widget using the intent_token

Use the returned intent_token from the previous step and use it to render the Checkout Widget to the end-user.

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

<script>
var widget = new cba.Checkout('#widget',"{{intent_token}}");

Step 4) Add event handling

The Master Widget in the checkout process sends specific notifications to merchants about their customers' checkout status. These notifications are crucial for managing the cardholder experience, addressing various checkout outcomes including:

onPaymentSuccessful

This event is triggered when a payment is completed successfully. It allows the merchant to
execute specific actions, such as updating the order status, notifying the customer of the
successful transaction, and/or redirecting the customer to a confirmation page

onPaymentError

This event is triggered when a payment fails. Merchants can use this event to handle payment
errors, such as displaying error messages to customers or logging the error details.

onPaymentExpired

This event is triggered when a payment workflow session expires. This typically happens if the
customer takes too long to complete the payment (e.g after 15 minutes of inactivity).

Example below:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8">
    <title>Checkout</title>
    <style></style>
  </head>
  <body>
    <h1>Widget</h1>
    <div id="widget"></div>
    <script src="https://widget.preproduction.powerboard.commbank.com.au/sdk/latest/widget.umd.js"></script>
    <script>
      var widget = new cba.Checkout('#widget', "{{intent_token}}");
      widget.onPaymentSuccessful(function(data) {
        console.log("success: ", data)
      });
      widget.onPaymentFailure(function(error) {
        console.log("failure: ", error)
      });
      widget.onPaymentExpired(function(data) {
        console.log("expired: ", data)
      })
    </script>
  </body>
</html>

History

PowerBoard provides you with the ability to review the history of your users checkout experience by providing insights into the steps taken for your user to complete their checkout process. This includes:

• ID - Intent token ID
• Amount - As entered in the intent API request
• Currency - As entered in the intent API request
• Reference - As entered in the intent API request (optional)
• Reason - Additional information about the outcome of a given intent session
• Status - Status of a given intent session
• Process Reference - The ID of the charge generated through the Payment Workflow
  process.
• Created at - The time when the intent API request was successfully completed

Selecting Actions --> View logs will provide you with further insights to exactly what payment methods were selected and details around the outcome of these actions. These have been categorised into colour statuses, which are:

• Green = Success
• Blue = Informational action
• Orange = Warning
• Red = Error

Versioning

Versioning in Templates:

When a merchant creates Configuration or Customisation templates
in the Dashboard, they will see the 'Version' field. This field is important because it allows them
to manage and apply different versions of their templates across various checkout workflows.

● Version Transparency:

Each version of a template corresponds to a specific set of
features and behaviours. By specifying the version in the template, merchants can
ensure that the same configuration is applied consistently across all their checkouts.

● Backward Compatibility:

If the merchant updates a template to a new version, previous
versions remain supported. This means they can maintain older checkout workflows
without disruption while taking advantage of new features in updated versions.

Versioning in the Create Intent Endpoint:

When generating an intent using the /intent API
endpoint, merchants need to explicitly pass the version of the workflow that they want to use.
This is key to maintaining consistency between the API and the Master Widget.

● Explicit Versioning:

By specifying the workflow version in merchants' API request, they
ensure that the API and the Master Widget are aligned. This removes any ambiguity
about which version of the checkout process is being used, reducing the risk of
inconsistencies.

● Stability

During updates, even as PowerBoard releases updates to the API and Master
Widget, their integration remains stable. Merchants only move to a new version of the
workflow when they are ready, giving them control over the timing of any changes.