@medipass/partner-sdk

v3.1.0

Published

a month ago

Medipass Partner SDK

The Medipass Partner SDK is a client-side JavaScript library which allows you to interact with Medipass from your web interface.

Partner-facing release notes are available in the SDK changelog.

Medipass Partner SDK

Install

yarn add @medipass/partner-sdk

or NPM:

npm install @medipass/partner-sdk

Basic Usage

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

medipassTransactionSDK.setConfig({
  env: 'stg',
  apiKey: 'xyz',
  appId: 'my-app',
  appVersion: '1.0.0'
});

medipassTransactionSDK.renderCreateTransaction(
  {},
  {
    onSuccess: data => {
      // handle success
    },
    onError: data => {
      // handle success
    },
    onCancel: () => {
      // handle cancel
    }
  }
);

TypeScript

The SDK publishes TypeScript declarations for configuration, callbacks, render options, and funder payloads.

import type { QbeCreateTransactionPayload, SdkCreateTransactionRenderOptions } from '@medipass/partner-sdk';

const payload: QbeCreateTransactionPayload = {
  funder: 'qbe',
  patient: {
    firstName: 'Ada',
    lastName: 'Lovelace',
  },
};

const options: SdkCreateTransactionRenderOptions = {
  onSuccess: transaction => {
    console.log(transaction);
  },
};

With 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: 'xyz',
        appId: 'my-app',
        appVersion: '1.0.0'
      });

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

API

sdk.setConfig(config)

config

{
  env: 'stg' | 'prod',
  apiKey: string,
  appId: string,
  appVersion: string
}

sdk.renderCreateTransaction(payload, options)

payload

With the payload parameter, you are able to pre-populate SDK fields. All attributes in the payload are optional (however, attributes marked with a ! are required) - so you can pre-populate what you wish.

{
  /* ====== START: GENERAL PRE-POPULATION ATTRIBUTES ====== */
  funder: "medicare" | "hicaps" | "patient-funded" | "ghs",

  providerNumber: string,

  invoiceReference: string,

  memberId: string, // Medipass Member ID
  // OR
  patient: {
    firstName: string,
    lastName: string,
    mobile: string,
    dob: string, // "YYYY-MM-DD" format
    accountNumber: string, // Medicare card number / PHI card number
    reference: string // Medicare card reference / PHI card rank
  },

  claimableItems: [{
    itemCode!: string,
    serviceDateString: string, // "YYYY-MM-DD" format
    price: string, // E.g. "$40.00"
    quantity: number,
    isTaxable: boolean
  }],

  nonClaimableItems: [{
    description!: string,
    price: string
  }],

  webhooks: [{
    url!: string,
    event!:
      'memberApprovedInvoice' |
      'memberRejectedInvoice' |
      'medipassAutoCancelledInvoice' |
      'healthFundApprovedInvoice' |
      'healthFundRejectedInvoice',
    method!: 'GET' | 'PUT' | 'POST' | 'DELETE',
    headers: { [key: string]: string }
  }],
  /* ====== END: GENERAL PRE-POPULATION ATTRIBUTES ====== */

  /* ====== START: FUNDER-SPECIFIC PRE-POPULATION ATTRIBUTES ====== */
  funderData: {
    hicaps: {
      patient: {
        healthFundCode: string
      },
      transactionMethod: 'phone' | 'terminal'
    },
    medicare: {
      isBulkBilled: boolean,

      // Optional Medicare Bulk bill Assignment of Benefit configuration.
      // If omitted, the AoB section is not shown and agreementMethod defaults to 'external'.
      // If provided, the AoB section is shown. Use {} to show it without a preset agreement method.
      aob: {
        agreementMethod: 'external' | 'tyro',
        isAssignorPatient: boolean,
        mobile: string
      },

      claimantMemberId: string, // Medipass Member ID
      // OR
      claimant: {
        firstName: string,
        lastName: string,
        mobile: string,
        dob: string, // "YYYY-MM-DD" format
        accountNumber: string, // Medicare card number / PHI card number
        reference: string // Medicare card reference / PHI card rank
      },

      referral: {
        providerNumber: string,
        providerName: string,
        issueDateString: string,
        period: 'standard' | 'non-standard' | 'indefinite'
      }
    },
    ghs: {
      isEmergencyTreatment: boolean,
      includesHospitalInpatientItems: boolean,
      failedToAttendClaim: boolean,
      dan: string,
      referringJointHealthCentre: string,
      referringMedicalOfficer: string,
      noDan: boolean,
      noDanReason: string,
      noEpId: boolean,
      noEpIdReason: string
    }
  }
  /* ====== END: FUNDER-SPECIFIC PRE-POPULATION ATTRIBUTES ====== */
}

