Simplify Link with OAuth 2.0

How to access Simplify Link using OAuth 2.0

With Simplify Link, CommBank Simplify APIs support OAuth 2.0 through endpoints for your application. We have also added it into the SDKs for easy setup and use. With user approval, your application may access CommBank Simplify APIs when the user is present or not.

The documentation below describes how to use Simplify Link when accessing CommBank Simplify APIs from your application.

Simplify Link uses OAuth 2.0 so you can interact with CommBank Simplify without having to store sensitive credentials. Our simple authentication flow makes it easy for your customers to connect their CommBank Simplify accounts while giving you the ability to request several levels of permissions. Users can manage and revoke access to their third-party authorisations using the CommBank Simplify dashboard.

With Simplify Link, OAuth developers can request:

Read and Write access to the full CommBank Simplify API

Read and Write access to the Payments and Refunds API

Read Only permission to the full CommBank Simplify API

Overview

First you will need to go to the apps management section of CommBank Simplify to upload a logo, key pair name, and redirect uri. You will get a public key that will be used for the client_id in the authorisation request.

The next part of the flow begins with redirecting a browser (popup or full page if needed) to a CommBank Simplify endpoint with the client_id and a response_type of code. CommBank Simplify then responds with an authorisation code to the application per the redirect_uri query parameter registered with the account.

After the application receives the authorisation code, the application can redeem the code for an access token. The application will send the authorisation code, the grant type of code, and the redirect uri. You will receive an access token and a refresh token. We recommend using one of our SDKs for ease of use.

With the access token you now may access protected CommBank Simplifys APIs.

You can also use the SDKs to refresh the access token if the token has expired or revoke a token.

Register Your Application

Applications that wish to utilise Simplify Link to access CommBank Simplifys APIs must be registered through the apps setting screen.

On this screen, you will upload the company logo (guideline dimensions: 128px x 128px) you wish to appear during authorisation, the name of the application, the key type (sandbox or live), and a redirect url.

A new private key, public key, and confirmation of the redirect url will then be displayed. Copy down the keys, you will need this for the next step.

Creating the URL for Obtaining Authorisation Token

Next you will want to request an authorisation grant. As the client you will do this by issuing a GET request from the user's user-agent browser to https://www.simplify.com/commerce/oauth/authorize with the following query parameters:

response_typeDetermines if an authorisation code is returned to the redirect url on file. A value of code is required.required

scope

The client is allowed to specify the scope of access using the scope parameter. The valid options are full, payments, or readall.

stateAn opaque value used by the client to maintain state between the request and callback. CommBank Simplify
includes this value when redirecting the user-agent back to the client. The parameter SHOULD be used for preventing cross-site request optional

isNewUser

A boolean value, true or false, is used to render the oauth sign up page as the landing page in the oauth flow rather than the oauth login page.
A button will be present on the sign up page to allow users who already have a CommBank Simplify account to redirect back to the login page.

Validation:Max-length: 512

optional

Users who have not previously registered with CommBank Simplify or users that are still in sandbox (or test) mode will be required to on-board & create a new merchant account in order to complete the oauth authorisation.

In order to do so, we require personal, business and other details from the user. In order to facilitate an easier & speedier process for the user, you can optionally pass these details (urlencoded) to us and we'll pre-fill the form for them.

Authorisation Response

If the user approves the access request, then the response will contain the authorisation and the state parameter (if you sent it in the request). If the user does not grant access the request will contain an error message. The message will be sent on the response query string. Example responses are below:

Using the Refresh Token

As stated earlier, a refresh token is returned along with the access token and when the access token expires. You will need to refresh the access token after the expiration time. You may obtain a new access token by sending the refresh token to CommBank Simplify.

Revoking a Token

When a user wants to revoke access to their application, they can do so through the apps setting in the CommBank Simplify app. In CommBank Simplify, the access token will be revoked with the corresponding refresh token.

You can also revoke the token programmatically using one of CommBank Simplifys SDKs.

Create a Payment With Simplify Link

Now lets put it all together. Below are examples using the CommBank Simplify SDKs to create a payment using Simplify Link. The examples assume you have already created your OAuth keys in the app managment screen of CommBank Simplify and you have obtained an authorisation code.