Transactions

states these are the possible states when processing a docid\ xftyvcscnepqsmjfz6o4a or docid\ ezdh0uhdpd1bvbgcddqio enum class transactionstate { / transaction is idle and ready to start / ready, / attempting connection to the \[toroclient selecteddevice] / connecting to device, / awaiting confirmation of gratuity amount from the customer only applicable if \[toroconfig gratuityenabled] is true / awaiting gratuity, / awaiting customer to present card on any interface (contact, contactless, magswipe) / awaiting card, / awaiting customer signature (in app or on device) @see toroconfig signaturemode / awaiting signature, / awaiting customer to enter pin on the device / awaiting pin entry, / awaiting customer to select application on the device / awaiting application selection, / contacting the gateway to authorise the transaction / authorising, / transaction was completed successfully and an outcome was received (approved, declined etc ) / completed, / transaction was cancelled by the user or operator / cancelled, / transaction failed due to an error / failed } transaction state listener to receive transaction state updates, you can implement the transactionstatelistener and register it with the toroclient instance val transactionstatelistener = transactionstatelistener { newstate > // handle transaction state updates here } // register the listener with the toroclient instance toro settransactionstatelistener(transactionstatelistener)transactionstatelistener listener = state > { // handle transaction state updates here }; toro settransactionstatelistener(listener); alternatively, you can use the transactionstate property on the toroclient instance to check the current state of the transaction val transactionstate = toro transactionstatetransactionstate state = toro gettransactionstate(); this will return the current transaction state as a transactionstate enum value metadata the transactionmetadata class allows you to include additional information with docid\ xftyvcscnepqsmjfz6o4a and docid\ ezdh0uhdpd1bvbgcddqio / optional metadata for the transaction / data class transactionmetadata( / custom id for the transaction this salereferenceid will be returned in the \[transactionreceipt] max length is 35 characters / val salereferenceid string? = null, / the gratuity amount for the transaction the gratuity amount is added to the transaction amount specified in starttransaction() this is useful if you are wanting to use a custom gratuity flow outside of the sdk / val gratuityamount int = 0, / details of the original transaction that is being refunded, cancelled or completed not applicable for purchases / val originaltransactiondetails originaltransactiondetails? = null, / any other additional data you want returned in the \[transactionreceipt] this data will be sent in the `acceptorauthorisationrequest` accptrauthstnreq/authstnreq/tx/txdtls/addtlinf / val additionalinformation map\<string, any?> = emptymap() ) cancelling an in progress transaction to cancel an in progress docid\ xftyvcscnepqsmjfz6o4a or docid\ ezdh0uhdpd1bvbgcddqio , you can call the canceltransaction method on the toroclient instance toro canceltransaction()toro canceltransaction(); this will also close the usb/bluetooth session with the miura device if it is open card events possible events and their descriptions are below enum class cardevent { / card inserted into the chip reader / cardinserted, / card removed from the chip reader / cardremoved, / card swiped on magnetic stripe reader / cardswiped, / represent the card on any interface / trycardagain, / represent the card using either chip or magnetic stripe reader / insertorswipecard, / represent the card using chip reader / insertcard; } card event listener the sdk will notify you of card events using the cardeventlistener interface you can register a cardeventlistener with the toroclient instance like so val cardeventlistener = cardeventlistener { event > // handle card events here } // register the listener with the toroclient instance toro setcardeventlistener(cardeventlistener)cardeventlistener cardeventlistener = event > { // handle card events here }; // register the listener with the toroclient instance toro setcardeventlistener(cardeventlistener); signatures the sdk provides two different methods for collecting cardholder signatures the method used depends on the signaturemode set in the toroconfig see docid 59sfhn6 zrin1pewwtmz8 for more information signaturemode device the signature will be captured on the miura device this is only applicable to devices which have a touch screen (e g , m021) no additional configuration is required for this mode to work signaturemode app the signature will be captured in the app this can be used for all devices, and requires some setup for it to work this setup can be seen in the transactionprocessingfragment in the sample application @androidentrypoint class transactionprocessingfragment fragment() { private var binding fragmenttransactionprocessingbinding? = null private val binding get() = binding!! @inject lateinit var toro toroclient override fun oncreateview( inflater layoutinflater, container viewgroup?, savedinstancestate bundle? ) view { binding = fragmenttransactionprocessingbinding inflate(inflater, container, false) handlesignature() return binding root } private fun handlesignature() { // register for the signature activity result val launcher = registerforactivityresult( activityresultcontracts startactivityforresult(), toro signatureactivityresultcallback ) // pass the launcher to the toroclient instance so it can // process the result toro setsignaturelauncher(launcher) } }@androidentrypoint public class transactionprocessingfragment extends fragment { private fragmenttransactionprocessingbinding binding; @inject toroclient toro; @override public view oncreateview( layoutinflater inflater, viewgroup container, bundle savedinstancestate ) { binding = fragmenttransactionprocessingbinding inflate(inflater, container, false); handlesignature(); return binding getroot(); } private void handlesignature() { // register for the signature activity result activityresultlauncher\<intent> launcher = registerforactivityresult( new activityresultcontracts startactivityforresult(), toro getsignatureactivityresultcallback() ); // pass the launcher to the toroclient instance so it can // process the result toro setsignaturelauncher(launcher); } @override public void ondestroyview() { super ondestroyview(); binding = null; } } in your app, you should call toro setsignaturelauncher(launcher) in the activity/fragment where the transaction will be in a awaiting signature state the sdk will then automatically launch the signatureactivity when required the activity is shown below receipt below is the transactionreceipt object you will receive in the oncompleted callback when calling starttransaction() for a docid\ xftyvcscnepqsmjfz6o4a or docid\ ezdh0uhdpd1bvbgcddqio data class transactionreceipt( / unique reference number to identify the transaction can be set in \[transactionmetadata] / val salereferenceid string? = null, / the total amount of the transaction represented in the smallest unit of the currency, e g cents for usd, pence for gbp / val amount int, / the amount of the transaction that was authorised by the acquirer in most cases the same as \[amount], but can differ e g partial approvals / val authorisedamount int? = null, / the type of transaction purchase, refund @see transactiontype / val type transactiontype, / gratuity amount confirmed by the customer this can be set either through \[transactionmetadata] or when \[toroconfig gratuityenabled] is set to true and the built in gratuity flow is used / val gratuityamount int, / the currency of the transaction / val currency currencycode, / the authorisation code set by the acquirer / val authcode string? = null, / the result of the authorisation (acquirer decision) typically approved or declined / val responsecode responsecode, / the reason for the \[responsecode] / val responsereason string? = null, / cardholder verification method / val authenticationmethod authenticationmethod8? = null, / additional response information (from gateway or acquirer) / val additionalresponseinformation string? = null, / also known as the authorisation response code emv tag 8a set by the acquirer / val actioncode string? = null, / application identifier of the card that was presented / val aid string? = null, / application label of the card that was presented / val applicationlabel string? = null, / the payment interface used to process the transaction e g contactless / val paymentinterface paymentinterface, / the first 6 or 8 digits of the primary account number (pan) aka bank identification number (bin) / val panstart string?, / the last 4 digits of the primary account number (pan) / val panlastfour string?, / identifier set by the recipient (acquirer) to reference the transaction this can be the same as the \[initiatortransactionid] depending on the acquirer / val recipienttransactionid string?, / identifier set by the initiator (merchant) to reference the transaction the toro sdk handles this internally and cannot be overridden by the host application / val initiatortransactionid string?, / unique identification of the transaction assigned by the poi (point of interaction) / val transactionreference string?, / the date and time the transaction occurred in iso 8601 format / val datetime string?, / the serial number of the terminal the transaction was processed on / val terminalserialnumber string, / cardholder signature base64 encoded if applicable / val signaturebase64 string? = null, / indicates whether the signature verification failed, either due to merchant rejection or customer cancellation during signature entry the host application should send cancellation advice in this case / val signatureverificationfailed boolean = false, / whether the transaction was captured by the acquirer / val captured boolean, / the latitude of the device at the point of transaction / val longitude string? = null, / the longitude of the device at the point of transaction / val latitude string? = null, / the custom data set in \[transactionmetadata] / val additionalinformation map\<string, any?>? = null )