Pax D135 - Android Quickstart

Build out your in-person payments integration using Finix's mobile SDK.

PAX D135 Integration Overview

The Pax D135 is a compact, mobile smart card reader designed for modern businesses on the go. Whether you're accepting payments in-store or out in the field, the D135 connects seamlessly to your Android or iOS device via Bluetooth, transforming your phone or tablet into a powerful payment terminal.

For additional details on the Pax D135, see Pax D135 Overview.

Android Demo Application

Step 1: Download Sample Application

To help you get started quickly, we provide a comprehensive Android Demo App that demonstrates the full capabilities of our mobile SDK.

You can clone the repository and run the Demo App to see our SDK in action, or use it as a reference for implementing your own solution.

Step 2: Run Sample Application

Please see the sample app to see how to interact with the SDK. The App works as follows:

Ensure the mPOS device has been paired to your phone/tablet via bluetooth.
Launch the app.
To connect the app to the device, first click the Scan for Devices button. This will scan for currently paired bluetooth devices.
Once the button is clicked a dialog would open showing a list of currently paired bluetooth devices.
Select the mPOS device. This will begin the process of connecting to the device and a loading spinner will be shown. You can observe the log output on the screen as it outputs messages of current progress.
Once the connection is complete and successful, one can initiate transactions by typing the amount into the TextField with the default value of 3.14 and clicking one of Sale, Auth, Refund.

Using the SDK

Create Role Merchant Credentials

All Finix Device SDK calls require ROLE_MERCHANT credentials. Once created, you can use these credentials across multiple devices as long as the devices are associated to the same Merchant.

Create Role Merchant Credentials Request

curl https://finix.sandbox-payments-api.com/identities/IDuWtgdP9VERb4FiLeYatWy/users \
    -H "Content-Type: application/json" \
    -H 'Finix-Version: 2022-02-01' \
    -u "USjHFGYvecE4LBitYG8KDE2g:b698f403-d9b7-4157-82d8-162cea8c8cc3" \
    -d '{}'

Create Role Merchant Credentials Response

{
    "id": "USxxxxxxxxxxxxxxxxxxxxxx",
    "created_at": "2022-10-10T06:05:08.11Z",
    "updated_at": "2022-10-10T06:05:08.11Z",
    "enabled": true,
    "identity": "IDxxxxxxxxxxxxxxxxxxxxxx",
    "password": "xxxxxxxxxxxxxxxxxxxxxx",
    "role": "ROLE_MERCHANT",
    "tags": {},
    "_links": {
        "self": {
            "href": "https://finix.sandbox-payments-api.com/users/USgymgj1dSkCNxYmZKd9GxQN"
        },
        "applications": {
            "href": "https://finix.sandbox-payments-api.com/applications"
        },
        "application": {
            "href": "https://finix.sandbox-payments-api.com/applications/APeUbTUjvYb1CdPXvNcwW1wP"
        }
    }
}

Installation

Add dependency in gradle file. See Maven Central or MVN Repository for the latest version.

implementation("com.finix:pax-mpos-sdk-android:2.1.1")

Initialization

Add permission to AndroidManifest to interact with mPOS device via Bluetooth

<!-- For network communication -->
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />

<!-- For bluetooth communication -->
<uses-permission android:name="android.permission.BLUETOOTH" />
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" /><!-- TargetSdkVersion greater than or equal to 31 -->
<uses-permission android:name="android.permission.BLUETOOTH_SCAN" />

To interact with the MPOS device, it first needs to be initialized. This can be done by initializing the class mposFinix.

class mposFinix(private val context: Context, private val merchantData: MerchantData)

context: Android application context
merchantData: Specific values which help identify the merchant

class MerchantData (
    val merchantId: String,     //Merchant Id from Finix starting with MUxxxx
    val mid: String,            //Finix mid (GUID representation)
    val deviceId: String,       //Device ID - device registers with Finix
    val currency: String = "USD",
    val env: String = "sandbox",   //sandbox or production
    val userId : String, // ROLE_MERCHANT UserId
    val password: String //  ROLE_MERCHANT password
)

