@auspayplus/open-payments-checkout v1.7.6
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.
1 month ago
5 months ago
5 months ago
5 months ago
6 months ago
6 months ago
6 months ago
8 months ago
10 months ago
1 year ago
1 year ago
1 year ago
11 months ago
11 months ago
11 months ago
11 months ago
11 months ago
1 year ago
1 year ago
1 year ago
1 year ago