Prepopulating transaction attributes

By default, the SDK will prompt users to enter all required attributes such as funder, provider and claim items to process a transaction. However, those attributes can be completely prepopulated from your system with the Medipass UI acting as a simple validation and error handling.

All of the top-level attributes listed below are optional to create a claim - only set what you wish. If an attribute is required by a particular fund, the user will be prompted to enter the value prior to claim submission.

Available attributes:

Virtual Terminal
Funders
- Generic attributes
- Funder-specific attributes

Virtual terminal

Schema

medipassTransactionSDK.renderCreateTransaction({
  platform: 'virtual-terminal',
  providerNumber: string,
  invoiceReference: string,
  chargeAmount: string,
  paymentMethod: "new-payment-card" | "phone" |"payment-link",
  patient: {
    mobile: string
  }
})

Reference

Field	Type	Max length	Notes
`providerNumber`	String	8	Usually the Medicare Provider Number. Else the funder specific provider number. Should be 8 characters alpha-numeric. This will change the cardholder's payment narrative and settlement if different rules are set for given provider and practice. Example: 1234565X
`invoiceReference`	String	16	Provider nominated unique transaction reference number, such as an invoice number from the practice management or accounting system.
`chargeAmount`	String		The amount to charge for the virtual terminal transaction. Example: 10.00
`paymentMethod`	"new-payment-card", "phone" or "payment-link"		Whether the payment should be processed by the provider as a one-off manual entry new-payment-card, the payment request should be sent via SMS to the patient or to generate a payment-link for email or inclusion in an invoice
`patient.mobile`	String		The mobile phone number of the patient. Can be either international notation: +61411111111 or national notation: 0411111111

Funders

Generic attributes (applicable to all funders)

These fields are common across funders. If you choose to limit integration efforts but wish to support the widest range of claiming scenarios, then the following fields could be used to set most required claim and payment attributes.

Schema

medipassTransactionSDK.renderCreateTransaction({
  funder: "comcare" | "dva" | "hicaps" | "patient-funded" | "icare" | "medicare" | "wcq"

  providerNumber: string,

  invoiceReference: string,

  patientId: string,
  // OR
  patient: {
    refId: string,
    firstName: string,
    lastName: string,
    mobile: string,
    dob: string,
    accountNumber: string,
    reference: string
  },

  claimableItems: [{
    itemCode: string,
    reference: string,
    serviceDateString: string,
    price: string,
    isGross: boolean,
    quantity: number,
    isTaxable: boolean
  }],

  webhooks: [{
    url: string,
    event:
      'invoiceBalancePaid' |
      'invoiceCancelled' |
      'invoiceCompleted' |
      'healthFundApprovedInvoice' |
      'healthFundRejectedInvoice',
    method: 'GET' | 'PUT' | 'POST' | 'DELETE',
    headers: { [key: string]: string }
  }],

  funderData: {
    /* see below for funder-specific attributes */
  }
}, {
  onSuccess: function (transaction) { /* ... */ },
  onError: function (error) { /* ... */ },
  onCancel: function () { /* ... */ }
})

Reference

Field	Type	Max length	Required?	Notes
`providerNumber`	String	8		Usually the Medicare Provider Number. Else the funder specific provider number. Should be 8 characters alpha-numeric. Example: 1234565X
`funder`	String			Example: `"hicaps"`, `"dva"`, `"medicare"`, `"patient-funded"`, `"wcq" "wsv"`. If no funder is selected, the provider will be prompted to select a funder.
`invoiceReference`	String	16		Provider nominated unique transaction reference number, such as an invoice number from the practice management or accounting system.

`patientId`	String			Medipass Business Patient ID. If supplied and valid, this value will pre-populate patient details from the patient record in the business.
OR
`patient.refId`	String			A patient unique reference as set by you. If supplied and valid, this value will pre-populate patient details from the patient record in the business. Any patient details sent for an existing patient record will update those values
OR
`patient`	Object
`patient.firstName`	String			Patient first name as registered with funder. Middle name is not supported. If patient has only one name, then set name in lastName field and set firstName to “Onlyname”.
`patient.lastName`	String			Patient last name as registered with funder.
`patient.dob`	String			Patient Date of Birth in ‘YYYY-MM-DD’ format. Example: ‘1967-11-02’
`patient.mobile`	String			The mobile phone number of the patient. Can be either international notation: +61411111111or national notation: 0411111111
`patient.accountNumber`	String			Unique funder issued account number for patient Maps to: medicareNumber (Medicare), dvaNumber (DVA), membershipNumber (HICAPS), claimNumber (icare) , claimNumber (Workcover Queensland)
`patient.reference`	String			Unique patient reference with funder Maps to: medicareReferenceNumber (Medicare), cardRank(HICAPS/PHI patient reference or individual identifier). Field ignored if cardRank is not applicable for funder.