Medicare Bulk bill Assignment of Benefit

For Medicare bulk bill claims, funderData.medicare.aob is optional so existing PMS integrations can continue sending Medicare payloads unchanged.

Omit aob to hide the AoB section and record the agreement method as external.
Send aob: {} to show the AoB section with no agreement method selected.
Send aob: { agreementMethod: 'external' } to show the AoB section with External selected.
Send aob: { agreementMethod: 'tyro' } to show the AoB section with Tyro Health selected.
For Tyro Health AoB, optionally send isAssignorPatient and mobile to prefill the assignor details.
mobile is treated as the assignor mobile. If it differs from the patient mobile, Connect treats it as a different mobile number.

When Tyro Health AoB is used, transaction/webhook responses expose the current AoB status on the transaction claim response so PMS integrations can reflect pending and submitted agreement states.

options

{
  onSuccess: function(transaction) {},  // Invoked when the transaction has submitted successfully.
  onError: function(error) {},          // Invoked when the transaction submission failed.
  onCancel: function() {},              // Invoked when the 'Cancel' button is clicked.

  // Optional config overrides - if not set, will use global config from sdk.setConfig().
  env: 'stg' | 'prod',
  apiKey: string,
  appId: string,
  appVersion: string
}

sdk.renderTerminalPayment(payload, options)

Starts a Tyro EFTPOS terminal payment for a transaction created by your server and displays the terminal status flow. Call sdk.setConfig(config) before rendering so the request uses your SDK authentication and application details.

Terminal payment payload

{
  transactionId: string, // Transaction _id created by your server.
  terminalId: string,    // Internal Tyro Health terminal _id.
  merchantId: string     // Merchant id associated with the terminal.
}

Terminal payment options

{
  onSuccess: function(transaction) {},
  onCancel: function() {},
  onError: function(error) {},
  onCloseModal: function({ status, transaction, error }) {},

  // Optional config overrides - if not set, global config from sdk.setConfig() is used.
  env: 'stg' | 'prod',
  apiKey: string,
  appId: string,
  appVersion: string,
  containerId: string, // Optional. Renders inline when supplied; otherwise opens a modal.
  height: string | number,
  width: string | number
}

await sdk.setConfig({
  env: 'stg',
  apiKey: 'xyz',
  appId: 'my-app',
  appVersion: '1.0.0'
});

sdk.renderTerminalPayment(
  {
    transactionId: 'transaction-id',
    terminalId: 'terminal-record-id',
    merchantId: 'merchant-id'
  },
  {
    onSuccess: transaction => console.log('Payment approved', transaction),
    onCancel: () => console.log('Payment cancelled'),
    onError: error => console.error('Unable to start terminal payment', error)
  }
);

An errored terminal response remains in the flow so the user can retry or cancel. If the /pays request itself fails, the error is shown in the SDK and onError is invoked when the user closes the error screen.

For approved payments, onSuccess runs before onCloseModal with status: 'success'. For cancelled or declined payments, onCancel runs before onCloseModal with status: 'cancelled'. Fatal /pays errors call onError followed by onCloseModal with status: 'error'. The SDK frame closes after these callbacks settle.

