Record transaction outcome
Virtual Terminal
Transaction states
For Virtual Terminal transctions, there is a simple whole of transaction state indicated by status. Status can be one of:
- Cancelled: transaction cancelled by provider or rejected by patient.
- Completed: transaction is completed, with payment approved.
- Pending: transaction created, awaiting approval by patient.
Response payload
When a transaction is processed, the SDK will pass through the transaction details to the first parameter of the onSuccess hook.
The response payload contains a number of attributes with a complete description of the transaction model in our online API documentation.
Key attributes include:
| Attribute | Notes |
|---|---|
_id | a unique transaction level identifier generated by Medipass |
status | overall transaction status |
payments[].amount | amount paid |
payments[].status | status of the payment |
payments[].gatewayDescription | payment network response, if failed/declined, reason fdescription |
Funder
Transaction and item level states
The following terminology is used for each Medipass transaction:
- Item code is a single item or service.
- Claim is the total set of item codes processed in one transaction. A complete claim could include a number of item codes if you have completed a more complex service for your patient.
- Patient funded payment is the gap or other payment made directly by a patient, usually by credit/debit card. This is only applicable for Medicare, HICAPS and Patient funded transactions.
- Transaction is a combined set of item codes that may include a combination of a claim and a patient payment.
Each of these components have their own statuses and error codes.
Medipass statuses and error codes include:
- Item code status can be one of:
- Pending: we are awaiting a response from the funder.
- Under Review: funder has advised that they have received the item code but it is under review.
- Approved: item code is approved.
- Rejected: item code is rejected. In this case we may offer further information that has been provided to us from Funder to help you determine how best to resubmit the claim in order for it to be approved.
- Claim status can be one of:
- Submitted: Medipass has submitted this claim to the funder.
- Accepted: funder Accepted (and therefore approved) the claim.
- Under Review: funder advised that they have received the claim but it is under review.
- Rejected: funder advised that the claim has been rejected. In this case we may offer further information that has been provided to us from the funder to help you determine how best to resubmit the claim for approval.
- Payment made: funder advised that payment has been sent to the nominated account.
- Patient funded payment status can be one of:
- Pending: the payment request has been sent to the patient and is awaiting their approval.
- Voided: the payment request was cancelled, either by the patient or by the provider.
- Approved: the payment request has been approved by the patient.
- Transaction status can be one of:
- Pending: the transaction is pending because a component (such as the patient payment) has not been finalised.
- Cancelled: a component of the transaction was cancelled.
- Under Review: a component of the transaction is under review
- Completed: payment has been made, though the funder claim may still be outstanding.
For Medicare claims, Medipass will show both the return code and the description as advised by Medicare. These are either:
- four digit return codes which are sent when errors happen. https://www.humanservices.gov.au/sites/default/files/2017/11/4-digit-reason-codes.csv
- three digit reason codes which provide information about how a claim was assessed: https://www.humanservices.gov.au/sites/default/files/2018/07/medicare-reason-codes.csv
A full list of all Medicare return codes is posted at: https://www.humanservices.gov.au/organisations/health-professionals/enablers/medicare-digital-claiming-return-codes/33171
Response payload
When a transaction is successful, the SDK will pass through the transaction details to the first parameter of the onSuccess hook.
The response payload will differ for each funder type, but the fundamental items that you need to check in the response remain similar. A complete description of the transaction model is provided in our online API documentation.
Key attributes include:
| Attribute | Notes |
|---|---|
_id | a unique transaction level identifier generated by Medipass |
status | overall transaction status, includes any claim and payment component |
amountClaimsBenefit | total benefit paid by funder |
amountBalance | any unpaid amount on aggregate charges |
claims[].status | overall claim status |
claims[].gatewayRefId | unique transaction reference from funder |
claims[].claimItems[].status | claim item status - some may be accepted and others declined |
claims[].claimItems[].amountBenefit | benefit paid on item by funder |
claims[].claimItems[].amountGap | gap on item (for HICAPS claims) |
claims[].claimItems[].clientMessage | message to display to user (usually for declined items) |
payments[].amount | amount paid by the payment method |
payments[].status | status of the payment |
externalReference | If the funder generates a unique transaction or approval number, those references will be available in the externalReferences model. These references are used for transaction inquiries with funders. |
links | For some funders, there are links that enable you to read-back the transaction or put through a cancellation for the transaction |