Payanywhere Android SDK

Products
Payanywhere Android SDK Integration Guide
mobile-sdk

How To Start

1. Sign up for a free North Developer account.
2. Contact us for credentials. Once credentials are provisioned, they can be referenced when logged in by selecting the User profile icon in the top right corner of the screen and selecting Credentials.
3. Apply for a Merchant Processing Account. Once approved, a Merchant ID (MID) will be provided to you.
4. Use the SDK specification to build your app. Resources to assist with development are provided here.
   When logged in, you can use the Integration Tracker to view the status of your integration, notes from meetings with Integration Engineers, resources related to your solution, and more by clicking the User profile icon in the top right corner of the screen and selecting Integrations.
5. When development is complete, contact us and once we ensure things are working properly, Production credentials will be provided to you.

To get started integrating your Android application with the Payanywhere SDK Android app for Android devices and PAX A920 Pro, you will first need to download and install Android Developer Studio. If you do not already have Android Developer Studio installed, you can download it here.

Setting up a Debug Device

With Android Developer Studio, you have a few choices for debugging and testing your application. You can use emulated devices inside Android Developer Studio or you can use a physical device.

Physical Debug Device

If you are developing for a PAX device, we recommend using a Debug device. Debug devices are used only for development and enable you to sideload APK files and transfer files via USB. If you use a Debug device, verify that it is already configured as a Debug device. Most PAX Debug devices will have a watermark icon on the bottom of the display screen that states “Debug only.” If your PAX device does not have this Debug watermark, you will not be able to use it as a Debug device.

If you use a Live device instead of a Debug one, you will need to obtain PAX Store approval each time you want to push an updated version of your application to your device. Sideloading APK files is prohibited on Live devices for security purposes.

Once your Android device is configured as a Debug device, power it on and connect it to your computer with a USB cable. This should be the same computer running Android Developer Studio. Once connected, you should be able to see that device listed as a Debug device in Android Developer Studio on the toolbar in the Connected Devices window. Below is an example of a PAX A920 Pro connected:

Emulated Debug Device

Below is an example of four emulated devices (circled in red):

Downloading and Installing the Payanywhere SDK APK

Once your physical or emulated debug device is set up and connected, you will need to download, install, and configure the Payanywhere SDK app. There are two options for sourcing and installing the Payanywhere SDK app: downloading from Google’s Play Store or manually sideloading the APK file.

Google Play Store

Sideloading the APK

• You do not have the Google Play Store app on your device
• You have a PAX device
• You are unable to locate the Payanywhere SDK app in the Google Play Store (on some emulated devices)
• You wish to load a specific version of the Payanywhere SDK

Before side loading, obtain the Payanywhere SDK APK file by downloading the link for the SDK package here. After unzipping the SDK package, navigate to the folder labeled, for example, “pa developer sdk 1.6.3.1 package.” In that folder, locate the file with a name similar to: “sdk-payanywhere-release_14136_63129.apk.”

Android Developer Studio includes a command line application called ADB to sideload APK files on Android devices. To sideload the Payanywhere SDK, first locate the folder containing the ADB executable file. For Windows the default path for this folder is C:\Users[YOUR_USER_NAME]\AppData\Local\Android\Sdk\platform-tools. Copy the sdk-payanywhere-release_14136_63129.apk file to this folder.

Once the APK file is in the same folder as the ADB executable, open a command prompt. Before typing any commands, power on and connect your Android Debug device. If you're using an emulated device, run the emulator for that device in Android Developer Studio and leave the emulator running. At the command prompt, navigate to the folder that contains the Payanywhere APK and the ADB executable using the change directory (CD) command. Once you've navigated the command line prompt to that location, type: adb install -r sdk-payanywhere-release_14136_63129.apk

Change the APK file name if using a different version of the Payanywhere SDK. After a short amount of time, you should get a response from the command line that the APK files were pushed successfully.

Configuring the Payanywhere SDK

Once the Payanywhere SDK has been installed, either through the Google Play Store or sideloaded, open the SDK app and configure it. For most Android OS builds, when you open the Payanywhere SDK app you will have to grant the app permissions to camera, location, microphone, phone, and storage resources. It is suggested that you go into the Android settings app and permanently grant permissions for all those resources, otherwise you may be prompted every time the app opens.

To permanently grant permissions, open the Google app named “Settings” and navigate to:

1. “Apps & notifications”
2. “PA SDK”
3. “Permissions”
   

Then enable the radio buttons for all the resources:

Next, open the Payanywhere SDK app and login with the account credentials for your test account. After your initial login, your credentials will be saved and you will not be prompted again. If you have a Bluetooth® card reader, you can pair it to the Payanywhere SDK at this time by selecting the three dots icon at the top right of the Payanywhere SDK app and selecting “Bluetooth Reader.” Be sure that Bluetooth® is enabled on the Android device and that the Bluetooth® reader is powered on. No pairing is necessary if you are using a PAX device.

Now that your Payanywhere SDK app is configured, you can begin the integration of your app with Payanywhere SDK.

Sending Requests From Your App To the Payanywhere SDK

On the SDK spec page, there are code examples for various Payanywhere payment functions. In most cases, there are a few lines of code that can be copied and pasted into your application.

This guide provides an example of integrating the Payanywhere Sale function in both Java and Kotlin, but you should be able to apply the same techniques to the other code samples/functions.

In these examples, a button function named: “saleButtonWasClicked” will be used to send a Sale request to the Payanywhere SDK.

Java Example

public void saleButtonWasClicked(View view) {

  
}

Next, paste the code example from the Reference page into that function to get the following:

public void saleButtonWasClicked(View view) {

	private static final String PAYMENT_URL = "payanywhere://payment/";
	private static final int PAYMENT_REQUEST_CODE = 123;

	Intent intent = new Intent(Intent.ACTION_VIEW , Uri.parse(PAYMENT_URL + "?chargeAmount=2.73"));
	startActivityForResult(intent, PAYMENT_REQUEST_CODE);
}

A few code changes may be required, for example the "private" and "static" modifiers may not be allowed in your function. To resolve this, you may want to change your code to the following:

public void saleButtonWasClicked(View view) {
	final String PAYMENT_URL = "payanywhere://payment/";
	final int PAYMENT_REQUEST_CODE = 123;

	Intent intent = new Intent(Intent.ACTION_VIEW , Uri.parse(PAYMENT_URL + "?chargeAmount=2.73"));
	startActivityForResult(intent, PAYMENT_REQUEST_CODE);
}

Some references may be unknown, for example "Intent" shown below. This is indicated by a red text color. For Windows users, left clicking your mouse on the word “Intent” and then pressing <Alt> + <Enter> will bring up a context menu. For Mac and Linux users, press <Option> + <Enter> to bring up the context menu.

When the context menu appears, selecting “Import Class” will resolve the "Unknown" issue.

To address the “Uri” reference in red text, Windows users can left click the mouse on the word “Uri” and then press <Alt> + <Enter>. Mac and Linux users can press <Option> + <Enter>.

With the code changes complete, you can run the app and test the function. When you connect your Debug device with Payanywhere installed and configured, select your debug device in the Devices window dropdown menu in the toolbar:

Press the green Run button:

When the application runs and you press the Test button in your application, you should see that the Payanywhere SDK app was launched and that the dollar amount specified by your application was passed to the Payanywhere SDK app. If the device has been recently restarted, you may have to launch the Payanywhere SDK app and sign in before sending requests from your application.

Kotlin Example

All of the code examples provided in the reference documentation are written in Java. If you are coding your application in Kotlin, Android Developer Studio has conversion tools to convert Java to Kotlin. The simplest way is to paste the Java code into your Kotlin file and Android Developer Studio will prompt to convert the code for you. For more information on converting Java to Kotlin, see “Convert existing Java code to Kotlin code” here: https://developer.android.com/kotlin/add-kotlin

After creating a button in the test application and defining the onClick properties and related code, you will have the following function:

fun saleButtonWasClicked(view: View) {
  
}

Next, paste the code example from the Reference page into that function. You may receive the following prompt from Android Developer Studio:

After clicking “Yes,” the function looks like this:

fun saleButtonWasClicked(view: View) {
	val PAYMENT_URL = "payanywhere://payment/"
	val PAYMENT_REQUEST_CODE = 123

	val intent = Intent(Intent.ACTION_VIEW, Uri.parse("$PAYMENT_URL?chargeAmount=2.73"))
	startActivityForResult(intent, PAYMENT_REQUEST_CODE)
}

Some issues may need to be resolved, such as “Uri” which has a red text color. For Windows users, left clicking your mouse on the word "Uri" and then pressing <Alt> + <Enter> will resolve the issue. For Mac and Linux users, press <Option> + <Enter>.

With the code changes complete, you can run the app and test the function. When you connect your Debug device with Payanywhere installed and configured, select your debug device in the Devices window dropdown menu in the toolbar:

And press the green Run button:

When the application runs and you press the Test button in your application, you should see that the Payanywhere SDK app was launched and that the dollar amount specified by your application was passed to the Payanywhere SDK app. If the device has been recently restarted, you may have to launch the Payanywhere SDK app and sign in before sending requests from your application.

Example Values For the SDK