@auspayplus/open-payments-checkout

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.

Error	Details	Friendly Message + UI example	Actions
onError callback
Order ID Expired	Caused at instantiation of checkout if an expired `orderId` is passed.	Payment Loading Error Don’t worry, your order is still there and you haven’t been charged yet. Please try closing the window and checking out again or contact Customer Service if this issue continues.	Display error message Generate a new orderId and try again
Order ID Missing	Caused at instantiation of checkout if no `orderId` is passed.	""	Pass an un-expired `orderId` and try again.
Instantiation Error	Generic error if something goes wrong that isn’t covered above	""	Log error and investigate.
onPaymentError Callback
Generic Payment Error	Generic error if something goes wrong during the payment process	Payment Processing Error We’re sorry, but there was an issue processing your payment. Don’t worry, you haven’t been charged yet. Please try again or contact Customer Service if this issue persists.	Log error and investigate.
onCheckoutClosed Callback
Authentication Error	Caused if the user exits after a failed login/signup flow in Ping	Errors handled by Ping	Log error and investigate. Issue is either with user input or Ping service.
Card Management Error	Caused by an error while trying to manage a card on BAAS	Save Card Error We’re sorry, but there was an issue saving your card. Don’t worry, no changes have been made yet. Please try to save again or contact Customer Service if this issue persists. Remove Card Error We’re sorry, but there was an issue removing your card. Don’t worry, no changes have been made yet. Please try to remove again or contact Customer Service if this issue persists.	Log error.
Failed to get order details	Caused by a failure to retrieve order details from BAAS	Payment Loading Error Don’t worry, your order is still there and you haven’t been charged yet. Please try closing the window and checking out again or contact Customer Service if this issue continues.	Log error and investigate.
Failed to get user details	Caused by a failure to get user information (primary concern for this is eg. a user’s payment methods) from BAAS	Wallet Details Error Sorry, there was a problem loading your wallet details. Your order is still here. Try going back and starting your checkout again or contact Customer Service for help.	Log error and investigate.
Generic Error	Generic error if something goes wrong that isn’t covered by other errors	Payment Processing Error We’re sorry, but there was an issue processing your payment. Don’t worry, you haven’t been charged yet. Please try again or contact Customer Service if this issue persists.	Log error and investigate.

---