NAV Navbar
.curl

Public 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.5 | Last updated: Friday, 14 September, 2018

Strictly Confidential

The Afterpay Touch Public Health Claiming API can be used by a Practice Management Systems (PMS) to perform Medicare Easyclaim transactions.

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

Copyright © Afterpay Touch

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:

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:

Changes we approve and introduce:

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 Public 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 Public 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 Aftepay 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 transaction
originalTouchId string Used for retrieving status or perform a refund of a previously performed payment transaction

EventInfo Object

Example EventInfo Object

{
  "displayText": [
    "INITIALISING        ",
    "PLEASE WAIT         "
  ],
  "okKeyFlag": false,
  "cancelKeyFlag": false,
  "yesKeyFlag": false,
  "noKeyFlag": false,
  "authoriseKeyFlag": false,
  "receiptType": "Logon"
}
Parameter Type Description
displayText array An array of string to display (one line per index)
okKeyFlag boolean OK Key present
cancelKeyFlag boolean Cancel Key present
yesKeyFlag boolean Yes Key present
noKeyFlag boolean No Key present
authoriseKeyFlag boolean Authorise Key present
inputDataFieldKeyFlag string Present if “authoriseKeyFlag” = true

Values are:

“Normal” = normal ASCII entry
“Amount” = formatted amount entry ($0.cc)
“NoDollarAmount” = amount with no dollar sign
“Password” = masked password entry
“Supervisor” = supervisor request entry
“OneKey” = one key entry
receiptType string “Customer”
“Merchant”
“Settlement”
“Logon”
“Audit”
“Duplicate”
“Unknown”

Claimant Object

Example Claimant Object

  {
    "medicareCardNumber": "3950068361",
    "individualReferenceNumber": "4",
    "firstName": "",
    "lastName": ""
  }
Parameter Type Description
individualReferenceNumber Claimant ID as on the card
medicareCardNumber Medicare issued card number
firstName First name of the claimant
lastName Last name of the claimant

Patient Object

Example Patient Object

  {
    "medicareCardNumber": "3950068361",
    "individualReferenceNumber": "9",
    "cardSwiped": true,
    "firstName": "",
    "lastName": ""
  }
Parameter Type Description
medicareCardNumber Medicare issued card number
individualReferenceNumber Patient id as on the card
cardSwiped boolean
firstName First name of the Patient
lastName First name of the Patient

Provider Object

Example Provider Object

  {
    "providerNumber": "2367876J",
    "providerName": "Dr. Julius Hibbert"
  }
Parameter Type Description
providerNumber The provider's id attending the patient.
providerName The provider's name attending the patient.

Service Item Object

Example Service Item Object

{                                                       
    "mbsItemNumber": "23",                              
    "chargeAmount": "95.00",                            
    "serviceDate": "2018-06-20T00:00:00.000+11:00",     
    "serviceItemOverrideCode": "AP"                     
}
Parameter Type Description
scpIdentificationNumber string Specimen Collection Point Identification Number
equipmentIdentificationNumber string Equipment Identification Number
lspnNumber string Location Specific Practice Number
selfDeemedCode string SD = self deemed
SS = substituted service
serviceRestrictiveOverrideCode string NC = not for comparison
SP = separate sites
NR = not related
serviceDate string Date of service (ISO 8601 - UTC format)
mbsItemNumber string Medicare Benefits Schedule Item Number
chargeAmount number Service item charge amount
patientContribution number Patient contribution amount for the service item
serviceItemOverrideCode string AO = Not normal aftercare; AP = Not duplicate service
assessmentStatus string Assessment status of the service item
(response message)
explanationCode string Explanation of the service item
(response message)
explanationText string Explanation text of the service item
(response message)
serviceBenefitAmount number Benefit amount the claimant can or will receive for the service item
(response message)
scheduleFee number Scheduled fee for this service item
(response message)
benefitAssignedAmount number Benefit amount assigned to the service provider
(response message)

Requesting Provider Object

Example Requesting Provider Object

{                                                       
    "provider": {
      "providerNumber": "2367876J"
    },                              
    "issueDate": "2018-06-20T00:00:00.000+11:00",     
    "requestTypeCode": "P"                     
}
Parameter Type Description
provider provider Requesting provider information
issueDate string Date when the request was issued (ISO 8601 - UTC format)
requestTypeCode string D = Diagnostic
P = Pathology

Referring Provider Object

Example Referring Provider Object

