-
Getting started
keyboard_arrow_down
Connect to the CCV Platform
Integrate our products into your software. Let's make payment happen together!
Look at all the possibilities
Integrate our products into your software. Let's make payment happen together!
Look at all the possibilitiesThe 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:
Prerequisites
You have received a CCV SoftPOS dev kit.
If you don’t have one yet, request your dev kit
here.
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.
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="
}
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.
public class MainActivity extends Activity {
void installTerminal(String payload) {
SoftPosService softPosService = SoftPosService.Companion.getInstance(this.getApplicationContext());
softPosService.installTerminal(this, payload, 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).getFailure());
}
return Unit.INSTANCE;
}
}
class MainActivity : Activity() {
fun installTerminal(payload: String) {
val softPosService = getInstance(this.applicationContext)
softPosService.installTerminal(
this,
payload
) { ::handleInitTerminalResult }
}
private fun handleInitTerminalResult(result: SoftPosInstallTerminalResult?) {
if (result is TerminalInstalled) {
showAlertDialog("SoftPos Terminal Install", "Installation successful")
} else if (result is TerminalNotInstalled) {
showAlertDialog(
"SoftPos Terminal Install",
"Installation failed with error: " + result.failure
)
}
}
}
SoftPosInstallTerminalResult is either a
TerminalInstalled in case of successTerminalNotInstalled in case of failureIn case of TerminalNotInstalled, 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 is described here: Installation errors
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 an 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
| 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 is described here: Installation errors
❗️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❗️
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. You can also consult our SoftPOS Error documentation for additional information about Failure and Failure Codes.