Native Android SDK

Device Supported

ModelConnection TypeCard Type
MagTek iDynamo 6USB-CMSR, Contact, Contactless

Minimum Targeted Android Version

Android SDK Version 21

Getting Started

Add the coresdk aar to the libs directory in your app folder:

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

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

import com.gravitypayments.coresdk.Emergepay
import com.gravitypayments.coresdk.OnEventListenerInterface
import com.gravitypayments.coresdk.models.*
import com.gravitypayments.coresdk.errors.*

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

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.

accountCardTypeStringThe card type that was processed
accountEntryMethodStringEntry type of the transaction
accountExpiryDateStringThe expiration date of the card
amountStringBase amount of the transaction, ex. "1.00"
amountBalanceStringReserved for future use
amountProcessedStringAmount total with tip included, ex. "1.00"
amountTaxedStringCurrently unused
avsResponseCodeStringAVS result code for manual entry transactions
avsResponseTextStringText description of AVS response
batchNumberStringCurrently unused
billingNameStringCustomer’s billing name from the card or from
the request configuration for manual entry
cashierStringCashier from the request configuration
cvvResponseCodeStringCVV result code for manual entry transactions
cvvResponseTextStringText description for CVV response
emvEMVDataAn object containing additional metadata for EMV based transactions
externalTransactionIdStringThe externalTransactionId from the request
isPartialApprovalStringA value indicating whether or not the
transaction was partially approved
maskedAccountStringThe masked account number of the card
resultMessageStringA text description for the result of the transaction
resultStatusStringA string describing the result of the
transaction. Should be "true" or "false"
transactionReferenceStringThe transaction reference from the request
transactionTypeStringThe type of transaction that was processed
uniqueTransIdStringThe 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.

Handling Events


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


errorDomainEventDomain enumvalues of:
errorCodeIntAn integer error code for keying off of the event
in response handling. See Error Codes list
recoverySuggestionStringA suggestion for handling/resolving the error
messageStringA 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

1000Request parameter errorY
2000The Magtek device is not accessible to the SDKY
2001The SDK is unable to connect to the Magtek deviceY
2002The device is disconnectedY
2003An error occurred trying to cancel the transactionN
2004The device is in use and unable to receive new requestsN
3000An unknown error occurredN
3001A transaction is in progress. Please wait until the current transaction is

completed before sending another request.
3002No active transactionY
3003The user cancelled the transactionY


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


domainEventDomain enumvalues of:
typeEventType enumvalues of:
messageStringA text description of the event
responseTransactionResponseAn 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