PayPal Smart Payment Buttons

This document will guide you on how to correctly integrate PayPal Smart Payment Buttons and Pay in 4 via PowerBoard.

Pre-requisites

PayPal Account Setup

Merchants will need to obtain the following data from PayPal:

• Username (Client ID)
• Secret Key (Password)

PowerBoard Setup

Merchants will need to setup the following data on PowerBoard:

• PowerBoard Secret key/Access token
• PayPal Gateway ID
• PayPal Wallet Button widget setup (all versions supported; latest version recommended)

Service Setup

Step 1. Connect PayPal Service on PowerBoard Dashboard

1. Select 'Services' on the left navigation pane.

2. Click on the 'Add New' tab.

3. Go to the 'Service Group' drop down list and select 'Gateway Services'.

4. Click on 'Activate' next to PayPal.

5. Complete all the required fields:

   • Username
   • Password

📘

Note

The "Enable Customer Information Overwrite" checkbox is used to indicate consent to replace the consumer information with the payer information from the PayPal wallet at the charge level.

6. Select the environment.
7. Click connect.

Step 2. Verify PayPal Service Connection

1. Select 'Services' on the left navigation pane.
2. Click on the 'Connected Services' tab.
3. Go to the 'Service Group' drop down list and select 'Gateway Services'.
4. Note the 'Gateway ID' as this will be used for API calls.

Integration Steps

Step 1. Create and Initialise the PayPal Widget

Include PowerBoard's Hosted JavaScript library in your page and create a container for the PowerBoard widget:

<div id="widget-paypal">
  <script src="https://widget.preproduction.powerboard.commbank.com.au/sdk/latest/widget.umd.js"></script>
  <script>
    let button = new cba.WalletButtons("#widget-paypal", "YOUR_WALLET_TOKEN", {
      amount_label: "Payment Amount",
      country: "AU",
      request_shipping: false,
      pay_later: true, // change 'pay_later' to false to display only PayPal button
      standalone: false, // change 'standalone' to true to display only one button
      hide_message: false, // change 'hide_message' to true to hide PayIn4 messaging
      style: {
        layout: 'horizontal',
        color: 'gold',
        shape: 'rect',
        label: 'paypal',
      },
    });
    button.setEnv('preproduction_cba');
    button.onUnavailable(() => console.log("No wallet buttons available"));
    button.onPaymentSuccessful((data) console.log("Payment Successful"));
    button.onPaymentError((data) => console.log("The payment was not successful"));
    button.onPaymentInReview((data) => console.log("The payment is on fraud review"));
    button.load();
    }
  </script>

Widget Configuration Parameters

Step 2. Configure Widget Event Handlers

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

onPaymentSuccessful callback

This function will be executed once the customer successfully completes the payment.

button.onPaymentSuccessful(function(data) {
    console.log("Payment successful");
    console.log(data);
});

onPaymentError callback

This function will be executed when a payment error occurs.

button.onPaymentError(function(err) {
    console.log("Payment error");
    console.log(err);
});

onPaymentInReview callback

This function will be executed when the payment is under fraud review.

button.onPaymentInReview(function(data) {
    console.log("The payment is on fraud review");
    console.log(data);
});

onUnavailable callback

This function will be executed when no wallet buttons are available.

button.onUnavailable(function() {
    window.alert("No wallet buttons available");
});

onUpdate callback

This function will be executed when the charge amount needs to be updated (e.g., shipping changes).

button.onUpdate((data) => {
    console.log("Updating amount via a backend to backend call to POST charges/:id");
    button.update({ success: true });
});

onClick callback

This function will be executed when the PayPal button is clicked, allowing for validation before proceeding.

// ASYNC MODE
const serverValidations = async () => {
    // Perform server-side validations
}

button.onClick(({ data: { attachResult } }) => {
    attachResult(serverValidations());
});

setEnv method

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

button.setEnv('sandbox'); // or 'production'

load method

This method needs to be called to load the widget into the customer's browser.

button.load();

API Reference

The following APIs are used for PayPal service:

• Initialise a charge for wallet payment: [POST https://api.preproduction.powerboard.commbank.com.au/v1/charges/wallet]
• Initialise charge for wallet payments (Auth, Capture and Cancel) - See https://developer.powerboard.commbank.com.au/docs/paypal-auth-capture
• Refund: [POST https://api.preproduction.powerboard.commbank.com.au/v1/charges/:chargeId/refunds]

Charge Processing

PayPal Charge

Step 1. Initialise Charge for Wallet Payments

Initialise wallet charge using the [POST /v1/charges/wallet] endpoint:

Sample Request:

{
    "amount": 50,
    "currency": "AUD",
    "customer": {
        "payment_source": {
            "gateway_id": "647d7c4da1a08f5eec502a5e"
        }
    }
}

{
    "status": 201,
    "error": null,
    "resource": {
        "type": "charge",
        "data": {
            "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
            "charge": {
                "_id": "650d1fc302467631b0fbac6f",
                "amount": 50,
                "currency": "AUD",
                "company_id": "6459ec32d5a3f85c5c9fa337",
                "type": "financial",
                "status": "wallet_initialized",
                "capture": true,
                "authorization": false,
                "one_off": true,
                "created_at": "2023-09-22T05:01:55.235Z",
                "updated_at": "2023-09-22T05:01:55.235Z",
                "customer": {
                    "payment_source": {
                        "type": "wallet",
                        "wallet_type": "paypal",
                        "gateway_id": "647d7c4da1a08f5eec502a5e",
                        "gateway_name": "PayPal",
                        "gateway_type": "Paypal"
                    }
                },
                "transactions": [],
                "shipping": {},
                "items": []
            }
        }
    }
}

Step 2. Execute PayPal Widget

1. Insert the data.token from the API response into the PayPal widget in the "YOUR_WALLET_TOKEN' field from Integration Step 1. (See below code exmaple)

 let button = new cba.WalletButtons("#widget-paypal", "YOUR_WALLET_TOKEN", {
      amount_label: "Payment Amount",
      country: "AU",
      request_shipping: false,
      pay_later: true, // change 'pay_later' to false to display only PayPal button
      standalone: false, // change 'standalone' to true to display only one button
      hide_message: false, // change 'hide_message' to true to hide PayIn4 messaging
      style: {
        layout: 'horizontal',
        color: 'gold',
        shape: 'rect',
        label: 'paypal',
      },

2. Execute the PayPal widget in the web browser.

3. PayPal button(s) will be rendered.

   

   
   

4. Click on either 'PayPal' or 'Pay in 4' button.

5. An iframe will be triggered for the customer to complete the payment.

6. Upon completion, the charge status will be updated to 'Complete' on the PowerBoard dashboard.

Create PayPal Refund

Use the [POST /v1/charges/:chargeId/refunds] endpoint:

Sample Request:

{
    "amount": 80
}

The charge status will be changed from 'Complete' to 'Refunded'.

Alternatively, refunds can be performed from the PowerBoard dashboard by selecting 'Refund Request' from the 'Actions' drop-down list.

Shipping Address Handling

There are 3 scenarios for handling shipping addresses based on merchant configuration:

Setting Shipping Options

When initialising a wallet charge [POST https://api.preproduction.powerboard.commbank.com.au/v1/charges/wallet], you can use the shipping object and define any of the supported shipping options.

📘

Note

The shipping.method must be the same as the shipping.options.id, and the shipping amount must also be the same as the shipping.option.amount for any of the used shipping.options.

Sample Shipping Object:

"shipping": {
    "amount": 5,
    "method": "SHIP_321",
    "address_line1": "ship1",
    "address_line2": "ship22",
    "address_line3": "ship3",
    "address_city": "shipcity",
    "address_state": "shipstate",
    "address_country": "AU",
    "address_postcode": "123456",
    "contact": {
        "first_name": "ship_contact",
        "last_name": "contact_last_name",
        "phone": "+5555555556"
    },
    "options": [
        {
            "id": "SHIP_321",
            "label": "Standard Shipping",
            "type": "SHIPPING",
            "detail": "SHIP_321 - Standard Shipping",
            "amount": 5.00,
            "currency": "AUD"
        }
    ]
}

Shipping Option Parameters

Hide Message Feature

The hide_message parameter controls the display of "PayLater messaging":

• If hide_message is set to true, PayLater Learn More message is NOT displayed
• If hide_message is set to false, PayLater Learn More message is displayed

📘

Note: Messaging is different depending on amount

• If amount is less than $30: Messaging says Pay in 4 is only available for purchases between $30 - $1500
• If amount is equal to or greater than $30: Messaging breaks down the amount into 4 equal instalments