sdk.renderViewTransaction(query, options)

query

{
  // required
  transactionId: string,

  // Optional override Business ID - by default, it uses business attached to API Key.
  businessId: string
}

options

{
  // Optional config overrides - if not set, will use global config from sdk.setConfig().
  env: 'stg' | 'prod',
  apiKey: string,
  appId: string,
  appVersion: string
}

sdk.members.discoverMember(options)

options

Discover a member using query parameters.

The response will be the matching member's internal ID. If a custodians array field is also present, the matching member is a dependant. Each custodian object contains the custodian's member ID, first name and last name. The custodian is important when creating an invoice for a dependant because the claim/payment authorisation can only be performed by a custodian. A dependant inherits their custodians' email and mobile, and therefore will be included in such a search.

Email and mobile are the primary search parameters. The order of search parameter priorities are as follows: email > mobile > dobString > lastName > firstName.

The following search sets are recommended:

{ email }
{ mobile, dobString }
{ mobile, firstName, lastName }
{ dobString, firstName, lastName }

The following query sets are not allowed:

{ firstName }
{ lastName }
{ dobString }
{ firstName, dobString }
{ lastName, dobString }

{
  query: {
    email: string,
    mobile: string,
    dobString: string, // "YYYY-MM-DD"
    firstName: string,
    lastName: string
  }
}

Example

medipassTransactionSDK.members.discoverMember({ email: '[email protected]' });

sdk.providers.getProvidersStatus(options)

options

Retrieve a business' provider and their status.

A provider number must be supplied as a query param to filter the results and return a single provider.

{
  query: {
    providerNumber: string
  }
}

Example

Get provider status

sdk.payments.getBusinessPatientPaymentMethods(options)

options

Retrieve a patient's payment methods.

A patient id must be supplied as a query parameter.

{
  query: {
    patientId: string
  }
}

Example

Get payment methods by patient id

sdk.payments.getBusinessPatientPaymentMethodsByRefId(options)

options

Retrieve a patient's payment methods by a patient's ref id.

A patient's ref id must be supplied as a query parameter.

{
  query: {
    refId: string
  }
}

Example

Get payment methods by patient ref id

sdk.claimItems.getBusinessClaimItems(options)

options

Get a list of claim items. A claim item describes a service that a patient can claim against.

{
  query: {
    page: number,
    limit: number,
    searchText: string
    itemCode: string,
    funderCode: string,
    funderId: string,
    modalityId: string,
    serviceDateString: string,
    isBulkBilled: string,
    isInHospital: string
  },

  // Optional override Business ID - by default, it uses business attached to API Key.
  businessId: string
}

Example

medipassTransactionSDK.claimItems.getBusinessClaimItems({
  query: {
    page: 1,
    limit: 10,
    funderCode: 'medicare',
    searchText: 'Awesome Item'
  }
});

sdk.transactions.getBusinessTransaction(options)

options

Get transaction details for a business.

{
  // Required
  transactionId: string,

  // Optional override Business ID - by default, it uses business attached to API Key.
  businessId: string
}

Example

medipassTransactionSDK.transactions.getBusinessTransaction({ transactionId: '123' });

sdk.transactions.downloadPDF(options, requestOptions, downloadOptions)

Async function that returns a PDF blob.

options

Downloads the transaction summary in PDF format.

Note: this method is only supported for Medicare transactions and downloads the Medicare statement.

{
  // Required
  transactionId: string,

  // Optional override Business ID - by default, it uses business attached to API Key.
  businessId: string
}

requestOptions

downloadOptions

{
  // Optional - when set to true, the PDF will not be automatically downloaded on the client.
  suppressLocalDownload: string

}

Example

medipassTransactionSDK.transactions.downloadPDF({ transactionId: '123' });

sdk.transactions.getPaymentReport(options)

options

