Handling the response | Transaction Callbacks

Handling the response of the integrated pre-auth functions in iClient involves the use of the transactionCompleteCallback and the responseReceivedCallback. The specification for these callbacks is given below.

Transaction Complete Callback | Open Pre-Authorisation Request

Function	Description	Required
transactionCompleteCallback	Invoked when the transaction has been completed on the terminal. Called with a subset of the following parameters as part of the transactionData object, as shown in the below table.	Required

Field	Type	Description	Usage Required
result	String	One of the following values: APPROVED, CANCELLED, REVERSED, DECLINED, SYSTEM ERROR, NOT STARTED, UNKNOWN. The merchant will only receive money if this value is APPROVED. UNKNOWN means the merchant should look at the terminal to determine what happened. Typically this would indicate a network error.	Required
cardType	String	The scheme displayed on the card (Visa, Mastercard, etc).	Optional
transactionReference	String	Also known as a STAN, this is Tyro's reference to this transaction. Quote this to Tyro Customer Support if you run into any issues with a transaction.	Optional
authorisationCode	String	The Scheme's reference to the transaction. Quote this number to Visa/Mastercard/etc if the issue is on their end.	Optional
issuerActionCode	String	The raw result code returned by the card issuer.	Optional
elidedPan.	String	The (elided) credit card number used for this transaction	Optional
rrn	String	The Retrieval Reference Number is a unique number generated by the Payment Service for a specific merchant. Guaranteed to be unique for a 7-day period.	Optional
preAuthCompletionReference	String	Tyro's reference to a PreAuth Completion.	Required
customerReceipt	String	Text representation of the Tyro receipt intended for the customer. Only included if integrated receipt printing is enabled. Formatted to be printed in a monospaced font.	Optional - Usage required if Integrated receipt printing has been developed as a feature.

Handling the response |Open Pre-authorisation Request

The response to the open pre-authorisation request is returned to the POS by iClient using the transactionCompleteCallback at the completion of the open pre-auth request. If the request is successful, the POS will be provided the result and the preAuthCompleteionReference field, along with other relevant fields. The POS must display the result for the user’s reference and store the preAuth completion reference in the sale invoice to allow the preAuth to be closed off or voided.

Response Example

Copy

Copied

{
  "result": "APPROVED",
  "transactionId": "e378fb4c327daa4474d86aea89c9aabfe7c2",
  "cardType": "Visa",
  "transactionReference": "298143",
  "authorisationCode": "695585",
  "issuerActionCode": "00",
  "elidedPan": "XXXXXXXXXXXXXX8641",
  "rrn": "2981431109",
  "preAuthCompletionReference": "431721",
  "baseAmount": "102.00",
  "transactionAmount": "102.00",
  "customerReceipt": " CUSTOMER COPY \n\n Merchant 8811 \n Address line 1 \n Address line 2 \n\n Tyro EFTPOS \n\nVisa\nCard: XXXXXXXXXXXXXX8641(s)\n\nPreAuth AUD $102.00\n\nAPPROVED 00\n\nA hold has been placed on\nyour account in the amount\nof $102.00. When the tab is\nclosed, up to $102.00 will\nbe debited from your\naccount.\n\nCompletion Ref: 431721\n\nTerminal ID: 123\nTransaction Ref: 298143\nAuthorisation No: 695585\n09 Nov 2021 at 08:59 PM\n"
}

Response Received Callback | Increment Pre-Auth Request

Function	Description	Usage Required
responseReceivedCallback	Invoked when the request has been completed on the terminal. Called with a single object containing the following fields, as shown in the below table.	Required

Field	Type	Description	Usage Required
result	String	The result of the request, will be either ‘success’ or ‘failure’.	Required
incrementalAmount	String	The value of the amount that the open pre-auth amount has been incremented by in cents.	Required
panLastFourDigits	String	The last 4 digits of the card PAN.	Optional

Response Handling | Increment Pre-Auth Request

The response to the increment Pre-Auth request is returned to the POS by iClient using the responseReceivedCallback at the completion of the increment pre-auth request. If the request is successful, the POS will be provided the result, the incremented amount, and the last 4 digits of the card PAN in the result , incrementalAmount, and panLastFourDigits fields, the POS must use them, and display the result and the message for the user’s reference and adjust the open pre-auth amount with the increment.

Response Example

Copy

Copied

{
  "result": "APPROVED",
  "incrementalAmount": "5000",
  "panLastFourDigits": "1234"
}

Response Received Callback | Complete Pre-Auth Request

Function Definition	Purpose	Parameters
responseReceivedCallback	Invoked when the request has been completed on the terminal. Called with a single object containing the following fields, as shown in the below table.	Required

Field	Type	Description	Usage Required
result	String	The result of the request, will be either ‘success’ or ‘failure’.	Required
message	String	A message to display to the merchant.	Required

Response Handling | Complete Pre-Auth Request

The response to the complete pre-auth request is returned to the POS by iClient using the responseReceivedCallback at the completion of the complete pre-auth request. If the request is successful, the POS will be provided the result, and an additional message in the result and the message fields, the POS must use them, and display the result and the message for the user’s reference and mark the pre-auth request as closed off.

Response Example

Copy

Copied

{
  "result": "success",
  "message": "Complete preAuth request accepted"
}

Response Received Callback | Void Pre-Auth Request

Function	Description	Usage Required
responseReceivedCallback	Invoked when the request has been completed on the terminal. Called with a single object containing the following fields, as shown in the below table.	Required

Field	Type	Description	Usage Required
result	String	The result of the request, will be either ‘success’ or ‘failure’.	Required
message	String	A message to display to the merchant.	Required

Response Handling | Void Pre-Auth Request

The response to the void pre-auth request is returned to the POS by iClient using the responseReceivedCallback at the completion of the void pre-auth request. If the request is successful, the POS will be provided the result, and an additional message in the result and the message fields, the POS must use them, and display the result and the message for the user’s reference and mark the pre-auth request as voided.

If the request is unsuccessful, the POS must use them, and display the result and the message for the user’s reference

Response Example

Copy

Copied

{
  "result":"success",
  "message":"Void preAuth request accepted"
  }