`claimableItems`	Array{Object}			array of fund claimable items
`claimableItems[].serviceDateString`	String			Date of the service in 'YYYY-MM-DD' format.
`claimableItems[].itemCode`	String		Required	Item code - note item code must be valid for funder type and as of the service date.
`claimableItems[].reference`	String			Reference for claim item. Has to be unique for the the entire claim
`claimableItems[].price`	String			Net (excluding GST) price each In $XX.XX format. Example ‘$15.95’. Note: If this is the gross amount (including GST), set the `isGross` flag below to `true`.
`claimableItems[].isGross`	boolean			If set to `true`, this will indicate the `price` is the gross amount (including GST).
`claimableItems[].description`	String			Only used where provider description is required for a given itemCode.
`claimableItems[].quantity`	number			Only applicable for icare & Workcover Queensland. Denotes number of services or pieces of equipment provided as part of this service. Where funder has item code set to ignore quantity, field is ignored.
`claimableItems[].isTaxable`	boolean			Only applicable for icare & Workcover Queensland. Set to `true` if GST tax is applicable for item. Where funder has item code as tax free, field is ignored. maps to gst fields.
`claimableItems[].clinicalCode`	string			Only applicable for supported claim items (eg. tooth number in hicaps for dental claim items). Note: clinicalCode will be applied to claim items which supports it and ignored otherwise.
`claimableItems[].extras.duration`	string			Only applicable for DVA and Medicare. Time duration (in minutes) of the service item, in increments of 15. Example: `"15"`, `"30"`, `"45"`, etc
`claimableItems[].extras.secondDevice`	`"Y"` \| `"N"`			Only applicable for DVA. `"Y"` for Yes, `"N"` for No.
`claimableItems[].extras.treatmentLocation`	`"V"` \| `"H"` \| `"R"` \| `"N"` \| `"C"`			Only applicable for DVA. `"V"` for Home Visit. `"H"` for Hospital. `"R"` for Rooms. `"N"` for Residential Care Facility. `"C"` for Community Health Centres.
`claimableItems[].extras.distanceTravelled`	`string`			Only applicable for DVA. Distance travelled in kilometres.

Comcare attributes

These fields apply to claims processed via Comcare.

The following general field are not applicable for Comcare claims and are ignored:

patient.mobile
patient.email
patient.reference
nonClaimableItems

The Medipass Comcare integration supports provider submission of supporting documentation, such as certificates of fitness/capacity, surgical/operation reports, allied health recovery requests and similar. However, these attachments must be added in the Medipass modal or iframe user interface.

Schema

medipassTransactionSDK.renderCreateTransaction(
  {
    /* ... generic attributes from above */

    patient: {
      ...
      accountNumber: string, // maps to Comcare claim number
      ...
    }

    funderData: {
      comcare: {
        serviceNotes: string
      }
    }
  },
  {
    onSuccess: function(transaction) {
      /* ... */
    },
    onError: function(error) {
      /* ... */
    },
    onCancel: function() {
      /* ... */
    }
  }
);

Reference

Field	Type	Max length	Required?	Notes
`serviceNotes`	String	512		Service notes for the transaction. Usually used for claims with exceptions.

DVA attributes

For all DVA transactions, it’s important the patient details match exactly to that listed on a DVA card rather than what may be recorded in your system. Medipass will prompt the user to verify and update details where account details vary from those registered with DVA.

The following general field are not applicable for DVA claims and are ignored:

claimableItems[].description
claimableItems[].quantity
claimableItems[].unit
claimableItems[].isTaxable

Schema