Fetches the payment report for a given transaction. Response is in JSON format.

Note: this method is only supported for Medicare transactions.

{
  // Required
  transactionId: string,

  query: {
    // When true, the payment report is retrieved in real time and the cache is updated if successful.
    forceRefresh: boolean
  },

  // Optional override Business ID - by default, it uses business attached to API Key.
  businessId: string
}

Response

{
  requestedDate: string,
  reportResult: number,
  sessionId: number,
  paymentRunDateString: string,
  paymentRunNumber: string,
  amountBenefitPaidString: string,
  bankAccount: {
    accountNumber: string,
    bsb: string,
    accountName: string
  },
  payments: [
    {
      claimId: string,
      claimDateString: string,
      amountChargedString: string,
      amountBenefitPaidString: string,
      amountDepositedString: string
    }
  ]
}

Example

medipassTransactionSDK.transactions.getPaymentReport({ transactionId: '123', query: { forceRefresh: true } });

sdk.transactions.getProcessingReport(options)

options

Fetches the processing report for a given transaction. Response is in JSON format.

Note: this method is only supported for Medicare transactions.

{
  // Required
  transactionId: string,

  query: {
    // When true, the processing report is retrieved in real time and the cache is updated if successful.
    forceRefresh: boolean
  },

  // Optional override Business ID - by default, it uses business attached to API Key.
  businessId: string
}

Response

{
  requestedDate: string,
  reportResult: number,
  sessionId: number,
  amountChargedString: string,
  amountBenefitPaidString: string,
  providerNumber: string,
  claimItems: [
    {
      serviceDateString: string,
      itemCode: string,
      claimId: string,
      serviceId: string,
      amountBenefitString: string,
      gatewayCode: string,
      gatewayDescription: string,
      amountChargedString: string,
      healthFundAccount: {
        membershipNumber: string,
        cardRank: string
      },
      patient: {
        firstName: string,
        lastName: string
      },
      cardFlag: string,
      cardFlagDescription: string,
      numberOfPatientsSeen: string,
      voucherId: string
    }
  ]
}

Example

medipassTransactionSDK.transactions.getProcessingReport({ transactionId: '123', query: { forceRefresh: true } });

sdk.buildTransactionUrl(payload, config)

payload

config

Returns a standalone URL.

Examples

Examples are maintained in the Tyro Health Online SDK tab so they stay aligned with the current Connect standalone routes.

Browser support

The Medipass Transaction SDK targets the same modern browser versions as Tyro Health Online: Chrome 111+, Edge 111+, Firefox 114+, Safari 16.4+, and iOS Safari 16.4+. Older zoid-based embeds remain supported by the Tyro Health Online standalone host compatibility shim while partners migrate to newer SDK builds.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

Medipass Partner SDK

Table of Contents

Install

Basic Usage

TypeScript

With a <script> tag

API

sdk.setConfig(config)

config

sdk.renderCreateTransaction(payload, options)

payload

Medicare Bulk bill Assignment of Benefit

options

sdk.renderTerminalPayment(payload, options)

Terminal payment payload

Terminal payment options

sdk.renderViewTransaction(query, options)

query

options

sdk.members.discoverMember(options)

options

Example

sdk.providers.getProvidersStatus(options)

options

Example

sdk.payments.getBusinessPatientPaymentMethods(options)

options

Example

sdk.payments.getBusinessPatientPaymentMethodsByRefId(options)

options

Example

sdk.claimItems.getBusinessClaimItems(options)

options

Example

sdk.transactions.getBusinessTransaction(options)

options

Example

sdk.transactions.downloadPDF(options, requestOptions, downloadOptions)

options

requestOptions

downloadOptions

Example

sdk.transactions.getPaymentReport(options)

options

Response

Example

sdk.transactions.getProcessingReport(options)

options

Response

Example

sdk.buildTransactionUrl(payload, config)

payload

config

Examples

Browser support

With a `<script>` tag