Example : val mpos = mposFinix(
    context,
    MerchantData(
        merchantId = "MUeDVrf2ahuKc9Eg5TeZugvs",
        mid = "3f4e4e1c-b8fc-40",
        deviceId = "DVvyDYDzp8Z",
        env = "sandbox", //Possible values are sandbox and production
        userId = "USsRhsHYZGBPnQw8CByJyEQW",
        password = "8a14c2f9-d94b-4c72-8f5c-a62908e5b30e"
  )
)

Once initialized, connect to the device. When the device is ready for pairing, it will show an orange light and green light. Once connected, the orange light will disappear and only the green light will stay on.

fun connect(deviceName: String, deviceAddress: String, callback: MPOSConnectionCallback)

deviceName : bluetooth name of the device
deviceAddress : bluetooth address of the device
callback: exposes functions which are invoked to propagate success, error, progress

interface MPOSConnectionCallback {
    fun onSuccess() // Called if the connection is successfully established
    fun onError(errorMessage: String) // Called if the connection fails for some reason
    fun onProcessing(currentStepMessage: String) // Provides status messages of what's currently happening
}

Start Transaction

To start a transaction, the function startTransaction() must be called. This will prep the mPOS device to accept card input (swipe, tap, insert). A blue status light will be shown. Once any action is performed with the card the device would show a red light to indicate, the card has been read and to remove it.

fun startTransaction(
    amount: Long,
    transactionType: String,
    transactionCallback: MPOSTransactionCallback,
    configureEMVResponseCallback: MPOSEMVProcessingCallback
 )

amount : amount in cents for \$10.10 this value would be 1010
transactionType : "Sale", "Auth", "Refund" only one of these values should be passed
transactionCallback : Exposes functions which are invoked with status of the transaction or the Transaction Result
configureEMVResponseCallback: Exposes functions which are invoked to with status of authorizing a card insert

interface MPOSTransactionCallback {
    fun onSuccess(result: TransactionResult?) // Called if the transaction is successfully processed
    fun onError(errorMessage: String) // Called if the transaction fails for any reason
    fun onProcessing(currentStepMessage: String) // Provides status messages of what's currently happening
}

interface MPOSEMVProcessingCallback {
    fun onError(errorMessage: String) // Called if the authorization of chip insert fails for any reason
    fun onProcessing(currentStepMessage: String) // Provides status messages of what's currently happening
}

Referenced Refund

A referenced refund, refunds the amount specified (refund amount) of a particular transaction (transaction id) to the card on file

fun startRefund(
    transactionId: String,
    refundAmount: Long,
    refundCallback: MPOSRefundCallback
)

transactionId : The transaction id specified correlating to a previous transaction. The ID is returned as part of the TransactionResult
in the above start transaction
refundAmount : amount in cents for \$10.10 this value would be 1010
refundCallback : Exposes functions which are invoked with status of the refund or the Refund Result

Device Unreachable

Add a warning or statement not to exit out of payment application or put the device in sleep mode. If they exit out of the application or put the device in sleep mode, they will likely get the above error.

Proguard Rules

If you're using proguard please add the following to your proguard rules.

#Retrofit
 -dontwarn retrofit.**
 -keep class retrofit.** { *; }
 -keepattributes Signature
 -keepattributes Exceptions
 -keepattributes RuntimeVisibleAnnotations
 -keepattributes RuntimeInvisibleAnnotations
 -keepattributes RuntimeVisibleParameterAnnotations
 -keepattributes RuntimeInvisibleParameterAnnotations

#OkHttp3
 -keepattributes Signature
 -keepattributes *Annotation*
 -keep class okhttp3.** { *; }
 -keep interface okhttp3.** { *; }
 -dontwarn okhttp3.**
 -dontwarn java.nio.file.*
 -dontwarn org.codehaus.mojo.animal_sniffer.IgnoreJRERequirement

#Gson
  -keep class com.google.gson.stream.** { *; }

#Finix
 -dontwarn com.finix.mpos.sdk.**
 -keep class com.finix.mpos.sdk.** { *; }
 -keep class com.finix.mpos.models.** { *; }
 -dontwarn java.lang.invoke.StringConcatFactory

Next Steps

Testing Your Integration

Learn how to test your In-Person Payments integration.