medipassTransactionSDK.renderCreateTransaction(
  {
    /* ... generic attributes from above */

    funderData: {
      lspn: string,
      facilityId: string,
      isInHospital: boolean,
      treatmentLocation: 'V' | 'H' | 'R' | 'N' | 'C' | undefined
      dva: {
        referral: {
          providerNumber: string,
          providerName: string,
          referrerType: 'gp' | 'specialist',
          issueDateString: string,
          period: 'standard' | 'non-standard' | 'indefinite'
        },
    nonReferral: {
          reason: 'hospital' | 'lost' | 'emergency' | 'not-required' | 'remote-exemption',
          description: string
        }
      }
    }
  },
  {
    onSuccess: function(transaction) {
      /* ... */
    },
    onError: function(error) {
      /* ... */
    },
    onCancel: function() {
      /* ... */
    }
  }
);

Reference

Field	Type	Notes
`lspn`	String	Location Specific Practice Number. LSPN may be required for diagnostic imaging items. When set, this value will be set on all claimed items.
`isInHospital`	Boolean	Set to true for admitted patient services. Defaults to false. Value applied for all claimed item.
`facilityId`	String	When isInHospital set to true, the Commonwealth Hospital Facility ID must be supplied which shares same format as a Medicare issued providerNumber.
`treatmentLocation`	Strimg	'V' (Home visit), 'H' (Hospital), 'R' (Rooms), 'N' (Residential Care facility), 'C' (Community Health Centres)
`referral.providerNumber`	String	Referring provider number - usually a DVA issued number.
`referral.providerName`	String	Name of the referring provider.
`referral.referrerType`	String	Type of the referring provider. 'gp' or 'specialist'.
`referral.issueDateString`	String	Issue date of the referral in YYYY-MM-DD format. Example “2019-01-25”.
`referral.period`	String	Period of the referral. Can be: 'standard', 'non-standard', 'indefinite'
`referral.periodDescription`	String	Number of months if `referral.period` is set to 'non-standard'

Claimable items

Additional item attributes such as admitted patient indicator, service text, Number Of Patients Seen and Duplicate Service Overrides can be set in the Medipass UI. A maximum of 16 items are permitted for patient claims and 80 items per bulk bill claim.

HICAPS attributes

These additional fields apply to claims processed via HICAPS including private health insurance and overseas insurance.

The following general field are not applicable for HICAPS claims and are ignored:

claimableItems[].description
claimableItems[].quantity
claimableItems[].unit
claimableItems[].isTaxable
claimableItems[].extras

Schema

medipassTransactionSDK.renderCreateTransaction(
  {
    /* ... generic attributes from above */

    nonClaimableItems: [
      {
        description: string,
        price: string,
        isGross: boolean
      }
    ],

    funderData: {
      hicaps: {
        patient: {
          healthFundCode: string
        }
      }
    }
  },
  {
    onSuccess: function(transaction) {
      /* ... */
    },
    onError: function(error) {
      /* ... */
    },
    onCancel: function() {
      /* ... */
    }
  }
);

Reference

Field	Type	Max length	Required?	Notes
`nonClaimableItems`	Array{Object}			Array of items paid by patient
`nonClaimableItems[].description`	String		Required	Description of good/service.
`nonClaimableItems[].price`	String			Net (excluding GST) price each In $XX.XX format. Example ‘$15.95’. Note: If this is the gross amount (including GST), set the `isGross` flag below to `true`.
`nonClaimableItems[].isGross`	boolean			If set to `true`, this will indicate the `price` is the gross amount (including GST).

`patient.healthFundCode`	String	8		Patient Health Fund Code. See Supported funders for a list of valid health fund codes.

Claimable & non-claimable items

Both claimable and non-claimable items can be set. Any gap amount (including all non-claimable items) will be processed as patient payment request via debit/credit cards. Note there is a maximum of 24 service items permitted per claim.

icare attributes

These fields apply to claims processed via icare including workers insurance, motor accident and other funding schemes.

The following general field are not applicable for icare claims and are ignored:

patient.mobile
patient.email
patient.dob
patient.reference
nonClaimableItems

The Medipass icare integration supports provider submission of supporting documentation, such as certificates of fitness/capacity, surgical/operation reports, allied health recovery requests and similar. However, these attachments must be added in the Medipass modal or iframe user interface.

Schema

medipassTransactionSDK.renderCreateTransaction(
  {
    /* ... generic attributes from above */

    patient: {
      ...
      accountNumber: string, // maps to icare claim/approval number
      healthFundCode: string, // icare insurance scheme
      ...
    }

    funderData: {
      icare: {
        serviceNotes: string
      }
    }
  },
  {
    onSuccess: function(transaction) {
      /* ... */
    },
    onError: function(error) {
      /* ... */
    },
    onCancel: function() {
      /* ... */
    }
  }
);

