Getting started

Processing a claim or payment transaction with Medipass requires three steps:

Setup the Transaction SDK

Requirements

The Transaction SDK requires a valid API Key, App ID and App Version. It is also recommended that you set the Environment to staging when testing the SDK in development.

Environment

Two environments are available:

stg: our staging / testing environment. This represents a production like environment but uses test account details and stubs to simulate responses from funders. By default, some external notifications like SMS are normally disabled but can be enabled via help desk request.
prod: our production environment.

API keys

An API key grants access to a business and all related providers and resources including practices, staff members, claims, payments and patients data. API keys are unique to a business account in Medipass. For example, an allied healthcare business “Always Healthy Pty Ltd” with four practice locations and 20 providers can use a single API key to create claims and access remittance details across the business.

How do I create an API key?

The API key can only be created by the Business Admin using the Medipass portal.

As a Business Admin, login to the Medipass portal: https://connect.medipass.io
Select Medipass account in the bottom left hand corner
In the API Keys panel, select Generate API Key
The API Key will be displayed

As the API key is specific to a business and can be used to access sensitive resources, it should be stored securely in your system - preferably via strong encryption with associated key management.

Note: The Business Admin API key carries many privileges and should remain secret and not exposed to end users or on client-side code. We provide a specially permissioned short-lived SDK authentication token which can be used to process transactions.

App IDs

An App ID allows us to identify who you are, so Medipass can debug problems & pinpoint where issues are arising from. You can choose to specify a single application name or generate different App IDs for each version of your software. Your App ID must be registered with Medipass. Contact Medipass via support@medipass.com.au or via chat to apply for your App ID.

App Version

The application version can be set to a value of your choosing. Ideally, this is aligned to your software release version and assists Medipass with debug and support inquires.

Domain whitelist

For security reasons, Medipass will also need to whitelist your origin domain names. Please contact support@medipass.com.au so we can add your domains to our content security policy. Until registered, you will get a CORS error for any unregistered originating domains.

Installation

The Transaction SDK can be installed via NPM/Yarn or downloaded via unpkg.com. If you plan to use the SDK as a JavaScript module, then install the NPM/Yarn package. If you plan to use the SDK with a <script> tag or other URL direction method, then use the unpkg.com version.

Install via NPM/Yarn

npm install @medipass/partner-sdk
// or, with yarn:
yarn add @medipass/partner-sdk

Download via unpkg.com

https://unpkg.com/@medipass/partner-sdk/umd/@medipass/partner-sdk.min.js

Using the JavaScript Module

import medipassSDK from '@medipass/partner-sdk';
// or: const medipassSDK = require('@medipass/partner-sdk');

medipassSDK.setConfig({
  env: 'stg',
  apiKey: '[insert your API key here]',
  appId: '[insert your App ID here]',
  appVersion: '[insert your App version here]'
});

medipassSDK.renderCreateTransaction({}, {
  onSuccess: function (transaction) {
    // handle successful submission of transaction
  },
  onError: function (error) {
    // handle errored submission of transaction
  },
  onCancel: function () {
    // handle when create transaction flow has been cancelled
  }
});

Using a `<script>` tag

<html>
<head>
  <script src="https://unpkg.com/@medipass/partner-sdk/umd/@medipass/partner-sdk.min.js"></script>
</head>
<body>
  <script>
    MedipassTransactionSDK.setConfig({
      env: 'stg',
      apiKey: '[insert your API key here]',
      appId: '[insert your App ID here]',
      appVersion: '[insert App version key here]'
    });

    MedipassTransactionSDK.renderCreateTransaction({}, {
      onSuccess: data => {
        // handle success
      },
      onError: data => {
        // handle error
      },
      onCancel: () => {
        // handle cancel
      }
    });
  </script>
</body>
</html>

Short-lived SDK token

Although the Business Admin API token can be used to directly process SDK transactions, the key could be obtained by lesser privileged users, such as a practice manager, provider or analyst. Those users could potentially decompile the SDK and look for this static API key.

To mitigate risks of unauthorised Business Admin API key disclosure, we provide a short-lived SDK authentication token option.

To use the short-lived token:

On your server-side, use the Business Admin API key to call:

Resource

POST <base-url>/v3/auth/token

Where base-url:

Staging: stg-api-au.medipass.io

Production: api-au.medipass.io

Required headers

authorization: Bearer <Business_Admin_API_key>
x-appid: your App ID

Payload

{
    "audience": "aud:business-sdk",
    "expiresIn": "1h"    // e.g. 30m, 1h, 6h, 24h. Defaults to 1h, max is 24h.
}

The response will contain a short-lived token that is restricted to SDK features. For example, it can't be used to generate more tokens, update business details or create other users in a business.

{
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ2ZXIiOjEsImlhdCI6MTU5Mzc1NzI1MCwiZXhwIjoxNTkzNzYwODUwLCJhdWQiOiJhdWQ6YnVzaW5lc3Mtc2RrIiwic3ViIjoiNTc0M2NiNWI1YjI0Y2MxNDAwOTk5MTcwIiwianRpIjoiNVctZDZLIn0.YbbogFjmk7-BT15aY7vqHfFcXpH5Smr9LT96hHUjlWQ"
}

Return this token to your portal, and use it for the SDK apiKey field.