menu

Payment API

What's on this page

In-person Payments / SoftPOS / Basic Operations / Check Terminal Status

Check Terminal Status

Introduction

The purpose of this request is to check, via the CCV SoftPOS application, if this device is ready to execute a transaction via the provided TerminalId.
This is executed via the isReadyForTransaction method.

This request is optional and not required for every transaction. It can be used when needed— for example, at the start of a shift — to ensure the terminal is ready to execute transactions and to handle possible errors before starting the transaction flow.

This guide will walk you through the process to execute an isReadyForTransaction within CCV SoftPOS.

Prerequisites

You have the SoftPOS application installed on your device.

Perform a Terminal Status check

Unlike installation and payment, isReadyForTransaction communicates directly with the CCV SoftPOS app so no web API call is needed.

SDK example

    public class MainActivity extends Activity {

    void isReadyForTransaction(String terminalId) {
        SoftPosService softPosService = SoftPosService.Companion.getInstance(this.getApplicationContext());
        softPosService.isReadyForTransaction(this, terminalId, this::handleIsReadyForTransaction);
    }

    private Unit handleIsReadyForTransaction(SoftPosTransactionResult result) {
        if(result.isReady) {
            showAlertDialog("SoftPos Status", "Status ok");
        } else {
            showAlertDialog("SoftPos Status", "Status not ok");
        }

        return Unit.INSTANCE;
    }
}
        
    class MainActivity : Activity() {
    fun isReadyForTransaction(terminalId: String) {
        val softPosService = getInstance(this.getApplicationContext())
        softPosService.isReadyForTransaction(
            activity = this,
            terminalId = terminalId
        ) { ::handleIsReadyForTransactionResult }
    }

    private fun handleIsReadyForTransactionResult(result: eu.ccvlab.softpos.domain.SoftPosTerminalStatusResult) {
        if (result.isReady) {
            showAlertDialog("SoftPos Status", "Status ok")
        } else {
            showAlertDialog("SoftPos Status", "Status not ok")
        }
    }
}

    SoftPosTerminalStatusResult is either a

    • SoftPosTerminalStatusSucceeded in case of success
    • SoftPosTerminalStatusFailure in case of failure

    In case of SoftPosTerminalStatusFailure, extra values are returned providing more details

    Field Java getter Kotlin field More details
    Failure Code getFailureCode() failureCode String representation of the failure
    Failure getFailure() failure Numeric (int) representation of the failure
    Internal Error Code getInternalErrorCode() internalErrorCode Internal id of the failure. To be reported to CCV in case of unexpected errors

    Possible values for Failure(Code) and how to handle these are described here: isReadyForTransaction errors

    Deeplink url on development

    ccvsoftpos-demo://isReadyForTransaction?terminalId={terminalId}&callback={callback}

    ccvsoftpos-demo://isReadyForTransaction?terminalId=myTerminalId&callback=https%3A%2F%2Fccvposexample.eu%2Fisreadyfortransaction-result

    Deeplink url on production

    ccvsoftpos://isReadyForTransaction?terminalId={terminalId}&callback={callback}

    ccvsoftpos://isReadyForTransaction?terminalId=myTerminalId&callback=https%3A%2F%2Fccvposexample.eu%2Fisreadyfortransaction-result

    ❗️The callback url needs to be URL encoded❗️

    The callback should be an url scheme that will redirect to the webpage of the integrator. When the transaction completes the CCV SoftPOS app will redirect back to the callback url. Launching the callback url is a best effort from the CCV SoftPOS app. If the callback url is not url encoded or overal an invalid url, the CCV SoftPOS app will continue with the transaction but not launch the callback url on transaction completion.

    In case of a successful isReadyForTransaction the callback will be followed by a status:
    {callback}?status=SUCCEEDED 

    https://ccvposexample.eu/isreadyfortransaction-result?status=SUCCEEDED

    In case of a failed isReadyForTransaction the callback will be followed by a status, a failure and failureCode with an optional internalErrorCode.
    {callback}?status=FAILED&failure={FAILURE}&failureCode={failure_code}&internalErrorCode={internal_error_code} 

    https://ccvposexample.eu/isreadyfortransaction-result?status=FAILED&failure=NETWORK_ERROR&failureCode=16000&internalErrorCode=30000

    Callback parameter Details
    status Either SUCCEEDED or FAILED
    failure Numeric (int) representation of the failure
    failureCode String representation of the failure
    internalErrorCode Internal id of the failure. To be reported to CCV in case of unexpected errors

    Possible values for Failure(Code) and how to handle these are described here: isReadyForTransaction errors

    ❗️When launching the “ccvsoftpos://” deeplink with a path other then (installation, transaction or isReadyForTransaction) the isReadyForTransaction will fail with an INVALID_URL_SCHEME (14000) failure, only if a callback url is provided. If no callback url is provided, the CCV SoftPOS app will just close❗

    Follow-up manuals

    Based on the outcome of the isReadyForTransaction errors, you can proceed with the following steps: