Open Payments Checkout

A library/framework agnostic NPM package that provides a means to trigger the Open Payments Checkout process and other related utility functions.

Getting Started

Simply install the package by running one of the following:

• For Yarn: yarn add @auspayplus/open-payments-checkout
• For NPM: npm install @auspayplus/open-payments-checkout
• For PNPM: pnpm install @auspayplus/open-payments-checkout

Basic Usage

Javascript

To instantiate Checkout in a JS environment, you can do the following:

import { Checkout } from '@auspayplus/open-payments-checkout';

const checkout = new Checkout({
  orderId: '123',
  url: 'https://{checkout_url}',
  clientId: 'client_id',
  onCheckoutClosed: () => {
    console.log('CHECKOUT COMPLETED!');
  },
});

And then bind the trigger to your event listener:

const openCheckout = () => checkout.open();
<button class="my-button" onclick=openCheckout()>My Button</button>

React

For React, the following is an example of how to instantiate the checkout.

import { Checkout } from '@auspayplus/open-payments-checkout';

export function MyComponent() {
  const checkout = new Checkout({
    orderId: '123',
    url: 'https://{checkout_url}',
    onCheckoutClosed: () => {
      console.log('CHECKOUT COMPLETED!');
    },
    onError: () => {
      console.log('AN ERROR OCCURRED!');
    },
    onPaymentSuccess: () => {
      console.log('PAYMENT IS SUCCESSFUL!');
    },
    onPaymentError: () => {
      console.log('PAYMENT HAS ERRORED!');
    },
    onTokensChanged: ({ accessToken, refreshToken }) => {
      console.log('TOKENS HAVE CHANGED!');
    },
  });

  const onClick = () => {
    checkout.open();
  };

  useEffect(() => {
    // This is required for the callbacks provided to work
    // otherwise, is negligible
    checkout.listenMessage();
  }, []);

  return <Button {...args} onClick={onClick} />;
}

Checkout params

There are a few arguments that you can pass in the Checkout class constructor to instantiate the checkout

| Params | Description | Required | | ----------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | | auth: object | Auth object that enables express checkout. This must be defined along with property mode defined as "express". More details in Further Info For Params | Optional | | orderId: string | An order id is required to invoke the checkout process. | Required | | clientId?: string | The client id is used to tag the wallet that is being used (e.g. Beem) as well as provide different experiences and functionality in the checkout journey. If a client id is not provided then the client id will be defaulted to Beem. | Optional | | mode?: string | This property must be defined if attempting to use express checkout. Values can be of string "default" or "express" | Optional | | onCheckoutClosed({ error: Error, orderId: string }) | A callback that can be passed to be invoked upon closure of the checkout window. | Optional | | onError({ error: Error, orderId: string }) | A callback that can be passed to be invoked upon encountering errors in the checkout process | Optional | | onPaymentSuccess({ error: Error, orderId: string }) | A callback that can be passed to be invoked upon success during the payment process. | Optional | | onPaymentError({ error: Error, orderId: string }) | A callback that can be passed to be invoked upon error during the payment process. | Optional | | onTokensChanged({ accessToken, refreshToken }) | A callback that can be passed to be invoked when the access token and/or refresh token changes. | Optional | | windowFeatures | This dictates how the window will be presented. | Optional |

Further Info For Params

auth

The auth property will allow for express checkout in the target checkout site. A mode with string value express must be declared along with this in order to enable this functionality.

| Property | Value | Required | | ------------- | ------ | -------- | | access_token | string | Required | | expires_in | number | Optional | | id_token | string | Optional | | refresh_token | string | Required | | scope | string | Optional | | token_type | string | Optional |

You can pass this object to the auth property during the instantiation like so

const checkout = new Checkout({
  // Pass tokens into the auth property object
  auth: {
    access_token: '12345',
    refresh_token: '678910',
  },
  mode: 'express',
  orderId: '123',
  url: 'https://{checkout_url}',
});

onTokensChanged

The onTokensChanged callback will receive an object containing the new accessToken and refreshToken values when they change.

windowFeatures

The windowFeatures param is accepting an object which comprises the following:

| Property | Value | | --------- | --------------------------- | | height | number | | left | number | | popup | 'yes' | 'no' | '1' | '0' | | resizable | 'yes' | 'no' | '1' | '0' | | top | number | | width | number |

For example, if you want to customise the window features, you would instantiate Checkout like so:

const checkout = new Checkout({
  orderId: '123',
  url: 'https://{checkout_url}',
  windowFeatures: {
    width: 200,
    height: 200,
  },
});

Available Methods

Upon instantiation of the Checkout class, the following public methods/utilities will be made available

| Method | Description | | ----------------------- | ------------------------------------------------ | | isCheckoutOpen: boolean | Checks if the checkout window is open or not | | listenMessage(): void | Required if utilising callbacks for the checkout | | open(): void | Opens and instantiates the checkout window | | close(): void | Closes the checkout window |

Callbacks and Errors

Apart from kicking off the checkout process, the Merchant Package also facilitates communications between the merchant and the checkout. The merchant package accommodates this via 4 callback methods to which 3 are able to provide access to errors with 1 for any additional tasks a merchant may want to perform upon successful payment. Callbacks will use the following signatures for as arguments.

interface ICheckoutCallback {
  orderId: string;
  error?: Error;
}

The next section will provide a basic overview of the overall flow and followed by further details of these callbacks.

Basic Merchant Package Flow

Starting from the merchant’s site, the Merchant Package is instantiated, providing several methods for usage. One of these is the open method. The open method is then bound to a button, for example, the “Checkout with FlyPay” button, which would then instantiate the checkout flow. The merchant site must provide an orderId obtained from creating an order via the Beem As A Service (BaaS) API and provide this orderId when instantiating the Merchant Package.

At the start of the checkout process, the user authentication process is commences and the user is redirected to a PING login/signup flow. On completing the flow, a userToken is generated and passed to the checkout. The user is taken to the checkout landing page, which queries BaaS with the userToken and orderId to get the details of the user and the order. The user may then manage their cards (view, add, remove, update, set card as default), or simply hit the pay button to commence payment.

When the user hits the pay button, a series of requests are exchanged with BaaS, simplified here as the 'payment flow'. If all of these are successful, the user is taken to a 'payment success' screen, and the onPaymentSuccess() callback is triggered on the merchant site (note that this happens upon successful payment and does not wait until the checkout is closed).

Merchant Package Callbacks

The four merchant package callbacks are described here. Note that onPaymentSuccess does not provide access to errors. Only the orderId is accessible from there.

onCheckoutClosed({ error: Error, orderId: string })

onCheckoutClosed (previously onPaymentComplete) occurs at any time the checkout is closed without a payment succeeding or failing. If an error is present in the session at close, it will be accessible in the callback along with the orderId otherwise, only the orderId is accessible.

onError({ error: Error, orderId: string })

onError will only occur at instantiation if the orderId is not provided during the instantiation of the Merchant Package, or the orderId provided is expired.

onPaymentError({ error: Error, orderId: string })

onPayment Error only occurs during the payment flow, allowing access to errors and the orderId within the callback function and any error handling in regards to payments.

onPaymentSuccess({ orderId: string })

onPaymentSuccess is called when a payment flow has fully succeeded. Only the orderId is accessible from this callback. This callback also provides the means to perform additional work if required by the merchant.

Possible Errors

Listed below are possible errors that can occur and which callback handles which. Note that, any errors occurring during the checkout process is detrimental to the success of a transaction and a user will no longer be able to complete the transaction if it occurs.