Native Android SDK · Gravity Payments Documentation

Device Supported

Model	Connection Type	Card Type
MagTek iDynamo 6	USB-C	MSR, Contact, Contactless

Minimum Targeted Android Version

Android SDK Version 21

Getting Started

Add the coresdk aar to the libs directory in your app folder:
<your-app-directory>/libs/coresdk-<version>.aar

Add the following dependencies to your build.gradle:

implementation 'com.fasterxml.jackson.module:jackson-module-kotlin:2.12.3'
implementation 'com.squareup.retrofit2:retrofit:2.9.0'
implementation 'com.squareup.retrofit2:converter-jackson:2.9.0'
implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-android:1.3.9'
implementation 'androidx.navigation:navigation-fragment-ktx:2.3.5'
implementation 'androidx.navigation:navigation-ui-ktx:2.3.5'

The coresdk does not require you to make changes to your AndroidManifest.xml

Listener Interface

The emergepay Android SDK uses an event driven interface for communicating back to your
calling application during a transaction request. You will need to create a class that implements
the OnEventListenerInterface exported from the emergepay SDK in order to handle events
and to receive the final transaction result when you make a request.
You will need to override the onEvent and onError methods which receive events in the form of
instances of the emergepay Event class and subclasses of the emergepay BaseError class
respectively.

class Listener(private val context: AppCompatActivity) : OnEventListenerInterface {
    override fun onEvent(event: Event) {
        when (event.type) {
            EventType.TransactionCompletion -> {
                if (event.response?.transactionResponse?.resultStatus.equals("true")) {
                // persist transaction result
                }
            }
            EventType.DeviceConnectionStateChange -> {
                // handle connection state changes
            }
            EventType.DisplayMessageRequest -> {
                // display actionable messages on screen
            }
            EventType.DeviceCancellationRequest -> {
                // track result of cancellation request
            }
        }
    }
    override fun onError(error: BaseError) {
        // handle errors
    }
}

Emergepay Client

You will instantiate the emergepay client as a singleton in the onCreate method of your activity
that will handle transaction processing. The listener that you pass into the emergepay instance
will handle the events for every transaction request during the activity’s lifecycle.

Emergepay(oid: string, authToken: string, listener: OnEventListenerInterface, context: Context): Emergepay

package com.yourdomain.app
import androidx.appcompat.app.AppCompatActivity
import com.gravitypayments.coresdk.Emergepay
import com.gravitypayments.coresdk.OnEventListenerInterface
import com.gravitypayments.coresdk.models.*
import com.gravitypayments.coresdk.events.*
import com.gravitypayments.coresdk.errors.*
import com.yourdomain.app.yourpackage.Listener

class MainActivity : AppCompatActivity() {
    private var OID = // your oid
    private var emergepay: Emergepay? = null
    override fun onCreate(savedInstanceState: Bundle?) {
        emergepay = Emergepay(OID, AUTH_TOKEN, Listener(this), this)
        // onCreate business logic
    }

Processing a Transaction

We provide utility builder classes for instantiating your transaction request objects by way of
method chaining. You pass your parameters into the setter methods on the builder class for the
specific transaction type you are processing, and then call the build method on the builder class
to create your request object.

When building your configuration object, call the deviceTransaction method passing in the
boolean true if you intend to run the transaction through the magtek device, or with false if you
intend to use manual entry. The env setter allows you to designate which environment you
choose to process the transaction against.

After creating your configuration object, call the transaction method on your Emergepay
singleton to initiate the transaction type you want to process. You will need to pass your
context into transaction methods as the second parameter for Credit Sale, Credit Auth, and
Credit Return. The example below illustrates building the configuration for a “CreditSale”
transaction and then calling the corresponding emergepay.creditSale() method to initiate a
transaction. The other transaction types follow:

Device and Manual Entry Transaction Types

Credit Sale

private fun creditSale() {
    val config = CreditSaleConfig.Builder()
        .oid(OID)
        .authToken(AUTH_TOKEN)
        .amount("10.00")
        .billingAddress("1234 Test St.")
        .billingName("Cardholder Name")
        .billingPostalCode("98107")
        .cashierId("Shift lead")
        .externalTransactionId(<v4 uuid>)
        .tipAmount("1.00")
        .transactionReference("Invoice 1234")
        .deviceTransaction(true)
        .env("production")
        .build()
          
    emergepay!!.creditSale(config, this)
}

property	type	required	description
oid	String	yes	Gravity location oid
authToken	String	yes	Gravity authorization token
amount	String	yes	Base transaction amount in decimal format with a minimum of 4 characters, ie "0.50"
externalTransactionId	String	yes	v4 uuid for tracking the transaction
billingAddress	String	no	Billing address for card
billingName	String	no	Billing name for the transaction
billingPostalCode	String	no	Billing zip code for card
cashierId	String	no	Cashier handling transaction
tipAmount	String	no	Tip amount, added to base amount to calculate transaction total, in decimal format with a minimum of 4 characters, ie "0.50"
transactionReference	String	no	Internal reference number for transaction
deviceTransaction	boolean	no	Indicates if transaction will process through the card reader or manual entry. Defaults to false
env	String: "production " \| "sandbox"	no	Indicates which environment transaction will process through. Defaults to "sandbox"

Credit Return

private fun creditReturn() {
    val config = CreditReturnConfig.Builder()
        .oid(OID)
        .authToken(AUTH_TOKEN)
        .amount("10.00")
        .billingAddress("1234 Test St.")
        .billingName("Cardholder Name")
        .billingPostalCode("98107")
        .cashierId("Shift lead")
        .externalTransactionId(<v4 uuid>)
        .transactionReference("Invoice 1234")
        .deviceTransaction(true)
        .env("production")
        .build()
          
    emergepay!!.creditReturn(config, this)
}

property	type	required	description
oid	String	yes	Gravity location oid
authToken	String	yes	Gravity authorization token
amount	String	yes	Base transaction amount in decimal format with a minimum of 4 characters, ie "0.50"
externalTransactionId	String	yes	v4 uuid for tracking the transaction
billingAddress	String	no	Billing address for card
billingName	String	no	Billing name for the transaction
billingPostalCode	String	no	Billing zip code for card
cashierId	String	no	Cashier handling transaction
transactionReference	String	no	Internal reference number for transaction
deviceTransaction	boolean	no	Indicates if transaction will process through the card reader or manual entry. Defaults to false
env	String: "production " \| "sandbox"	no	Indicates which environment transaction will process through. Defaults to "sandbox"

Credit Auth

private fun creditAuthorization() {
    val config = CreditAuthConfig.Builder()
        .oid(OID)
        .authToken(AUTH_TOKEN)
        .amount("10.00")
        .billingAddress("1234 Test St.")
        .billingName("Cardholder Name")
        .billingPostalCode("98107")
        .cashierId("Shift lead")
        .externalTransactionId(<v4 uuid>)
        .tipAmount(null)
        .transactionReference("Invoice 1234")
        .deviceTransaction(true)
        .env("production")
        .build()
          
    emergepay!!.creditAuthorization(config, this)
}

property	type	required	description
oid	String	yes	Gravity location oid
authToken	String	yes	Gravity authorization token
amount	String	yes	Base transaction amount in decimal format with a minimum of 4 characters, ie "0.50"
externalTransactionId	String	yes	v4 uuid for tracking the transaction
billingAddress	String	no	Billing address for card
billingName	String	no	Billing name for the transaction
billingPostalCode	String	no	Billing zip code for card
cashierId	String	no	Cashier handling transaction
tipAmount	String	no	Tip amount, added to base amount to calculate transaction total
transactionReference	String	no	Internal reference number for transaction
deviceTransaction	String	no	Indicates if transaction will process through the card reader or manual entry. Defaults to false
env	String: "production " \| "sandbox"	no	Indicates which environment transaction will process through. Defaults to "sandbox"

Credit Save Card

This transaction is used to store a customer’s card on file behind a token and currently requires entering the card number through the emergepay ui instead of capturing the card number through the device.

private fun creditSaveCard() {
    val config = CreditSaveCardConfig.Builder()
        .oid(OID)
        .authToken(AUTH_TOKEN)
        .billingAddress("1234 Test St.")
        .billingName("Cardholder Name")
        .billingPostalCode("98107")
        .cashierId("Shift lead")
        .externalTransactionId(<v4 uuid>)
        .transactionReference("Invoice 1234")
        .env("production")
        .build()
          
    emergepay!!.creditSaveCard(config, this)
}

property	type	required	description
oid	String	yes	Gravity location oid
authToken	String	yes	Base transaction amount in decimal format with a minimum of 4 characters, ie "0.50"
externalTransactionId	String	yes	v4 uuid for tracking the transaction
billingAddress	String	no	Billing address for card
billingName	String	no	Billing name for the transaction
billingPostalCode	String	no	Billing zip code for card
cashierId	String	no	Cashier handling transaction
transactionReference	String	no	Internal reference number for transaction
env	String: "production " \| "sandbox"	no	Indicates which environment transaction will process through. Defaults to "sandbox"

Credit Force

This is the transaction type for capturing a prior Credit Auth transaction. The uniqueTransId
returned from the Credit Auth transaction request is passed into the configuration builder below.

private fun creditForce() {
    val config = CreditForceConfig.Builder()
        .oid(OID)
        .authToken(AUTH_TOKEN)
        .uniqueTransId("ce9ad61b3c984a7999677a527cb26a2a-00000000000000...")
        .amount("10.00")
        .cashierId("Shift lead")
        .externalTransactionId(<v4 uuid>)
        .tipAmount(null)
        .transactionReference("Invoice 1234")
        .env("production")
        .build()
          
    emergepay!!.creditForce(config)
}

property	type	required	description
oid	String	yes	Gravity location oid
authToken	String	yes	Gravity authorization token
externalTransactionId	String	yes	v4 uuid for tracking the transaction
uniqueTransId	String	yes	uniqueTransId from original Credit Auth transaction
amount	String	no
cashierId	String	no	Cashier handling transaction
tipAmount	String	no	Tip amount, added to base amount to calculate transaction total

Void

This is the transaction type for voiding a prior Credit Auth, Credit Return, or Credit Sale
transaction. The uniqueTransId returned from the original transaction request is passed into
the configuration builder below.

private fun creditVoid() {
    val config = CreditVoidConfig.Builder()
        .oid(OID)
        .authToken(AUTH_TOKEN)
        .uniqueTransId("ce9ad61b3c984a7999677a527cb26a2a-00000000000000...")
        .cashierId("Shift lead")
        .externalTransactionId(<v4 uuid>)
        .transactionReference("Invoice 1234")
        .env("production")
        .build()
          
    emergepay!!.creditVoid(config)
}

property	type	required	description
oid	String	yes	Gravity location oid
authToken	String	yes	Gravity authorization token
externalTransactionId	String	yes	v4 uuid for tracking the transaction
uniqueTransId	String	yes	uniqueTransId from original Credit Auth transaction
cashierId	String	no	Cashier handling transaction
transactionReference	String	no	Cashier handling transaction
env	String: "production " \| "sandbox"	no	Indicates which environment transaction will process through. Defaults to "sandbox"

Cancel Transaction

This method is used to cancel a pending device transaction and takes no parameters.

private fun cancelTransaction() {
    emergepay!!.cancelTransaction()
}

Connect to Device

This method is used to reconnect to the device after a disconnect event and takes the activity
context as a parameter.

private fun connect() {
    emergepay!!.connectToDevice(this)
}

Transaction Response

The TransactionResponse class contains a single transactionResponse property that is
an instance of the TransactionResponseData class. An instance of the
TransactionResponse class is returned for every transaction type.

property	type	description
accountCardType	String	The card type that was processed
accountEntryMethod	String	Entry type of the transaction
accountExpiryDate	String	The expiration date of the card
amount	String	Base amount of the transaction, ex. "1.00"
amountBalance	String	Reserved for future use
amountProcessed	String	Amount total with tip included, ex. "1.00"
amountTaxed	String	Currently unused
avsResponseCode	String	AVS result code for manual entry transactions
avsResponseText	String	Text description of AVS response
batchNumber	String	Currently unused
billingName	String	Customer’s billing name from the card or from the request configuration for manual entry
cashier	String	Cashier from the request configuration
cvvResponseCode	String	CVV result code for manual entry transactions
cvvResponseText	String	Text description for CVV response
emv	EMVData	An object containing additional metadata for EMV based transactions
externalTransactionId	String	The externalTransactionId from the request
isPartialApproval	String	A value indicating whether or not the transaction was partially approved
maskedAccount	String	The masked account number of the card
resultMessage	String	A text description for the result of the transaction
resultStatus	String	A string describing the result of the transaction. Should be "true" or "false"
transactionReference	String	The transaction reference from the request
transactionType	String	The type of transaction that was processed
uniqueTransId	String	The uniqueTransactionId returned from emergepay

Firmware Updates

The iDynamo6 device will occasionally need to have its firmware updated. Gravity will email partners utilizing the SDK whenever a new update is available. Gravity has provided two different
method calls that will facilitate updating the device firmware.

Check Firmware Version

We provide the checkFirmwareVersion() method in order for the client to quickly compare
their firmware version to the most recent version. This method will trigger the
DeviceCommandResponse event type with the current firmware version the device is using.

private fun checkFirmwareVersion() {
    emergepay!!.checkFirmwareVersion()
}

Update Firmware

This method is used to update the device firmware and takes the activity context as a
parameter. This method will trigger the DeviceFirmwareUpdateStateChange event type
periodically through the update process. If the update has completed successfully, the
FirmwareUpdateComplete event will fire. In the event of an error, a
FirmwareUpdateError error will fire.

The firmware update process can take between 2-7 minutes to complete depending on the host
device and network connection. The device can not be plugged into any power source when
attempting the update, and the device must not go to sleep during the update, as the user will
need to re-establish the connection to the device periodically through the update. Failure to do
so will result in a FirmwareUpdateError. If an error occurs during the update, the user will
need to try again.

It is recommended that the device be fully charged, and all sleep settings turned off for the
duration of the update.

private fun updateFirmware(this) {
    emergepay!!.updateFirmware()
}

Handling Events

OnError()

Your override method for onError will receive instances of classes that descend from the BaseError class.

Error

property	type	description
errorDomain	EventDomain enum	values of: CardPresent, ManualEntry, TokenizedTransaction, DeviceState, DataValidation, IO, TransactionState, FirmwareUpdateError
errorCode	Int	An integer error code for keying off of the event in response handling. See Error Codes list below
recoverySuggestion	String	A suggestion for handling/resolving the error
message	String	A text description of the error

Error Codes

3 digit error codes represent http error codes and will match the canonical descriptions for those
codes. 4 digit codes are issued by the SDK. If an error code is listed as terminal, receiving the
code means the current transaction session has ended and you will need to send a new
request.

Code	Description	Terminal
1000	Request parameter error	Y
2000	The Magtek device is not accessible to the SDK	Y
2001	The SDK is unable to connect to the Magtek device	Y
2002	The device is disconnected	Y
2003	An error occurred trying to cancel the transaction	N
2004	The device is in use and unable to receive new requests	N
3000	An unknown error occurred	N
3001	A transaction is in progress. Please wait until the current transaction is completed before sending another request.	Y
3002	No active transaction	Y
3003	The user cancelled the transaction	Y

onEvent()

Your override method for onEvent will receive instances of the Event class.

Event

property	type	description
domain	EventDomain enum	values of: CardPresent, ManualEntry, TokenizedTransaction, DeviceState, DataValidation, IO, TransactionState, DeviceFirmware
type	EventType enum	values of: TransactionCompletion, DeviceConnectionStateChanged, DisplayMessageRequest, DeviceCancellationRequest, TransactionStatusUpdate, DeviceCommandResponse, DeviceFirmwareUpdateStateChange, FirmwareUpdateComplete
message	String	A text description of the event
response	TransactionResponse	An instance of the TransactionResponse class with the final transaction result. This property will be null in most events and the presence of this property indicates that the transaction was completed and the transaction session has ended.