Overview

PayPal Vaulting is a feature offered by PayPal that enables merchants to store their customers' payment information for future use securely. This allows merchants to process payments without requiring customers to be present for each transaction or to re-authenticate their identity with PayPal, even if the customer is involved in a future transaction.

With PayPal Vaulting, merchants can store a tokenized version of the customer's payment details—such as their PayPal account information—securely in PayPal's vault. This token can then facilitate future payments, making the process faster and more convenient for merchants and customers. This feature is especially beneficial for subscription-based businesses, e-commerce merchants, and those offering services with recurring charges.

Key Benefits

Future Payments
Merchants can charge a customer’s account at a later date (e.g., for recurring payments
or one-click purchases) without requiring the customer to enter their PayPal credentials
or go through authentication again.
Seamless Customer Experience
For customers, it reduces friction in the payment process by eliminating the need to
repeatedly log in or re-authenticate when making purchases on the merchant’s platform.

Pre-Configuration and access tokens

🚧
Before you begin:
When utilising the PayPal Vaulting 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:

Login to the PowerBoard Merchant Dashboard.

Click on the ‘Access Tokens’ link in the navigation dropdown.

On screen, select the 'Create New' button.

Enter a name for your access token. Optionally, set an expiration date if required.

Select the 'For UI' tab.

Select the following permission under Widgets and click 'Create Token':

PaypalSavePaymentSource

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

Integration Steps

Step 1. Create, initialise, and style the PayPal Vaulting Widget

You should begin by including PowerBoard's Hosted JavaScript library in your page and creating a container for the PowerBoard widget

<script src="https://widget.preproduction.powerboard.commbank.com.au/sdk/latest/widget.umd.min.js"></script>
<div id="paypalButton"></div>
<script>
  function loadButtons() {
  let payPalSavePaymentSourceWidget = new cba.PayPalSavePaymentSourceWidget("#paypalButton",
  {{Access token value}}, {{Paypal Gateway id value}},
  {
    style: {
      layout: 'vertical',
      color: 'gold',
      shape: 'sharp',
      label: 'paypal'
  	}
  });
  // setup callbacks, environment and start loading process.
  payPalSavePaymentSourceWidget.load();
</script>

List of available styling configuration parameters:

Parameter	Type	Description
style.layout	’vertical’ \| ’horizontal’	Used for indicating the PayPal Button layout.
style.color	’blue’ \| ’gold’ \| ’silver’ \| ’black’ \| ’white’	Used for indicating the main color of the PayPal Button.
style.shape	’rect’ \| ’sharp’ \| ’pill’	Used for indicating the shape of the PayPal Button.
style.label	’paypal’ \| ’checkout’ \| ’buynow’ \| ’pay’	Used for indicating the label of the PayPal Button.
style.disableMaxWidth	boolean	Used for indicating if the max width will be disabled.
style.disableMaxHeight	boolean	Used for indicating if the max height will be disabled
style.height	number	Used for indicating the height of the PayPal Button, if disableMaxHeight is true.
style.borderRadius	number	Used for indicating the border radius of the PayPal Button.
style.tagline	boolean	Used for indicating the tagline of the PayPal Button.
message.amount	number	Used for indicating an amount before the payment.
message.align	’center’ \| ’left’ \| ’right’	Used for indicating the align of the message.
message.color	’black’ \| ’white’	Used for indicating the color of the message.
message.position	’top’ \| ’bottom’	Used for indicating the position of the message.

Step 2. Configure the widget event handlers and methods

There are numerous Event handlers and methods available as part of the widget to manage your workflows:

onSuccess callback

This function will be executed once the customer successfully chooses their payment method within Paypal to be saved.

payPalSavePaymentSourceWidget.onSuccess((eventData) => {
  console.log("PayPal Success Event Data:", eventData);
);

eventData will return two values:

email: The email used by the customer to login to their PayPal account.
token: The one-time token returned by the widget

{
  email: "[email protected]",
  token: "e9421bd7-01b9-46ec-a123-d15da126e393"
}

onCancel callback

This function will be executed once the customer closes the PayPal IFrame

payPalSavePaymentSourceWidget.onCancel(() => {
  console.log("PayPal IFrame has been cancelled");
);

onError callback

This function will be executed once an error occurs in the customer's journey. This handler is a "catch-all". Any errors at this point aren't expected to be handled beyond showing a generic error message or page.

payPalSavePaymentSourceWidget.onError((error) => {
  console.log("There has been an error with your transaction:", error);
);

load method

This method needs to be called to load the widget into the customer's browser, once the widget configuration, environment, and callback configuration is completed.

payPalSavePaymentSourceWidget.load();

setEnv method

This method needs to be called to select the environment to be targeted.

payPalSavePaymentSourceWidget.setEnv("preproduction_cba");

Step 3. Add the Paypal Data Collector

To help prevent fraud, implement the PayPal data collector to gather information about a customer's device on your checkout page.

To implement this data collector, add the following data collector instance into your integration:

const payPalDataCollector = new cba.PayPalDataCollector(flowId, {
 mouse_movement: true // Enables mouse movement data collection to be sent to PayPal 
}
payPalDataCollector.collectDeviceData().then((cmid)=>console.log(cmid));

flowId is a unique flow id per web page. If not supplied, it will be an auto-generated unique value.

The collectDeviceData method returned an object.correlation_id asynchronously. The correlation_id can then be sent in the payment request to Paypal.

Step 4. Create or modify an existing customer using the returned token.

The token returned from the widget when a customer links a PayPal account can then be used to create or modify a customer in PowerBoard.

API Endpoint	https://api.preproduction.powerboard.commbank.com.au/v1/customers
HTTP Method	POST
Headers	x-user-secret-key- POWERBOARD_SECRET_KEY - This is your PowerBoard API Secret Key. Content-Type - application/json - Type will always be application/json.
Request Parameters	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. token - string - payment source string returned from the widget following the "finish" event. Example: "paymentsource": "c2a69078-110c-4081-a927-167d9d1b2f04". first_name - _string - Customer first name. last_name - string - Customer last name. phone - string - Customer phone number. email - string - Customer email address.

Sample body

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.

{
    "first_name": "John",
    "last_name": "Customer",
    "email": "[email protected]",
    "phone": "+61111111111",
    "reference": "Customer 1",
    "token": "b243799c-c9d6-43b8-80aa-689fc8179927"
}

{
  "status": 201,
  "error": null,
  "resource": {
    "type": "customer",
    "data": {
      "company_id": "649a6edfb848941bea648bd6",
      "first_name": "John",
      "last_name": "Doe",
      "phone": "036-900-5958",
      "_check_expire_date": false,
      "_service": {
        "default_gateway_id": "67bfb1e7e6d9585ca3925faa"
      },
      "statistics": {
        "successful_transactions": 0,
        "total_collected_amount": 0
      },
      "archived": false,
      "status": "active",
      "payment_sources": [
        {
          "type": "gateway_token",
          "checkout_holder": "John Doe",
          "checkout_email": "[email protected]",
          "external_payer_id": "BGGXK6DBNHS7J",
          "status": "active",
          "gateway_id": "67bfb1e7e6d9585cfa3925faa",
          "gateway_name": "PayPal",
          "gateway_type": "Paypal",
          "gateway_mode": "test",
          "created_at": "2025-03-13T00:04:08.776Z",
          "updated_at": "2025-03-13T00:09:18.434Z",
          "ref_token": "3nf14910l5051630y",
          "_id": "67d220f8ad078abe2e471a17"
        }
      ],
      "default_source": "67d220f8ad078abe2e471a17",
      "_source_ip_address": "133.41.61.123",
      "_id": "67d2222e48da409bf2daa622",
      "payment_destinations": [],
      "updated_at": "2025-03-13T00:09:18.435Z",
      "created_at": "2025-03-13T00:09:18.435Z",
      "__v": 0
    }
  }
}

Once created, you can then use the returned customer_id to process a financial charge or subscription, as documented here

Creating a Subscription

The widget generated token can additionally be used to directly create a subscription within PowerBoard

API Endpoint	https://api.preproduction.powerboard.commbank.com.au/v1/subscriptions
HTTP Method	POST
Headers	x-user-secret-key- POWERBOARD_SECRET_KEY - This is your PowerBoard API Secret Key. Content-Type - application/json - Type will always be application/json.
Request Parameters	amount - string - Total amount for the subscription 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. token - string - Token returned from the widget representing the customer's paypal account. schedule.frequency - string - A number value for how often a subscription charge is processed (default = "1") schedule.interval - string - The interval of the subscription; allowed values: day, week, month, year schedule.start_date - string - The start date of the subscription in the ISO 8601 format (yyyy-mm-ddThh:mm:ss.sssZ) or in a short type of date (yyyy-mm-dd) schedule.end_date - string - The end date of the subscription in the ISO 8601 format (yyyy-mm-ddThh:mm:ss.sssZ) or in a short type of date (yyyy-mm-dd) device_data.correlation_id - String - The PayPal Data collector correlation_id collected from the widget

Sample Request and Response

{
    "amount": "22.99",
    "currency": "AUD",
    "reference": "subscrip_ref",
    "description": "Test subscription",
    "token": "6bf026ed-38f9-4cc1-8787-1fc45f65d665",
    "schedule": {
        "frequency": "1",
        "interval": "day",
        "start_date": "2023-08-08",
        "end_date": "2023-08-09"
    },
  "device_data": {
    "correlation_id": "2f615d54-ba97-6962-b1cc-cfccbfb9e278"
  }
}

{
    "status": 201,
    "error": null,
    "resource": {
        "type": "subscription",
        "data": {
            "schedule": {
                "frequency": 1,
                "retry_count": 0,
                "held_count": 0,
                "completed_count": 0,
                "locked": false,
                "interval": "day",
                "start_date": "2023-08-08T00:00:00.000Z",
                "end_date": "2023-08-09T00:00:00.000Z",
                "end_amount_after": 0,
                "end_amount_before": 0,
                "end_amount_total": 0,
                "next_assessment": "2023-08-08T00:00:00.000Z",
                "next_assessment_planned": "2023-08-08T00:00:00.000Z",
                "first_assessment": "2023-08-08T00:00:00.000Z",
                "status": "inprogress"
            },
            "statistics": {
                "successful_transactions": 0,
                "total_collected_amount": 0
            },
            "currency": "AUD",
            "archived": false,
            "_id": "64d180b71e04e51be27fc81f",
            "amount": 22.99,
            "description": "Test subscription",
            "reference": "subscrip_ref",
            "customer": {
                "customer_id": "64d180b71e04e51be27fc81c"
            },
            "_service": {
                "customer_default_gateway_id": "649a6f111e04e51be27e9a91",
                "tags": "undefined undefined undefined"
            },
            "status": "active",
            "updated_at": "2023-08-07T23:39:35.308Z",
            "created_at": "2023-08-07T23:39:35.308Z",
            "__v": 0
        }
    }
}

Paypal Vaulting

PayPal

Overview

Key Benefits

Pre-Configuration and access tokens

🚧
Before you begin:

Integration Steps

Step 1. Create, initialise, and style the PayPal Vaulting Widget

Step 2. Configure the widget event handlers and methods

onSuccess callback

onCancel callback

onError callback

load method

setEnv method

Step 3. Add the Paypal Data Collector

Step 4. Create or modify an existing customer using the returned token.

Sample body

Creating a Subscription

PayPal

Overview

Key Benefits

Pre-Configuration and access tokens

🚧Before you begin:

Integration Steps

Step 1. Create, initialise, and style the PayPal Vaulting Widget

Step 2. Configure the widget event handlers and methods

onSuccess callback

onCancel callback

onError callback

load method

setEnv method

Step 3. Add the Paypal Data Collector

Step 4. Create or modify an existing customer using the returned token.

Sample body

Creating a Subscription

🚧
Before you begin: