Private Health Claiming API Reference

API Production Endpoint

https://healthclaims.touchcorp.com/v1/
https://healthclaims.touchcorp.com/v1.1/

API Integration Endpoint

https://healthclaims-3pi.touchcorp.com/v1/
https://healthclaims-3pi.touchcorp.com/v1.1/

API Certification Endpoint

https://healthclaims-stg.touchcorp.com/v1/
https://healthclaims-stg.touchcorp.com/v1.1/

Document Version 1.8 | Last updated: Thursday, 30 May, 2019

Strictly Confidential

The Afterpay Touch Private Health Claiming API can be used by a Practice Management Systems (PMS) to perform Extra Covers claims in practice.

The document has language examples in curl. You can view code examples in the dark area to the right.

API Update Guidelines

Our API is constantly being updated with new features and improvements. These updates ensure the API evolves with customer and industry demands. Managing this change to ensure we provide a reliable, consistent, and backward compatible API design is a key focus for our customers. Every new and improved feature is put through a peer review process to ensure:

it will not change an existing resource to the extent it breaks current customer implementations,
that it is consistent with existing resources (therefore predictable and easy to use).

The following guidelines are used in our peer review process to understand what constitutes acceptable change for the API and our customers.

Changes we avoid:

Removing or renaming request or response content fields
Removing or renaming query string parameters
Removing or changing the location of a resource
Changing the API domain

Changes we approve and introduce:

Adding new resources
Adding new, optional request content fields
Adding new, optional query string parameters
Adding new response content fields
Adding new response header information

If, for any reason, we cannot avoid any of the non-backward compatible changes mentioned above, we will implement a deprecation schedule. This schedule will be provided to all customers with the goal of giving them adequate time to accommodate the updates.

Additional information:

Undocumented resources and properties are considered to be in beta release and are subject to change without notification.

REST

The Afterpay Touch Private Health Claiming API is organized around REST. The API attempts to use predictable, resource-oriented URLs and to use HTTP response codes to indicate errors.

The API will occasionally deviate from REST principles to reduce chattiness so that latency is minimised.

HTTPS

The Afterpay Touch Private Health Claiming API requires all communications to be secured using TLS 1.2 or greater.

Request and Response Headers

Clients must send appropriate headers with all requests.:

HTTP Headers

Field Name	Requirement	Description
Authorization	`required`	See Authentication
Content-Type	`required`	All `POST` and `PUT` requests must declare the content-type as `application/json`
User-Agent	`recommended`	All requests must include information about the Afterpay Touch Merchant and PMS Platform For example: Merchant/`{merchantname}`; PMS/`{pmsnameame}`; PMS Version/`{pmsversionumber}`; MerchantId/`{pmsmerchantId}`; Reception/`{pmsreceptionId}`; Device/`{deviceId}`
Accept	`recommended`	All requests must accept `application/json` or `/`
Operator	`required`	See PMS Operator Identification

All endpoint responses provide data as JSON in the response body and include the header:

Content-Type: application/json

Activation

Will use Afterpay Touch standard activation process. Device activation relies on a valid TLS certification managed by Afterpay Touch (APT) host. The device can then be activated using the APT Health Device Activation API.

Authentication

To authorize, use this code:

# With shell, you can just pass the correct header with each request
curl "https://{{Environment}}/v1/" \
  -H "Authorization: Bearer <accessToken>"

Make sure to replace accessToken with a valid access token.

Afterpay Touch Health Claiming API uses access tokens to allow access to the API. Access tokens are created using the create token endpoint.

Afterpay Touch Health Claiming API expects the access token to be included in all API requests as a HTTP header such as the following:

Authorization: Bearer <accessToken>

PMS Operator Identification

To authorize, use this code:

# With shell, you can just pass the correct header with each request
curl "https://{{Environment}}/v1/" \
  -H "Operator: operator-id"

Make sure to replace operator-id with the operator’s ID.

With the exception of the device activation and create token endpoints, Afterpay expects for the Operator ID to be included in all healthclaims.touchcorp.com API requests to the server in a header that looks like the following:

Operator: operator-id

Timeouts

Afterpay Touch Health Platform will attempt to respond to requests as soon as possible, but often latency delays are outside of our control. Where an API call is dependant on downstream banking networks the response times can be higher. As a guideline this document provides recommended network connection open timeout and read timeout values for each API resource. Resources that are dependant on banking networks will have higher timeout values.

Models

Transaction Object

Example Transaction Object

{
  "requestId": "50dce43a-fb4c-4f75-847c-55858b87208f",
  "requestedAt": "2015-07-14T10:08:14.123Z",
  "touchId": "1000094574",
  "completedAt": "2016-06-29T07:27:48.000+10:00",
  "txnResponseCode": "00",
  "txnResponseText": "APPROVED",
  "finalMessage": "false",
  "originalRequestId": "50dce43a-fb4c-4f75-847c-55858b87208f",
  "originalTouchId": "1000094574"
}

Parameter	Type	Description
requestId	string	Transaction request identifier from the device or Practice Management System for claims. It is recommended that the client generate a GUID as no mechanism is provided to synchronise a incrementing id should the sequence repeat
requestedAt	string (ISO-8601)	A timestamp of the device claim request time (ISO 8601 UTC/Zulu time)
completedAt	string (ISO-8601)	A timestamp of the transaction completed date and time
touchId		Afterpay Touch allocated transaction id
txnResponseCode		Overall transaction response code
txnResponseText		Overall transaction response code description
finalMessage	boolean	Response message indicator. `Present if eventInfo object is used`
originalRequestId	string	Used for retrieving status or perform a refund of a previously performed payment or claim transaction
originalTouchId	string	Used for retrieving status or perform a refund of a previously performed payment or claim transaction

Claimant Object

Example Claimant Object

  {
    "memberNumber": "",
    "healthFundId": "PHF00999",
    "track2Data": "9036009900001230001=2506????????????????"
  }

Parameter	Type	Description
healthFundId		Private health fund id
memberNumber		Private health fund membership number
track2Data		Private health fund card's track 2 data

Patient Object

Example Patient Object

  {
    "individualReferenceNumber": "01"
  }

Parameter	Type	Description
individualReferenceNumber		Patient id as on the card

HealthFund Object

Example HealthFund Object

{
  "id": "PHF00999",
  "name": "Test Fund",
  "prefix": "0001",
  "shortname": "Test"
}

Parameter	Type	Description
id		Health fund identification
name		Health fund name
prefix		Health fund card identifier
shortname		Readable name of Health fund

Providers Object

Example Patient Object

{
     "providerNumber": "947245AF",
     "providerName": "MR KERMIT FROG"
}

Parameter	Type	Description
providerNumber		The provider's id attending the patient
providerName		The provider's name attending the patient

Service Object

Example Service Object

{
  "serviceReference": "2",
  "chargeAmount": 85.00,
  "patient": 
  { 
    "individualReferenceNumber": "01" 
  },
  "serviceCode": "505",
  "serviceDate": "2016-05-27T09:14:49.1771373+10:00",
  "rebateAmount": 0.0,
  "responseCode": ""
}

Parameter	Type	Description
rebateAmount		Claim item benefit amount
chargeAmount		Claim item amount
patient	patient	Represents the recipient of medical services
responseCode		Claim Item response code
serviceCode		Claim item service code
serviceDate		Claim item date
serviceReference		Body part or Tooth Number

Service Items Object

Example Service Items Object

{
    "itemName": "COMPREHE ORAL EXAM",
    "itemNumber": "11",
    "fee": 0
}

Parameter	Type	Description
itemName		Name of the Service Item
itemNumber		Code assigned to Service Item by Healthfunds
fee		fees associated to the Service Item

Service Types Object

Example

 {
            "serviceTypeName": "GENERAL DENTIST",
            "serviceTypeCode": "D",
            "providers": [
                {
                    "providerNumber": "947245AF",
                    "providerName": "MR KERMIT FROG"
                }
            ],
            "serviceItems": [
                {
                    "itemName": "COMPREHE ORAL EXAM",
                    "itemNumber": "11",
                    "fee": 0
                }
            ]
        }

Parameter	Type	Description
serviceTypeName
serviceTypeCode
providers	providers
serviceItems	serviceItems

Service Status

Ping

Example Ping Request

curl "https://{{Environment}}/ping"

Response (200)

This endpoint can be used to check that the service is reachable and available.

HTTP Request

Get /ping

Device Authentication

Device Activation

Example Device Activation Request

curl "https://{{Environment}}/v1.1/devices/activate" \
  -X POST \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'User-Agent: Merchant/ XYZ; PMS/PMS Name1; PMS Version/ 1.5; MerchantId/347643; Reception/123' \
  -d '{
        "secret":"xyzabc",
        "name": "PMS1234",
        "attributes": "pmsVendor=ABC, pmsProduct=TestHarness"
      }'

Returns response headers like so:

HTTP/1.1 201 Created
Content-Type: application/json
Date: Mon, 11 Dec 2017 15:17:53 GMT
Connection: keep-alive

The above command returns JSON structured like so Response (201):

{
    "deviceId":"1234",
    "deviceKey":"bb68452ad2d743db75a270bf2c305df9abeefcb3e02084fc1ff7a3ba61ed46d5"
}

Response (401)

{
    "id": "yrv5fu2gqwifdr2m6qfurctsna",
    "message": "Device secret not found",
    "httpStatus": 401,
    "type": "Unauthorized"
}

This endpoint performs a one time activation of a device, providing a device’s identification and authorization credentials. The device credentials obtained from the activation request should be securely stored on the device/PMS system. The device credentials are required to create access tokens used for authentication.

HTTP Request

POST /v1.1/devices/activate

HTTP Headers

Parameter	Description
Content-Type	application/json
Accept	application/json
User-Agent	Merchant/`{merchantname}`; PMS/`{pmsnameame}`; PMS Version/`{pmsversionumber}`; MerchantId/`{pmsmerchantId}`; Reception/`{pmsreceptionId}`

Arguments

Parameter	Type	Description
secret	`required` string	The device secret provided for activation.
name	`recommended` string	An identifier for the device being activated.
attributes	`optional`	A free text field that can be populated with device or PMS Vendor specific information. Suggest a comma separated list of key/value pairs.

Response

Returns the devices authorization credentials

Parameter	Description
deviceId	A device ID require for auditing and authentication.
deviceKey	A secret key required for authentication.

Errors

Can return the following specific error responses

Status Code	Type	Description
401	unauthorized	Will be returned if the secret is not found or is invalid for the device.
412	precondition failed	Will be returned if the secret length does not meet the valid parameter i.e. between 10 and 32.

Connection timeouts

Timeout	Time (seconds)
Open	10
Read	20

Create Token

Example Create Token Request

curl "https://{{Environment}}/v1/devices/token" \
  -X POST \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'User-Agent: Merchant/ XYZ; PMS/PMS Name1; PMS Version/ 1.5; MerchantId/347643; Reception/123; Device/100' \
  -d '{ 
        "deviceId":"hj65f52a",
        "deviceKey":"bb68452ad2d743db75a270bf2c305df9abeefcb3e02084fc1ff7a3ba61ed46d5"
      }'

Returns response headers like so:

HTTP/1.1 200 Created
Content-Type: application/json
Date: Mon, 11 Dec 2017 14 15:17:53 GMT
Connection: keep-alive

The above command returns JSON structured like so:

{
     "accessToken":"86bc8b2b973d5046d82432862254dfb5967a6db7c844bf615ab8eba17082105b",
     "expiresInSecs":14400
}

This endpoint creates a device access token. The device will need to periodically renew the access token, indicated by expiresInSecs, required by all API endpoints.

HTTP Request

POST /v1/devices/token

HTTP Headers

Parameter	Description
Content-Type	application/json
Accept	application/json
User-Agent	Merchant/`{merchantname}`; PMS/`{pmsnameame}`; PMS Version/`{pmsversionumber}`; MerchantId/`{pmsmerchantId}`; Reception/`{pmsreceptionId}`; Device/`{deviceId}`

Arguments

Parameter	Description
deviceId	The device ID obtained during activation
deviceKey	The device secret key obtained during activation

Response

Returns the devices access token

Parameter	Description
accessToken	An access token.
expiresInSecs	The access token's expiry time in second.

Errors

Can return the following specific error responses

Status Code	Type	Description
401	unauthorized	Will be returned if the deviceId and/or deviceKey are invalid

Connection timeouts

Timeout	Time (seconds)
Open	10
Read	20

Access Token Validation Ping

Example API key validation via HEAD request

curl "https://{{Environment}}/v1/ping" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'User-Agent: Merchant/ XYZ; PMS/PMS Name1; PMS Version/ 1.5; MerchantId/347643; Reception/123; Device/100' \    
  -H "Authorization: Bearer <accessToken>" \

If the key is VALID, you will receive a HTTP 200 response

HTTP/1.1 200 OK
Content-Type: application/json
Date: Mon, 11 Dec 2017 15:17:53 GMT
Connection: keep-alive

If the key is INVALID, you will receive a HTTP 401 response

HTTP/1.1 401 Unauthorized
Cache-Control: must-revalidate,no-cache,no-store
Content-length: 1327
Content-Type: text/html;charset=ISO-8859-1
Date: Mon, 11 Dec 2017 15:15:11 GMT
Connection: keep-alive

If you wish to validate your access token, you can make an authenticated HEAD request to the /v1/ping endpoint.

HTTP Request

Get /v1/ping

HTTP Headers

Parameter	Description
Content-Type	application/json
Accept	application/json
Authorization	Bearer
User-Agent	Merchant/`{merchantname}`; PMS/`{pmsnameame}`; PMS Version/`{pmsversionumber}`; MerchantId/`{pmsmerchantId}`; Reception/`{pmsreceptionId}`; Device/`{deviceId}`

Response

Returns the key valid response (200)

Errors

Can return the following specific error responses

Status Code	Type	Description
401	unauthorized	Will be returned if the secret is not found or is invalid

Connection timeouts

Timeout	Time (seconds)
Open	10
Read	20

Transactions

Set up Private Health

Example Set up Private Health Service

curl "https://{{Environment}}/v1/devices/private/setup" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-H "Authorization: Bearer {accessToken}" \
-H 'Operator: Dante Hicks' \
-H 'User-Agent: Merchant/ XYZ; PMS/PMS Name1; PMS Version/ 1.5; MerchantId/347643; Reception/123; Device/100' \
-X POST \
-d '{
      "optNumber": "OPT85702"
     }'

Returns response headers like so:

HTTP/1.1 200 Created
Content-Type: application/json
Date: Thu, 24 Apr 2014 15:17:53 GMT
Connection: keep-alive

The above command returns JSON structured like so:

{
    "healthFunds": [
        {
            "id": "PHF00999",
            "prefix": "0099",
            "shortname": "ISOFT FUND",
            "name": "iSOFT Test Fund"
        },
        {
            "id": "PHF00550",
            "prefix": "0041",
            "shortname": "AHM",
            "name": "AHM"
        },
        {
            "id": "PHF00010",
            "prefix": "0012",
            "shortname": "ACA",
            "name": "ACA Health"
        },
        {
            "id": "PHF00470",
            "prefix": "0140",
            "shortname": "EMERGENCY SERVICES HEALTH",
            "name": "ESH"
        }
    ],
    "serviceTypes": [
        {
            "serviceTypeName": "GENERAL DENTIST",
            "serviceTypeCode": "D",
            "providers": [
                {
                    "providerNumber": "947245AF",
                    "providerName": "MR KERMIT FROG"
                }
            ],
            "serviceItems": [
                {
                    "itemName": "COMPREHE ORAL EXAM",
                    "itemNumber": "11",
                    "fee": 0
                },
                {
                    "itemName": "PERIODIC ORAL EXAM",
                    "itemNumber": "12",
                    "fee": 0
                },               
                {
                    "itemName": "LIMIT BOOST",
                    "itemNumber": "992",
                    "fee": 0
                },
                {
                    "itemName": "GST",
                    "itemNumber": "999",
                    "fee": 0
                }
            ]
        },
        {
            "serviceTypeName": "MYOTHERAPIST",
            "serviceTypeCode": "2",
            "providers": [
                {
                    "providerNumber": "957245AW",
                    "providerName": "MR PERCY PIG"
                }
            ],
            "serviceItems": [
                {
                    "itemName": "INIT CONS-60MIN",
                    "itemNumber": "105",
                    "fee": 0
                },
                {
                    "itemName": "STD CONS-30MIN",
                    "itemNumber": "205",
                    "fee": 0
                }
            ]
        }
    ],
    "nextReferenceNumber": "0000295",
    "optNumber": "ITT00007",
    "transaction": {
        "touchId": "1000261774",
        "completedAt": "2018-02-19T20:04:09.000+11:00"
    }
}

This endpoint set up the Private Health service.

HTTP Request

POST /v1/devices/private/setup

HTTP Headers

Parameter	Requirement	Description
Authorization	`required`	The Bearer token returned from /v1/devices/token. See Authentication
Content-Type	`required`	`application/json`
User-Agent	`recommended`	Merchant/`{merchantname}`; PMS/`{pmsnameame}`; PMS Version/`{pmsversionumber}`; MerchantId/`{pmsmerchantId}`; Reception/`{pmsreceptionId}`; Device/`{deviceId}`
Accept	`recommended`	`application/json` or `/`
Operator	`required`	The PMS, terminal, user or operator identifier. See PMS Operator Identification

Arguments

Parameter	Type	Description
optNumber		Private Health ID issued by DXC for each device also known as "Private Claiming ID"

Response

Returns service activation and private health data associated with the device. This includes:

Supported Health Funds
Practitioners
Service Items

Parameter	Type	Description
healthFunds	healthFund	A collection of Health Fund objects, representing the individual supported fund
serviceTypes	serviceTypes	A collection of Service objects, representing the individual service being claimed
nextReferenceNumber		Unique sequential number tat can be used by device to process claim request in sequential order
optNumber		Private Health ID issued by DXC for each device also known as "Private Claiming ID"
transaction	transaction	General details related to the transaction

Errors

Can return the following specific error responses

Status Code	Type	Description
401	unauthorized	Will be returned if the access token is not found or is invalid or expired

Rebate Estimate

Example Process Rebate Estimate Request

curl "https://{{Environment}}/v1/private/rebateestimates" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-H "Authorization: Bearer {accessToken}" \
-H 'Operator: Dante Hicks' \
-H 'User-Agent: Merchant/ XYZ; PMS/PMS Name1; PMS Version/ 1.5; MerchantId/347643; Reception/123; Device/100' \
-X POST \
-d '{
      "referenceNumber": "1149",
      "claimant": {
        "cardNumber": "9036009900001230001",
        "memberNumber": "",
        "healthFundId": "PHF00999",
        "track2Data": "9036009900001230001=2506????????????????"
      },
      "serviceProvider": {
        "providerNumber": "4574112T"
      },
      "serviceTypeCode": "M",
      "services": [
        {
          "serviceReference": "2",
          "chargeAmount": 85.00,
          "patient": {
            "individualReferenceNumber": "1"
          },
          "serviceCode": "505",
          "serviceDate": "2016-05-27T09:14:49.1771373+10:00",
        }
      ],
      "transaction": {
          "requestId": "00056748"
      }
    }'

Returns response headers like so:

HTTP/1.1 200 Created
Content-Type: application/json
Date: Thu, 24 Apr 2014 15:17:53 GMT
Connection: keep-alive

The above command returns JSON structured like so:

{
  "referenceNumber": "423",
  "settlementDate": "2016-05-04T17:23:56.9214169+10:00",
  "totalChargeAmount": 252.0,
  "totalGapAmount": 206.0,
  "totalRebateAmount": 46.0,
  "claimant": {
    "cardNumber": "9036009900001230001",
    "memberNumber": "01230001",
    "healthFundId": "PHF00099",
    "track2Data": "9036009900001230001=2506????????????????"
  },
  "serviceProvider": {
    "providerNumber": "2407381F"
  },
  "serviceTypeCode": "M",
  "services": [
    {
      "serviceReference": "27",
      "chargeAmount": 141.0,
      "patient": {
        "individualReferenceNumber": "7"
      },
      "serviceCode": "57521",
      "serviceDate": "2016-05-03T17:23:52.342+10:00",
      "rebateAmount": 28.0,
      "responseCode": "0"
    },
    {
      "serviceReference": "884",
      "chargeAmount": 111.0,
      "patient": {
        "individualReferenceNumber": "3"
      },
      "serviceCode": "11506",
      "serviceDate": "2016-05-03T17:23:52.342+10:00",
      "rebateAmount": 18.0,
      "responseCode": "0"
    }
  ],
  "updateAvailable": false,
  "transaction": {
    "requestId": "00056748",
    "completedAt": "2016-05-03T17:23:56.921+10:00",
    "touchId": "864100412004",
    "txnResponseCode": "00",
    "txnResponseText": "APPROVED"
  }
}

This endpoint will process medical insurance rebate estimates (quotes).

HTTP Request

POST https://{{Environment}}/v1/private/rebateestimates

HTTP Header

Parameter	Description
accessToken	The access token.

Body

Parameter	type	Description
claimant	claimant	Represents the health fund account.
referenceNumber		Unique sequential number for the device claims.
services	services	A collection of Service objects, representing the individual service being claimed.
serviceProvider	provider	Represents a medical practitioner who provided the services being claimed.
serviceTypeCode		Category of service.
transaction	transaction	General details related to the transaction.

Response

Returns the processed claim

Parameter	type	Description
claimant	claimant	Represents the health fund account.
referenceNumber		Unique sequential number for the device claims.
services	service	A collection of Service objects, representing the individual service being claimed.
serviceProvider	provider	Represents a medical practitioner who provided the services being claimed.
serviceTypeCode		Category of service.
settlementDate		Settlement date as determined by the system.
totalRebateAmount		Private health fund total benefit amount for all services.
totalChargeAmount		Private health fund total charge amount for all services.
totalGapAmount		Private health fund total gap amount for all services.
updateAvailable		Refers to availability of updates for download (health funds only).
transaction	transaction	General details related to the transaction.

Errors

Can return the following specific error responses

Status Code	Type	Description
401	unauthorized	Will be returned if the access token is not found or is invalid or expired
409	conflict	Another request with this request id has already been processed

Process Claim

Example Process Claim Request

curl "https://{{Environment}}/v1/private/claims" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-H "Authorization: Bearer {accessToken}" \
-H 'Operator: Dante Hicks' \
-H 'User-Agent: Merchant/ XYZ; PMS/PMS Name1; PMS Version/ 1.5; MerchantId/347643; Reception/123; Device/100' \
-X POST \
-d '{
      "claimant": {
        "cardNumber": "9036009900001230001",
        "memberNumber": "",
        "healthFundId": "PHF00999",
        "track2Data": "9036009900001230001=2506????????????????"
      },
      "serviceProvider": {
        "providerNumber": "4574112T"
      },
      "serviceTypeCode": "M",
      "services": [
        {
          "serviceReference": "2",
          "chargeAmount": 85.00,
          "patient": {
            "individualReferenceNumber": "1"
          },
          "serviceCode": "505",
          "serviceDate": "2016-05-27T09:14:49.1771373+10:00"
        }
      ],
      "referenceNumber": "1149",
      "transaction": {
        "requestId": "50dce43a-fb4c-4f75-847c-55858b87208f",
        "requestedAt": "2018-01-29T14:09:32.000+11:00"
      }
    }'

Returns response headers like so:

HTTP/1.1 200 Created
Content-Type: application/json
Date: Thu, 24 Apr 2014 15:17:53 GMT
Connection: keep-alive

The above command returns JSON structured like so:

{
  "referenceNumber": "423",
  "settlementDate": "2016-05-04T17:23:56.9214169+10:00",
  "totalChargeAmount": 252.0,
  "totalGapAmount": 206.0,
  "totalRebateAmount": 46.0,
  "claimant": {
    "cardNumber": "9036009900001230001",
    "memberNumber": "01230001",
    "healthFundId": "PHF00099",
    "track2Data": "9036009900001230001=2506????????????????"
  },
  "serviceProvider": {
    "providerNumber": "2407381F"
  },
  "serviceTypeCode": "M",
  "services": [
    {
      "serviceReference": "27",
      "chargeAmount": 141.0,
      "patient": {
        "individualReferenceNumber": "7"
      },
      "serviceCode": "57521",
      "serviceDate": "2016-05-03T17:23:52.342+10:00",
      "rebateAmount": 28.0,
      "responseCode": "0"
    },
    {
      "serviceReference": "884",
      "chargeAmount": 111.0,
      "patient": {
        "individualReferenceNumber": "3"
      },
      "serviceCode": "11506",
      "serviceDate": "2016-05-03T17:23:52.342+10:00",
      "rebateAmount": 18.0,
      "responseCode": "0"
    }
  ],
  "updateAvailable": false,
  "transaction": {
    "requestId": "00056748",
    "completedAt": "2016-05-03T17:23:56.921+10:00",
    "touchId": "864100412004",
    "txnResponseCode": "00",
    "txnResponseText": "APPROVED"
  }
}

This endpoint will process medical insurance claims (extra covers).

HTTP Request

POST /v1/private/claims

HTTP Headers

Parameter	Requirement	Description
Authorization	`required`	The Bearer token returned from /v1/devices/token. See Authentication
Content-Type	`required`	`application/json`
User-Agent	`recommended`	Merchant/`{merchantname}`; PMS/`{pmsnameame}`; PMS Version/`{pmsversionumber}`; MerchantId/`{pmsmerchantId}`; Reception/`{pmsreceptionId}`; Device/`{deviceId}`
Accept	`recommended`	`application/json` or `/`
Operator	`required`	The PMS, terminal, user or operator identifier. See PMS Operator Identification

Arguments

Parameter	Type	Description
claimant	claimant	Represents the claimant health fund account
referenceNumber		Unique sequential number for the device claims. This is typically is in sequential order based on nextReferenceNumber received by the devices as part of Private Health Set Up Request. It is unique at the device level only
services	services	A collection of Service objects, representing the individual service being claimed
serviceProvider	provider	Represents a medical practitioner who provided the services being claimed
serviceTypeCode		Category of service
transaction	transaction	General details related to the transaction

Response

Returns the processed claim

Parameter	Type	Description
claimant	claimant	Represents the claimant health fund account
referenceNumber		Unique sequential number for the device claims. This is typically is in sequential order based on nextReferenceNumber received by the devices as part of Private Health Set Up Request. It is unique at the device level only
services	service	A collection of Service objects, representing the individual service being claimed
serviceProvider	provider	Represents a medical practitioner who provided the services being claimed
serviceTypeCode		Category of service.
settlementDate		Settlement date as determined by the system
totalRebateAmount		Private health fund total benefit amount for all services
totalChargeAmount		Private health fund total charge amount for all services
totalGapAmount		Private health fund total gap amount for all services
updateAvailable	boolean	Refers to availability of updates for download (health funds only)
transaction	transaction	General details related to the transaction

Errors

Can return the following specific error responses

Status Code	Type	Description
401	unauthorized	Will be returned if the access token is not found or is invalid or expired
409	conflict	Another request with this request id has already been processed

Retrieve Claim

Example Request returns a single claim:

curl "https://{{Environment}}/v1/private/claims/435678" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-H "Authorization: Bearer {accessToken}" \
-H 'Operator: Dante Hicks' \
-H 'User-Agent: Merchant/ XYZ; PMS/PMS Name1; PMS Version/ 1.5; MerchantId/347643; Reception/123; Device/100' \
-X GET \

Returns response headers like so:

HTTP/1.1 201 Created
Content-Type: application/json
Date: Thu, 24 Apr 2014 15:17:53 GMT
Connection: keep-alive

The above command returns JSON structured like so:

{
  "status": "SUCCESS",
  "totalRebateAmount": 65.0,
  "totalChargeAmount": 65.0,
  "claimant": {
    "track2Data": "9036009900001230001=2506????????????????"
  },
  "referenceNumber": "0003000",
  "transaction": {
    "touchId": "1000095149",
    "completedAt": "2016-05-31T11:12:58.000+10:00"
  }
}

This endpoint retrieves a specific claim.

HTTP Request

GET /v1/private/claims/{CLAIM_ID}

HTTP Headers

Parameter	Requirement	Description
Authorization	`required`	The Bearer token returned from /v1/devices/token. See Authentication
Content-Type	`required`	`application/json`
User-Agent	`recommended`	Merchant/`{merchantname}`; PMS/`{pmsnameame}`; PMS Version/`{pmsversionumber}`; MerchantId/`{pmsmerchantId}`; Reception/`{pmsreceptionId}`; Device/`{deviceId}`
Accept	`recommended`	`application/json` or `/`
Operator	`required`	The PMS, terminal, user or operator identifier. See PMS Operator Identification

PATH Parameters

Parameter	Type	Description
CLAIM_ID		The identification of the claim to retrieve.

Response

Returns the claim transaction.

Parameter	Type	Description
status		Represents the status of a processed claim
totalRebateAmount		Private health fund total benefit amount for all services
totalChargeAmount		Private health fund total charge amount for all services
claimant	claimant	Represents the claimant health fund account
referenceNumber		Unique sequential number for the device claims
transaction	transaction	General details related to the transaction

Errors

Can return the following specific error responses

Status Code	Type	Description
401	unauthorized	Will be returned if the access token is not found or is invalid or expired

Cancel Claim

Example Request to Cancel a claim

curl "https://{{Environment}}/v1/private/claims/435678976/cancel" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-H "Authorization: Bearer {accessToken}" \
-H 'Operator: Dante Hicks' \
-H 'User-Agent: Merchant/ XYZ; PMS/PMS Name1; PMS Version/ 1.5; MerchantId/347643; Reception/123; Device/100' \
-X POST \
-d '{
      "claimant": {
        "track2Data": "9036009900001230001=2506????????????????"
      },
      "transaction": {
        "requestId": "50dce43a-fb4c-4f75-847c-55858b87208f",
        "requestedAt": "2018-01-29T14:09:32.000+11:00"
      }
    }'

Returns response headers like so:

HTTP/1.1 201 Created
Content-Type: application/json
Date: Thu, 24 Apr 2014 15:17:53 GMT
Connection: keep-alive

The above command returns JSON structured like so:

{
  "totalRebateAmount": 65.0,
  "totalChargeAmount": 65.0,
  "claimant": {
    "cardNumber": "0000000000",
    "healthFundId": "iSOFT Test Fund"
  },
  "serviceProvider": {
    "providerNumber": "4574112T"
  },
  "services": [
    {
      "chargeAmount": 65.0,
      "serviceCode": "0505",
      "serviceDate": "2016-05-31T00:00:00.000+10:00",
      "rebateAmount": 65.0,
      "responseCode": "00"
    }
  ],
  "referenceNumber": "3000",
  "transaction": {
    "touchId": "1000095149",
    "completedAt": "2016-05-31T11:13:12.000+10:00",
    "txnResponseCode": "00",
    "txnResponseText": "APPROVED"
  },
  "updateAvailable": false
}

This endpoint cancels a specific claim.

HTTP Request

POST /v1/private/claims/{CLAIM_ID}/cancel

HTTP Headers

Parameter	Requirement	Description
Authorization	`required`	The Bearer token returned from /v1/devices/token. See Authentication
Content-Type	`required`	`application/json`
User-Agent	`recommended`	Merchant/`{merchantname}`; PMS/`{pmsnameame}`; PMS Version/`{pmsversionumber}`; MerchantId/`{pmsmerchantId}`; Reception/`{pmsreceptionId}`; Device/`{deviceId}`
Accept	`recommended`	`application/json` or `/`
Operator	`required`	The PMS, terminal, user or operator identifier. See PMS Operator Identification

PATH Parameters

Parameter	Type	Description
CLAIM_ID		The identification of the claim to retrieve. It's ‘referenceNumber’ of the original claim transaction.

Arguments

Parameter	Type	Description
claimant	`required` claimant	Represents the claimant health fund account
transaction	`required` transaction	General details related to the transaction

Response

Returns the updated claim.

Parameter	Type	Description
totalRebateAmount		Private health fund total benefit amount for all services
totalChargeAmount		Private health fund total charge amount for all services
claimant	claimant	Represents the claimant health fund account
serviceProvider	provider	Represents a medical practitioner who provided the services being claimed
services	service	A collection of Service objects, representing the individual service being claimed
referenceNumber		Unique sequential number for the device claims
transaction	transaction	General details related to the transaction
updateAvailable	boolean	Refers to availability of updates for download (health funds only)

Errors

Can return the following specific error responses

Status Code	Type	Description
401	unauthorized	Will be returned if the access token is not found or is invalid or expired

Void Claim

Example Request to Void an approved claim

curl "https://{{Environment}}/v1/private/claims/435678976/voids" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-H "Authorization: Bearer {accessToken}" \
-H 'Operator: Dante Hicks' \
-H 'User-Agent: Merchant/ XYZ; PMS/PMS Name1; PMS Version/ 1.5; MerchantId/347643; Reception/123; Device/100' \
-X POST \
-d '{
      "transaction": {
        "originalTouchId": "864100412004",
        "requestId": "50dce43a-fb4c-4f75-847c-55858b87208f",
        "requestedAt": "2018-01-29T14:09:32.000+11:00"
      }
    }'

Returns response headers like so:

HTTP/1.1 201 Created
Content-Type: application/json
Date: Thu, 24 Apr 2014 15:17:53 GMT
Connection: keep-alive

The above command returns JSON structured like so:

{
  "totalRebateAmount": 35.0,
  "totalChargeAmount": 35.0,
  "claimant": {
    "cardNumber": "0000000000",
    "healthFundId": "iSOFT Test Fund"
  },
  "serviceProvider": {
    "providerNumber": "4574112T"
  },
  "services": [
    {
      "chargeAmount": 35.0,
      "serviceCode": "0505",
      "serviceDate": "2016-05-31T00:00:00.000+10:00",
      "rebateAmount": 35.0,
      "responseCode": "00"
    }
  ],
  "referenceNumber": "3000",
  "transaction": {
    "touchId": "1000095150",
    "completedAt": "2016-05-31T11:15:12.000+10:00",
    "txnResponseCode": "00",
    "txnResponseText": "APPROVED"
  },
  "updateAvailable": false
}

This endpoint voids a specific claim.

HTTP Request

POST /v1/private/claims/{CLAIM_ID}/voids

HTTP Headers

Parameter	Requirement	Description
Authorization	`required`	The Bearer token returned from /v1/devices/token. See Authentication
Content-Type	`required`	`application/json`
User-Agent	`recommended`	Merchant/`{merchantname}`; PMS/`{pmsnameame}`; PMS Version/`{pmsversionumber}`; MerchantId/`{pmsmerchantId}`; Reception/`{pmsreceptionId}`; Device/`{deviceId}`
Accept	`recommended`	`application/json` or `/`
Operator	`required`	The PMS, terminal, user or operator identifier. See PMS Operator Identification

PATH Parameters

Parameter	Type	Description
CLAIM_ID		The identification of the claim to retrieve. It's ‘referenceNumber’ of the original claim transaction

Arguments

Parameter	Type	Description
transaction	transaction	General details related to the transaction

Response

Parameter	Type	Description
totalRebateAmount		Private health fund total benefit amount for all services
totalChargeAmount		Private health fund total charge amount for all services
claimant	claimant	Represents the claimant health fund account
serviceProvider	provider	Represents a medical practitioner who provided the services being claimed
services	service	A collection of Service objects, representing the individual service being claimed
referenceNumber		Unique sequential number for the device claims
transaction	transaction	General details related to the transaction
updateAvailable		Refers to availability of updates for download (health funds only)

Errors

Can return the following specific error responses

Status Code	Type	Description
401	unauthorized	Will be returned if the access token is not found or is invalid or expired

Private Health Config Data

Example Get Config

curl "https://{{Environment}}/v1/devices/private/updates" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-H "Authorization: Bearer {accessToken}" \
-H 'Operator: Dante Hicks' \
-H 'User-Agent: Merchant/ XYZ; PMS/PMS Name1; PMS Version/ 1.5; MerchantId/347643; Reception/123; Device/100' \
-X GET \

Returns response headers like so:

HTTP/1.1 200 OK
Content-Type: application/json
Date: Thu, 24 Apr 2014 15:17:53 GMT
Connection: keep-alive

The above command returns JSON structured like so:

{
    "healthFunds": [
        {
            "id": "PHF00999",
            "prefix": "0099",
            "shortname": "ISOFT FUND",
            "name": "iSOFT Test Fund"
        },
        {
            "id": "PHF00550",
            "prefix": "0041",
            "shortname": "AHM",
            "name": "AHM"
        },
        {
            "id": "PHF00010",
            "prefix": "0012",
            "shortname": "ACA",
            "name": "ACA Health"
        },
        {
            "id": "PHF00470",
            "prefix": "0140",
            "shortname": "EMERGENCY SERVICES HEALTH",
            "name": "ESH"
        }
    ],
    "serviceTypes": [
        {
            "serviceTypeName": "GENERAL DENTIST",
            "serviceTypeCode": "D",
            "providers": [
                {
                    "providerNumber": "947245AF",
                    "providerName": "MR KERMIT FROG"
                }
            ],
            "serviceItems": [
                {
                    "itemName": "COMPREHE ORAL EXAM",
                    "itemNumber": "11",
                    "fee": 0
                }
            ]
        },
        {
            "serviceTypeName": "MYOTHERAPIST",
            "serviceTypeCode": "2",
            "providers": [
                {
                    "providerNumber": "957245AW",
                    "providerName": "MR PERCY PIG"
                }
            ],
            "serviceItems": [
                {
                    "itemName": "INIT CONS-60MIN",
                    "itemNumber": "105",
                    "fee": 0
                }
            ]
        }
    ],
    "nextReferenceNumber": "0000295",
    "optNumber": "ITT00007",
    "transaction": {
        "touchId": "1000261774",
        "completedAt": "2018-02-19T20:04:09.000+11:00"
    }
}

This endpoint provides the device specific and global configuration for Private health funds data. The values provided in this configuration are related to the Service Item codes apporved for the provider that a practice can select for private health claims.

HTTP Request

GET /v1/devices/private/updates

HTTP Headers

Parameter	Requirement	Description
Authorization	`required`	The Bearer token returned from /v1/devices/token. See Authentication
Content-Type	`required`	`application/json`
User-Agent	`recommended`	Merchant/`{merchantname}`; PMS/`{pmsnameame}`; PMS Version/`{pmsversionumber}`; MerchantId/`{pmsmerchantId}`; Reception/`{pmsreceptionId}`; Device/`{deviceId}`
Accept	`recommended`	`application/json` or `/`
Operator	`required`	The PMS, terminal, user or operator identifier. See PMS Operator Identification

Response

Returns a set of undocumented configuration options

Parameter	type	Description
healthFunds	HealthFund	A collection of Health Fund objects, representing the individual supported fund.
serviceTypes	ServiceTypes	A collection of Service objects, representing the individual service being claimed.
transaction	Transaction	General details related to the transaction.

Errors

Can return the following specific error responses

Status Code	Type	Description
401	unauthorized	Will be returned if the access token is not found or is invalid or expired

Errors Management

Example Invalid Private Claim Request

curl "/v1.1/..." \
  -X POST \
  -H 'Authorization: Bearer 86bc8b2b973d5046d82432862254dfb5967a6db7c844bf615ab8eba17082105b' \
  -H 'Content-Type: application/json' \
  -H 'Operator: Dante Hicks' \
  -H 'User-Agent: Merchant/ XYZ; PMS/PMS Name1; PMS Version/ 1.5; MerchantId/347643; Reception/123; Device/100' \
  -H 'Accept: application/json' \
  -d '{
  }'

If the given parameters are incorrect, you will receive a HTTP 400 response

HTTP/1.1 400 Bad Request
Cache-Control: must-revalidate,no-cache,no-store
Content-length: 1327
Content-Type: text/html;charset=ISO-8859-1
Date: Thu, 24 Apr 2014 15:15:11 GMT
Connection: keep-alive

Returns a JSON response and appropriate HTTP status code

{
  "id": "cf5907fbf8fbc417",
  "code": " ",
  "message": " ",
  "httpStatus": 422,
  "type": "invalid_object",
}

The Afterpay Touch Private Health API uses conventional HTTP response codes to indicate success or failure of an API request.

