menu

Payment API

What's on this page

In-person Payments / SoftPOS / Basic Operations / Install A Terminal

Install a terminal

Introduction

The CCV SoftPOS app needs to be installed before you can initiate a SoftPOS payment.
This manual will walk you through that process.
There are two steps in the process:

  1. Installation Request (API request)​
  2. Installation (app to app communication)​

Prerequisites


You have received a CCV SoftPOS dev kit.
If you don’t have one yet, request your dev kit here.

1. Installation Request

The terminal is already created in the TMS system of CCV but it needs to be activated.
You need an installationsPayload to install a SoftPos terminal. You can retrieve this payload by executing the following request.

API Request​

  • End-point: /api/v1/softpos/terminal/{terminalId}/install
  • Method: POST​
  • Authentication: API Key
  • Request Headers
    • Content-Type: application/json​
    • X-Merchant-Reference: (optional)
  • Path parameter
    • terminalId: The terminal id as assigned by CCV

API Response

Response parameters

Parameter Description
terminalId The terminal id as assigned by CCV.
terminalType The terminal type. Possible values: ‘softpos’.
installationPayload  The payload to continue the installation process for the terminal.

Example 

{
  "terminalId": "SP0001",
  "terminalType": "softpos",
  "installationPayload": "IfhGLwDjRrr4mgeFOVr6tkA="
}

2. Installation

The second step in the installation process is starting the CCV SoftPOS app and passing throught the installationPayload
You can do this by using the installTerminal method from the Android SDK.

Prerequisites:

  • NFC is enabled
  • Network connection available
  • Android developer options are disabled

2.1 SDK method examples

Install terminal method example (Java) 

    
    String installationPayload = "Ia6FZr3jQ0oxoEBqe2iJtQY=";

    SoftPosService softPosService = SoftPosService.getInstance(this.applicationContext);
    softPosService.installTerminal(activity, installationPayload, this::handleInitTerminalResult);

    private Unit handleInitTerminalResult(SoftPosInstallTerminalResult result) {
        if(result instanceof TerminalInstalled) {
            showAlertDialog("SoftPos Terminal Install", "Installation successful");
        } else if (result instanceof TerminalNotInstalled) {
            showAlertDialog("SoftPos Terminal Install", "Installation failed with error: " + ((TerminalNotInstalled) result).getError());
        }

        return Unit.INSTANCE;
    }

Deeplink url on development

ccvsoftpos-demo://installation?data={payload}&callback={callback}

ccvsoftpos-demo://installation?data=myInstallToken&callback=https%3A%2F%2Fccvposexample.eu%2Finstallation-complete

Deeplink url on production

ccvsoftpos://installation?data={payload}&callback={callback}

ccvsoftpos://installation?data=myInstallToken&callback=https%3A%2F%2Fccvposexample.eu%2Finstallation-complete

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

The callback should be a url scheme that will redirect to the webpage of the integrator. When the installation 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 installation but not launch the callback url on installation completion.

  • In case of a successful installation the callback will be followed by a status:
    {callback}?status=SUCCEEDED 
    https://ccvposexample.eu/installation-complete?status=SUCCEEDED
  • In case of a failed installation 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/installation-complete?status=FAILED&failure=NETWORK_ERROR&failureCode=11004&internalErrorCode=30000

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

Error handling

When an error occurs you will need to retry both step 1 (Installation Request) and step 2 (Installation). This is because the installationPayload from step 1 can only be used once.

Followup manuals