{                                                       
    "provider": {
      "providerNumber": "2367876J"
    },                              
    "issueDate": "2018-06-20T00:00:00.000+11:00",     
    "referralPeriodCode": "S"                     
}
Parameter Type Description
provider provider Referring provider information
issueDate string Date when the referral was issued (ISO 8601 - UTC format)
referralPeriodCode string S = Standard
I = Indefinite

Voucher Object

Example Voucher Object

{
  "serviceTypeCode": "O",
  "requestOverrideCode": "N",
  "referralOverrideCode": "N",
  "referral": {
    "provider": {
      "providerNumber": "2367876J"
    },
    "issueDate": "2018-06-20T00:00:00.000+11:00",
    "referralPeriodCode": "S"
  },
  "request": {
    "provider": {
      "providerNumber": "2367876J"
    },
    "issueDate": "2018-06-20T00:00:00.000+11:00",
    "requestTypeCode": "P"
  }
}
Parameter Type Description
request requestingProvider Requesting provider for this service
requestOverrideCode string L = Lost
E = Emergency
N = Not required
referral referringProvider Referring provider for this service
referralOverrideCode string L = Lost
E = Emergency
N = Not required
serviceTypeCode string O = General Practice
S = Specialist
D = Diagnostic
P = Pathology

Public Claim Object

Example Public Claim Object

{
  "claimType": "Patient",
  "totalBenefitAmount": 83.45,
  "services": [
    {
      "serviceDate": "2018-06-19T23:00:00.000+10:00",
      "mbsItemNumber": "23",
      "chargeAmount": 95,
      "explanationCode": "517",
      "explanationText": "MSN THRESHOLD REACHED - 80% INCREASE FOR THIS ITEM",
      "serviceBenefitAmount": 83.45,
      "scheduleFee": 37.05,
      "serviceItemOverrideCode": "AP"
    }
  ],
  "medicareId": "00118062113104901045601M",
  "transaction": {
    "requestId": "50dce43a-fb4c-4f75-847c-55858b87208f",
    "requestedAt": "2015-07-14T10:08:14.123Z+10:00",
    "touchId": "1000335917",
    "finalMessage": true,
    "completedAt": "2018-06-21T13:10:50.000+10:00",
    "txnResponseCode": "00",
    "txnResponseText": "APPROVED"
  },
  "patient": {
    "medicareCardNumber": "2951021881",
    "individualReferenceNumber": "1",
    "cardSwiped": false,
    "firstName": "HARVEY",
    "lastName": "BARKER"
  },
  "serviceProvider": {
    "providerNumber": "2147561K",
    "providerName": "DR K AZIZI"
  },
  "voucher": {
    "serviceTypeCode": "O"
  },
  "totalChargeAmount": 95,
  "acceptanceType": "PAID",
  "accountPaidIndicator": true,
  "claimant": {
    "medicareCardNumber": "2951021881",
    "individualReferenceNumber": "1",
    "firstName": "HARVEY",
    "lastName": "BARKER"
  },
  "paymentTypeCode": "F"
}

This object is for claim response only.

Parameter Type Description
claimType string "Patient"
accountPaidIndicator boolean
paymentTypeCode string Defines whether the patient has paid for the services.
F = Fully paid
P = Partially paid
U = Unpaid
patient patient Patient information
claimant claimant Claimant information
services services List of service items
serviceProvider serviceProvider Service Provider details
voucher voucher Service information
transaction transaction General details related to the transaction

Rebate Object

Example Rebate Object

{
  "responseInfo": {
    "successFlag": true,
    "responseCode": "00",
    "responseText": "APPROVED            "
  },
  "pinPadInfo": {
    "merchant": "00",
    "terminalId": "00019007001",
    "stan": 6578
  },
  "transactionInfo": {
    "transactionType": "Refund",
    "accountType": "Savings ",
    "purchaseAmount": 83.45,
    "cashAmount": 0,
    "tipAmount": 0,
    "authorisationNumber": "525599",
    "referenceNumber": "20180621131049",
    "rrn": "000000000233",
    "dateTime": "2018-06-21T13:11:25",
    "settlementDate": "2106"
  },
  "cardDataInfo": {
    "cardType": "EFTPOS",
    "cardName": "05"
  }
}

This object is for Patient claim response only, confirming the rebate payment processing on the terminal. Refer to Pinpad Interface API for details on each of the fields in this object.

Parameter Type Description
responseInfo responseInfo
cardDataInfo cardDataInfo Available information about the Card Swiped.
transactionInfo transactionInfo
pinPadInfo pinPadInfo Available information about the PINpad.

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 https://{{Environment}}/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

Transactions

Process Patient Claim

curl "https://{{Environment}}/v1.1/public/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 '{                                                               
       "claimType": "Patient",                                     
       "accountPaidIndicator": true,                               
       "paymentTypeCode": "F",                                     
       "patient": {                                                
           "cardSwiped": false,                                    
           "medicareCardNumber": "2951021881",                     
           "individualReferenceNumber": "1"                        
       },                                                          
       "claimant": {                                               
           "medicareCardNumber": "2951021881",                     
           "individualReferenceNumber": "1"                        
       },                                                          
       "serviceProvider": {                                        
           "providerNumber": "2147561K"                            
       },                                                          
       "services": [                                               
           {                                                       
               "mbsItemNumber": "23",                              
               "chargeAmount": "95.00",                            
               "serviceDate": "2018-06-20T00:00:00.000+11:00",     
               "serviceItemOverrideCode": "AP"                     
           }                                                       
       ],                                                          
       "voucher": {                                                
           "serviceTypeCode": "O"                                  
       },                                                          
       "transaction": {                                            
           "requestId": "50dce43a-fb4c-4f75-847c-55858b87208f",
           "requestedAt": "2015-07-14T10:08:14.123Z+10:00"     
       }                                                           
   }'

Returns response headers like so:

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

The above command returns JSON structured with a Claim Assessment from Medicare like so:

{
    "transactionId": "1000335917",
    "eventInfo": {
        "displayText": ["TOTAL BENEFIT AMOUNT", "83.45", "", "SELECT PINPAD"],
        "okKeyFlag": true,
        "cancelKeyFlag": true
    },
    "pinPads": [{
        "terminalId": "00019007001",
        "versionNumber": "000842"
    }],
    "finalMessage": false
}

Follow on request to process rebate if the patient has accepted the assessment

curl "https://{{Environment}}/v1.1/public/claims/{transactionId}/pinpad?terminalId={terminalId}" \
-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 \

The above command returns JSON structured with complete claim response along with rebate processing results form the terminal:

{
    "transactionId": "1000335917",
    "publicClaim": {
        "claimType": "Patient",
        "totalBenefitAmount": 83.45,
        "services": [{
            "serviceDate": "2018-06-19T23:00:00.000+10:00",
            "mbsItemNumber": "23",
            "chargeAmount": 95.00,
            "explanationCode": "517",
            "explanationText": "MSN THRESHOLD REACHED - 80% INCREASE FOR THIS ITEM",
            "serviceBenefitAmount": 83.45,
            "scheduleFee": 37.05,
            "serviceItemOverrideCode": "AP"
        }],
        "medicareId": "00118062113104901045601M",
        "finalMessage": true,
        "transaction": {
            "requestId": "50dce43a-fb4c-4f75-847c-55858b87208f",
            "requestedAt": "2015-07-14T10:08:14.123Z+10:00",
            "touchId": "1000335917",
            "finalMessage": true,
            "completedAt": "2018-06-21T13:10:50.000+10:00",
            "txnResponseCode": "00",
            "txnResponseText": "APPROVED"
        },
        "patient": {
            "medicareCardNumber": "2951021881",
            "individualReferenceNumber": "1",
            "cardSwiped": false,
            "firstName": "HARVEY",
            "lastName": "BARKER"
        },
        "serviceProvider": {
            "providerNumber": "2147561K",
            "providerName": "DR K AZIZI"
        },
        "voucher": {
            "serviceTypeCode": "O"
        },
        "totalChargeAmount": 95.00,
        "acceptanceType": "PAID",
        "accountPaidIndicator": true,
        "claimant": {
            "medicareCardNumber": "2951021881",
            "individualReferenceNumber": "1",
            "firstName": "HARVEY",
            "lastName": "BARKER"
        },
        "paymentTypeCode": "F"
    },
    "rebate": {
        "responseInfo": {
            "successFlag": true,
            "responseCode": "00",
            "responseText": "APPROVED            "
        },
        "pinPadInfo": {
            "merchant": "00",
            "terminalId": "00019007001",
            "stan": 6578
        },
        "transactionInfo": {
            "transactionType": "Refund",
            "accountType": "Savings ",
            "purchaseAmount": 83.45,
            "cashAmount": 0.00,
            "tipAmount": 0.00,
            "authorisationNumber": "525599",
            "referenceNumber": "20180621131049",
            "rrn": "000000000233",
            "dateTime": "2018-06-21T13:11:25",
            "settlementDate": "2106"
        },
        "cardDataInfo": {
            "cardType": "EFTPOS",
            "cardName": "05"
        }
    }
}

This endpoint will process a Medicare Easyclaim Patient claims.

HTTP Request

POST /v1.1/public/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
claimType required string "Patient"
accountPaidIndicator required boolean
paymentTypeCode required string Defines whether the patient has paid for the services.
F = Fully paid
P = Partially paid
U = Unpaid
patient required patient Patient information
claimant required claimant Claimant information
services required services List of service items
serviceProvider required serviceProvider Service Provider details
voucher required voucher Service information
transaction required transaction General details related to the transaction

Claim Assessment Response

Returns the claim assessment from Medicare. This does not completes the transaction as a rebate must be processed via the terminal to complete the transaction if Patient have accepted the assessment.

Parameter type Description
transactionId string Transaction Id for this claim request.
eventInfo eventInfo
pinpads array List of PINpads i.e. ids of the terminals available in the practice.
finalMessage boolean Response message indicator.

Rebate Processing Arguments

HTTP Request

POST /v1.1/public/claims/{transactionId}/pinpad?terminalId={terminalId}

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

URL Parameters

Parameter Type Description
transactionId string Transaction Id provided in the claim assessment response.
terminalId Terminal ID selected by the user from the list provided in the claim assessment response.

Rebate Processing Response

Parameter Type Description
transactionId string Transaction Id for this claim.
publicClaim publicclaim Public claim response.
rebate rebate Rebate response from the PINpad.
finalMessage boolean Response message indicator.

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.

Events Handling

In some cases, platform will not send a response right away, but instead it will send EVENTS. This section describes different events and how to handle them.

If ‘eventInfo’ is present, PMS must adhere to following scenarios:

Display Event

{
    "eventInfo": {
        "displayText": ["INITIALISING        ", "PLEASE WAIT         "],
        "okKeyFlag": false,
        "cancelKeyFlag": false,
        "yesKeyFlag": false,
        "noKeyFlag": false,
        "authoriseKeyFlag": false
    }
}

This is determined by having “displayText” in “eventInfo”. it should display the text together which key or buttons are set to true.

Parameter Requirement Description
eventInfo eventInfo

Possible values of {keyPressType} are:

Example Print Event

{
    "eventInfo": {
        "receiptType": "Logon"
    }
}

This is determine by "receiptType" or "receiptData" in “eventInfo”. This will happen if the request specifies the "printerType" is "pos", see ReceiptPrintingInfo. Data to be printed is the "receiptData".

Parameter Requirement Description
eventInfo eventInfo

Keep doing this until it receives "responseInfo".

Errors Management

Example Invalid Payment 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 Public 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 Payment Support 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.

Claim Error Codes

For scenarios where transaction has been rejected by the Medicare 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 Medicare.

Medicare Easyclaim Return Codes

When a claim is lodge for Medicare benefits, Medicare use return codes to advise the claim was rejected or how the claim was assessed. This information can be:

Some examples of return codes that might be returned by Medicare for the rejected Medicare Easyclaims.

Medicare Return code Instructions
2015, 2025 A system error has occurred. Please resubmit or call the eBusiness Service Centre and quote the error number displayed on the EFTPOS terminal.
2016 Item number missing. Please resubmit with this information.
2017 The payee provider cannot be the same as the servicing provider. Please check details and resubmit.
2030 Two pieces of information submitted within the claim cannot be submitted together. Please check details and resubmit.
2032 Maximum reached. The maximum number of items that can be submitted in one claim is 14. Please create a separate claim if necessary.
2038 The referral/request information submitted is inconsistent with the item that is being claimed. Please check details and resubmit if appropriate.
2053 The patient contribution amount must be less than the total charge. Please check details and resubmit.
2055 The patient contribution amount should not be entered when the account is fully paid. Please check details and resubmit.
3000–3999 A system error has occurred. Please resubmit or call the eBusiness Service Centre and quote the error number displayed on the EFTPOS terminal.
9006 Check servicing provider details. May not be able to provide the service for this item at date of service. For more information call the eBusiness Service Centre.
9201 Invalid data entered. Please check details and resubmit.
9203 Date of service is too old to be submitted through Medicare Easyclaim. Please issue patient/claimant an account/account receipt to claim through an alternative Medicare claiming channel (eg. at a Medicare office).

Refer here for the detailed list of Medicare Easyclaim Return Codes

.curl