Payroc Cloud

Payroc Cloud is our semi-integrated payments solution that you can use to run card transactions without the need of a direct connection between the Point of Sale (POS) and the payment device.

To run transactions, program your POS to send an instruction to the payment device. An instruction contains information about the transaction, for example, the transaction amount and order information. The payment device then uses the information in the instruction to run the transaction.

There are two ways to use Payroc Cloud:

  • If you use a separate POS system and need to send instructions to other payment devices, go to Send instructions to a different device.
  • If you want to install a POS app on the payment device and run transactions on the same payment device, go to Send instructions to the same device.

The payment device can be on a different network or different location to the POS, however the payment device must be connected to the internet.

Note: You can’t use our API to cancel a transaction. The merchant must cancel the transaction on the payment device before the customer presents their card.

How it works

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

Payroc Cloud diagram

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.

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.

Guides

After you send an instruction to the payment device, the payment 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 you 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.

Payroc Cloud diagram

Initiate a transaction

  1. Your POS app sends an instruction to our gateway.
  2. Our gateway passes the instruction to the Payroc app.
  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, do the following:

  • Adjust permissions on the payment device.
  • Update the Payroc app.
  • Configure your activity to run a single task.
  • (Optional) Set the Payroc app to start first.

Adjust permissions on the payment device

Note: This applies only to Android 10 devices.

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

1private 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.

Note: The Payroc app doesn’t display the navigation bar. To view the navigation bar, tap the Payroc logo three times.

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