Reference

Field	Type	Max length	Required?	Notes
`healthFundCode`	String	3	Required	Set to "IWC" for Workers Insurance
`serviceNotes`	String	512		Service notes for the transaction. Usually used for claims with exceptions.

Medicare attributes

These additional fields apply to claims processed directly with Medicare including bulk bill and patient claims. For patient claims, there is also an option to set claimant details - where someone other than the patient pays for the service and receives the Medicare benefit. By default, the servicing provider will be set to the payee provider (the recipient for bulk bill payments). However, a different payee provider number can be specified at each transaction or as a default for the provider in the Medipass portal.

For all Medicare transactions, it’s important the patient and/or claimant details match exactly to that listed on a Medicare card rather than what may be recorded in your system. Medipass will prompt the user to verify and update details where account details vary from those registered with Medicare.

The following general field are not applicable for Medicare claims and are ignored:

claimableItems[].description
claimableItems[].quantity
claimableItems[].unit
claimableItems[].isTaxable

Schema

medipassTransactionSDK.renderCreateTransaction(
  {
    /* ... generic attributes from above */

    funderData: {
      medicare: {
        isBulkBilled: boolean,
        lspn: string,
        facilityId: string,
        isInHospital: boolean,

        claimantPatientId: string,
        // OR
        claimant: {
      refId: string,
          firstName: string,
          lastName: string,
          mobile: string,
          dob: string,
          accountNumber: string,
          reference: string
        },

        referral: {
          providerNumber: string,
          providerName: string,
          referrerType: 'gp' | 'specialist',
          issueDateString: string,
          period: 'standard' | 'non-standard' | 'indefinite',
          periodDescription: number
        },
    nonReferral: {
          reason: 'hospital' | 'lost' | 'emergency' | 'not-required' | 'remote-exemption',
          description: string
        }
      }
    }
  },
  {
    onSuccess: function(transaction) {
      /* ... */
    },
    onError: function(error) {
      /* ... */
    },
    onCancel: function() {
      /* ... */
    }
  }
);

Reference

Field	Type	Max length	Notes
`isBulkBilled`	Boolean	8	Denotes if transaction is a bulk-bill claim (true) or patient claim (false).
`lspn`	String		Location Specific Practice Number. LSPN may be required for diagnostic imaging items. When set, this value will be set on all claimed items.
`isInHospital`	Boolean		Set to true for admitted patient services. Defaults to false. Value applied for all claimed item.
`facilityId`	String		When isInHospital set to true, the Commonwealth Hospital Facility ID must be supplied which shares same format as a Medicare issued providerNumber.
`claimantPatientId`	String		Medipass Business Patient ID. If supplied and valid, this value will pre-populate claimant details from Medipass records.
OR
`claimant[].firstName`	String		Claimant first name as displayed on Medicare card. Middle name is not supported. If patient has only one name set first name field to ‘Onlyname’ and set name in lastName.
`claimant[].lastName`	String		Claimant last name as displayed on Medicare card.
`claimant[].mobile`	String		Mobile Phone number of the claimant
`claimant[].dob`	String		Claimant Date of Birth in ‘YYYY-MM-DD’ format. Example: ‘1967-11-02’
`claimant[].accountNumber`	String		Claimant Medicare card number.
`claimant[].reference`	String		Claimant Individual Reference Number from Medicare card eg 1, 2 etc. This number appears on the left of the cardholder's name on the medicare card and distinguishes the individuals named on the card.

`referral.providerNumber`	String		Referring provider number - usually a Medicare issued number.
`referral.providerName`	String		Name of the referring provider.
`referral.referrerType`	String		Type of the referring provider. 'gp' or 'specialist'.
`referral.issueDateString`	String		Issue date of the referral in YYYY-MM-DD format. Example “2019-01-25”.
`referral.period`	String		Period of the referral. Can be: 'standard', 'non-standard', 'indefinite'
`referral.periodDescription`	Number		Number of months if `referral.period` is set to 'non-standard'

Claimable items

Workcover Queensland attributes

To process a Workcover Queensland workers insurance claim, the following fields apply. Any required field not passed to the SDK will be prompted at the Medipass submission page.

Field	Type	Max length	Required?	Notes
`funder`	String		Required	Set to wcq for Workcover Queensland claims.
`providerNumber`	String		Required	For medical or allied healthcare providers, this is usually a Medicare issued provider number - 8 characters alpha-numeric such as 1234565X. If Medicare provider number is not applicable, Workcover Queensland account numbers (Pxxxxxxxxxx) for non-medical providers and AHPRA numbers are also supported if that same number was registered with Medipass.
`invoiceReference`	String	20		Provider nominated unique transaction reference number, such as an invoice number from the practice management or accounting system. Used for reconciliation purposed.
-----
`patient`	Object
`patient.firstName`	String		Required	Patient first name as registered with fund. Middle name is not supported. If patient has only one name, then set name in lastName field and set firstName to “Onlyname”.
`patient.lastName`	String		Required	Patient last name as registered with fund.
`patient.dob`	String		Required	Patient Date of Birth in ‘YYYY-MM-DD’ format. Example: ‘1967-11-02’
`patient.mobile`	String			The mobile phone number of the patient. Can be either international notation: +61411111111 or national notation: 0411111111
`patient.accountNumber`	String	11	Required	Set to the Workcover Queensland issued Claim Number. Usually, these are formatted like `SNNAANNNNNN` or `DNNAANNNNNN` where N = numeric and A = alpha character.
`patient.accidentDate`	String			Date of accident/injury in 'YYYY-MM-DD' format.
OR
`patient.refId`	String			A patient unique reference as set by you. If supplied and valid, this value will pre-populate patient details from the patient record in the business as set in any prior claim. Any patient details sent for an existing patient record will update those values
-----
`claimableItems`	Array{Object}			Array of fund claimable items.
`claimableItems[].reference`	String			Unique item reference for reconciliation in your system, such as `001`. This reference must be unique for each item in the claim.
`claimableItems[].serviceDateString`	String		Required	Date of the service in 'YYYY-MM-DD' format.
`claimableItems[].itemCode`	String	10	Required	Item code - note item code must be valid for funder, the provider registered profession and service date.
`claimableItems[].price`	String		Required	Net (excluding GST) price each unit in $XX.XX format. Example ‘$15.95’.
`claimableItems[].quantity`	Number			Denotes number of services or pieces of equipment or other unit of measure as part of this service. Where funder has item code set to ignore quantity, field is ignored.
`claimableItems[].isTaxable`	Boolean			Set to `true` if GST tax is applicable.
`claimableItems[].serviceText`	String	2000		Additional item level description or commentary.
`claimableItems[].isGross`	Boolean			If set to `true`, this will indicate the `price` is the gross amount including GST tax for the item submitted. For example, if set to true and price is $11.00, item price excluding tax is $10.00 and GST of 10% / $1.00 is applied.
`claimableItems[].isExtendedPrice`	Boolean			If set to true, this will indicate the price is extended/aggregate price for all quantities submitted. For example, if set to true, and price is $20.00 with three quantity (effectively $6.66666 per unit) as sent to a funder. Otherwise, if set to false or omitted the price field will be multiplied per quantity claimed. For example, if set to false, price is $20.00 with three quantity, each item price is $20.00 which will make extended price $60.00 as sent to a funder.

At present, Workcover Queensland is not returning the outcome of a claim decision - approved, declined or otherwise. Updates on the claim and any payment remittance to providers will be supplied directly by Workcover Queenland either via email or their Provider Connect web portal. Providers can manually mark a claim as approved/paid in Medipass which will trigger a webhook event.

Schema

medipassTransactionSDK.renderCreateTransaction({
  funder: string,
  providerNumber: string,
  invoiceReference: string,
  patient: {
    refId: string,
    firstName: string,
    lastName: string,
    mobile: string,
    dob: string,
    accountNumber: string,
    accidentDate: string
  },

  claimableItems: [{
    reference: string,
    itemCode: string,
    serviceDateString: string,
    price: string,
    quantity: number,
    isTaxable: boolean,
    serviceText: string,
    isGross: boolean,
    isExtendedPrice: boolean
  }],

  webhooks: [{
    url: string,
    event:
      'invoiceCompleted' |
    method: 'GET' | 'PUT' | 'POST' | 'DELETE',
    headers: { [key: string]: string }
  }],

}, {
  onSuccess: function (transaction) { /* ... */ },
  onError: function (error) { /* ... */ },
  onCancel: function () { /* ... */ }
})