Welcome

Hi fellow code warrior, we hope you enjoy our local payment api and to keep evolving we want to collect as much feedback as possible.
So if you have any remarks/improvements please share it with us here.

To get going with the SDK we would like to introduce our global flow which is maintained through the api:

• create an instance of the api you need (PaymentApi, TerminalApi, TerminalDiscoveryApi, TokenApi)
• to know which one you need, I would recommend you our javadoc
• retrieve terminal information to create a request object, this will help with these information
• call instance method with request object

The following steps will guide you through your journey as a ccv integrator:

1. Start the terminal and connect it to the internet
2. Add the library to your project, add the jars/aars to the libs folder of your project
3. Follow the flow steps described above and start your integration journey

For android integrators we suggest reading our android part below

Initialize Android SDK

In the onCreate method of your MainActivity you need to initialize the Android SDK like follows:

    @Override
    protected void onCreate(@Nullable Bundle savedInstanceState) {
        MAPI.initialize(this);
    }

Now you’re all set up to make a payment

Retrieve terminal information

This information is required to create the terminal request object which is used across the api.

IP address

• Android terminals (IM30/A920/A77) use 127.0.0.1
• Other
  • We recommend to use our terminalDiscoveryService (discovery-guide) which will return the terminal request object that can be used further in the api
  • You can also manually find the ip using next steps:
    • Press red, green, yellow (x3)
    • Go to display info
    • Go to ethernet or wifi
    • Go to IP info
    • You will find the IP address at IP:

Android integration tips

We have 3 possible android pos integrations which will have their own tip & tricks:

• Integration with a separate standalone terminal (VX820, P400, …)
• Integration with an Android terminal (Pax A920, A77, …)
• Integration with an Android PhonePOS

Global

Compatibility Android API Levels

The compatibility is for all possible solutions. As our api uses some Java 8 features that are not compatible with all Android API Levels. If your projects provides support for Android API Levels that don’t support Java 8 features you will need to add some this functionality to your app build.gradle file.

Here you can find more information about Java 8 support for Android.

    android {
      defaultConfig {
        // Required when setting minSdkVersion to 20 or lower
        multiDexEnabled true
      }
    
      compileOptions {
        // Flag to enable support for the new language APIs
        coreLibraryDesugaringEnabled true
        // Sets Java compatibility to Java 8
        sourceCompatibility JavaVersion.VERSION_1_8
        targetCompatibility JavaVersion.VERSION_1_8
      }
    }
    
    dependencies {
      coreLibraryDesugaring 'com.android.tools:desugar_jdk_libs:1.0.9'
    }

Integration with an Android terminal

Switch from app to payment-engine and back

In order to switch from the local payment engine back to the integrator-app, you need to add an intent-filter to the activity in the AndroidManifest.xml file.

    
    <application
            android:allowBackup="true"
            android:icon="@mipmap/ic_launcher"
            android:label="@string/app_name"
            android:supportsRtl="true"
            android:theme="@style/AppTheme">
        <activity>
            <intent-filter>
                <action android:name="eu.ccv.service.ECR" />
                <category android:name="android.intent.category.DEFAULT" />
            </intent-filter>
        </activity>
    </application>

To prevent that the integrator-app restarts the activity when switching back from the local payment engine, you need to add android:launchMode=“singleTask” to the activity in the AndroidManifest.xml file.

    <application
        android:allowBackup="true"
        android:icon="@mipmap/ic_launcher"
        android:label="@string/app_name"
        android:supportsRtl="true"
        android:theme="@style/AppTheme">
        <activity
            android:name=".MainActivity"
            android:label="@string/app_name"
            android:configChanges="orientation"
            android:screenOrientation="portrait"
            android:theme="@style/AppTheme.NoActionBar"
            android:launchMode="singleTask">
        ...
        </activity>
    </application>

Integration with an Android phonePOS

You can find more information about the PhonePOS solution via this link. For the convenient integration of the PhonePOS solution with the Android ECR applications CCV provides the mAPI (Android SDK).

It is being advised that a cash register always uses the PaymentRecovery procedure when it does receive a response from the PhonePOS application (eg. because of the problem with Internet connection). It is the way to keep the same trx status in both the ECR and the payment apps. The documentation of a payment recovery can be found here.

Printer Device Requests must be deactivated for PhonePOS, as these can lead to communication problems between acCEPT/PhonePOS App/ECR App. The configuration options: “Off” or “ReceiptsInResponse” must therefore be selected. The “Default” option must not be selected. The documentation can be found here.