In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that resulted from the provided information (e.g. a required parameter was missing), and codes in the 5xx range indicate an error with the Afterpay Touch Health Platform. Not all errors map cleanly onto HTTP response codes. Example, when a request is valid but does not complete successfully (e.g. a card is declined), we return a 402 error code. For certain claim error scenarios we do responde with http 2xx range, refer Claim Error Codes

Attributes	Description
id	A unique error ID.
code	Any specific transaction level error code responded by the terminal or healthfunds or medicare
message	A human-readable message giving more details about the error. For card errors, these messages can be shown to your users.
status	The HTTP status code.
type	The type of error returned. Can be invalid_request_error, transaction_error, or server_error.

HTTP Error Codes

Some examples of status codes that might be returned by the Afterpay Touch Health Private Health API are below. This list is not exhaustive, and other status codes may be encountered specific to the resource.

HTTP Status Code	HTTP Status Name	Meaning
400	Bad Request	Your request is a little wrong
401	Unauthorized	Your API key is wrong or access token is invalid.
402	Payment Required	Generally returned in cases where payments are declined.
404	Not Found	The specified resource could not be found
405	Method Not Allowed	You tried to access a resource with an invalid method
406	Not Acceptable	You requested a format that isn’t json
409	Conflict	You tried to perform an operation that conflicts with another operation.
410	Gone	The resource requested has been removed from our servers
412	Precondition Failed	A prerequisite step that was required before calling the resource had not been performed.
422	Unprocessable Entity	The request format was valid, however one or more values were incorrect.
423	Locked	The resource requested is in use at the moment. Try again later.
429	Too Many Requests	Too many requests may occur if an abnormal number of requests occur.
500	Internal Server Error	We had a problem with our server. Try again later.
503	Service Unavailable	We’re temporarily offline for maintenance. Please try again later.

Host Response Codes

Error Code	Meaning
1000	FATAL SYSTEM ERROR. PLEASE NOTIFY DXC HELP DESK
1001	INVALID DATA (X1)
1002	SYSTEM PROBLEM (X2). PLEASE TRY LATER
1003	INVALID DATA (X3)
1004	SYSTEM PROBLEM (X4)
1005	INVALID MESSAGE (X5)
1006	FUND UNAVAILABLE (A). PLEASE TRY LATER
1007	FUND CONNECTION LOST. PLEASE TRY AGAIN
1008	FUND UNAVAILABLE. PLEASE TRY LATER
1009	FUND NOT RESPONDING. PLEASE TRY AGAIN
1010	SYSTEM PROBLEM (D). PLEASE TRY AGAIN
1011	SYSTEM PROBLEM (B). PLEASE TRY LATER
1012	FUND UNAVAILABLE NOW. PLEASE CHECK SCHEDULE
1013	FUND IS BUSY. PLEASE TRY LATER
1014	INVALID MESSAGE (X14)
1017	NO CLAIM SUCCEEDED ON
1019	INVALID TERMINAL ID
1020	DO NOT TRY

HealthPoint Claim Error Codes

For scenarios where transaction has been rejected by the Healthfunds for a specific reason either at claim level or item level. Health Platform will respond with 2xx range http status code with a transaction level or claim level error code or description as advised by the Healthfunds.

Transaction Response Codes

The following is a list of all standard transaction response codes for a claim, void or cancellation.

Error Code	Meaning
01	Provider not approved by Fund
03	Invalid provider number
04	Retain Card
10	Refer claim to Fund
12	Transaction not approved
14	Card number not valid (no such number exists)
19	No Items have been entered
21	No Action has been taken by the system.
25	Unable to locate original transaction. (For Void or Cancellation only)
30	Format Error
32	Not all transaction has been completed
40	Patients Membership does not cover this service
42	Membership ceased/suspended at date of service
51	Membership has not been paid
54	Membership card has expired
56	Membership number not valid
57	Patient does not have ancillary cover
58	Transaction not permitted
60	Provider not recognised by Fund
61	Benefit limit exceeded
69	No benefit payable
76	Unable to process cancellation or void. Message not received on same day at original claim (For Void or Cancellation only)
91	System is busy at this point in time
92	System unavailable
93	System problem
94	Duplicate transmission

Item Response Codes

The following is a list of all standard item response codes. Item Response Codes are for individual line items within a Claim Response or Cancellation Response.

Error Code	Meaning
0000	Service Item is approved
0001	No benefit payable on this item
0002	No benefit payable - restricted item
0003	Reduced benefit - restricted item
0004	No benefit - benefit previously paid
0005	No benefit - Limit reached
0006	Reduced benefit - Limit reached
0007	No benefit - qualifying period applies
0008	No benefit - pre-requisite service required
0009	No benefit - preexisting ailment
0010	Item number invalid
0011	Item number no longer in use (at date of service)
0012	Item number is not valid for this provider
0013	Item number not approved, not payable
0014	Service exceeds number of times permitted
0015	Cost of service must be entered for this item
0016	Date of service must be equal to or earlier than today
0017	Date of service too old
0018	Body part required
0019	Patient not covered (at date of service)
0020	Dependent status ceased (at date of service)
0021	Invalid patient code
0022	Membership not covered (at date of service)
0023	Membership ceased/suspended (at date of service)
0024	Membership unfinancial (at date of service)
0025	No ancillary cover (at date of service)
0026	Not covered for this service (at date of service)
0027	No benefit - possible duplicate service
0028	No benefit - excess on service applied
0029	Reduced benefit - excess on service applied
0030	No benefit - quotation required prior to service
0031	Reduced benefit - quotation required prior to service
0032	No benefit - claim exceeds quotation
0033	Reduced benefit - claim exceeds quotation
0034	No benefit - Age restriction applies
0035	Reduced benefit - Age restriction applies
0036	No benefit - Gender restriction applies
0037	Reduced benefit - Gender restriction applies
0038	No benefit - invalid charge
0039	Notional charge
0040	Converted item
0041	Refer to Fund
0042	System problem
0050	Provider not approved by Fund (at date of service)
0051	Provider not approved by Fund for this service (at date of service)