Configure Payroc Cloud for an Android device

You can send instructions to a payment device that is on a different network or at a different location than the POS, however the payment device must be connected to the internet.

How it works

The following diagram describes the flow of a transaction between the POS, our gateway, and the payment device.

Initiate a transaction

1. The POS sends an instruction to our gateway.
2. Our gateway passes the instruction to the payment device.
3. The payment device confirms that it has received the instruction.
4. Our gateway sends a response to the POS that contains an identifier for the instruction.

Run the transaction

1. The payment device captures the card details.
2. The payment device sends the transaction details to our gateway.
3. Our gateway sends the transaction details to the processor.
4. The processor sends a response to our gateway.
5. Our gateway sends the response to the payment device.

Get a link to the transaction

1. The POS sends a request to our gateway to check the status of the instruction.
2. Our gateway sends the response to your POS that contains a HATEOAS link to view the transaction.

View the transaction

1. The POS sends a request to our gateway to view the details of the transaction.
2. Our gateway sends a response to the POS that contains details about the transaction.

Guides

To integrate with our API so that you can send instructions to a payment device, go to our guides:

When you send an instruction to the payment device, the device uses the Payroc App to capture the card details. The Payroc App then sends the card details to our gateway with the transaction information.

If you use a POS app on the same device as the Payroc App, you need to switch between your POS app and the Payroc App after the following key events:

• When you receive a response to the instruction request.
• When you receive the details of the transaction.
• When the instruction is cancelled or fails.

How it works

The following diagram describes the flow of a transaction, between your POS app, our gateway, and the Payroc App.

Initiate a transaction

1. Your POS app sends an instruction to our gateway.
2. Our gateway passes the instruction to the Payroc pp.
3. The Payroc App confirms that it has received the instruction.
4. Our gateway sends a response to your app that contains an identifier for the instruction.
5. Switch to the Payroc App.

Run the transaction

1. The Payroc App captures the card details.
2. The Payroc App sends the transaction details to our gateway.
3. Our gateway sends the transaction details to the processor.
4. The processor sends a response to our gateway.
5. Our gateway sends the response to the Payroc App.

Get a link to the transaction

1. Your POS app sends a request to our gateway to check the status of the instruction.
2. Our gateway sends the response to your POS app that contains a HATEOAS link to view the transaction.

View the transaction

1. Your POS app sends a request to our gateway to view the details of the transaction.
2. Our gateway sends a response to your POS app that contains details about the transaction.
3. Switch to your POS app.
4. Your POS app displays the receipt.

To run follow-on actions, for example, to void a sale or to view the details of a refund, use the methods in our Payroc API.

Before you begin

Before you integrate with Payroc Cloud, complete the following:

1. Adjust permissions on the payment device.
2. Update the Payroc App.
3. Configure your activity to run a single task.
4. (Optional) Set the Payroc App to start first.

Adjust permissions on the payment device

To switch back to your POS app from the Payroc App, adjust the following permission in the manifest:

1
<uses-permission android:name="android.permission.SYSTEM_ALERT_WINDOW" />

Example code

1
private fun requestPermission() {
2
    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.M) {
3
        val intent = Intent(
4
            Settings.ACTION_MANAGE_OVERLAY_PERMISSION, Uri.parse("package:$packageName")
5
        )
6
        startActivityForResult(intent, ACTION_MANAGE_OVERLAY_PERMISSION_REQUEST_CODE)
7
    }
8
}

Update the Payroc App

To make sure that your Payroc App is up to date, open the Payroc App from the home screen. After you open the Payroc App from the home screen, the Payroc App fetches the latest version and settings.

Configure your activity to run a single task

To make sure that you return to the same activity instance when you switch back to your POS app, configure the launch mode to singleTask.

Example code

1
<activity
2
    android:name="com.payroc.appswitching.MainActivity"
3
    android:exported="true"
4
    android:label="@string/app_name"
5
    android:launchMode="singleTask"
6
    android:theme="@style/Theme.MyApplication.NoActionBar">
7
    <intent-filter>
8
        <action android:name="android.intent.action.MAIN" />
9
        <category android:name="android.intent.category.LAUNCHER" />
10
    </intent-filter>
11
</activity>

(Optional) Set the Payroc App to start first

If you want to start your POS app when the device turns on, you need to make sure that the Payroc App starts first. To make sure that the Payroc App starts first, set the priority of the intent filter in the boot receiver to 0.

Example code

1
<receiver
2
    android:name="com.payroc.appswitching.utils.BootReceiver"
3
    android:exported="true">
4
    <intent-filter android:priority="0">
5
        <action android:name="android.intent.action.BOOT_COMPLETED" />
6
    </intent-filter>
7
</receiver>

What to do after you create your app

After you create your app, upload it to the Paxstore. When you’re ready to release your app, contact us and we’ll link it to our Payroc account on the Paxstore.

Guides

To integrate with our API so that you can send instructions to a payment device, go to our guides: