Native Android SDK
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
Device-Initiated Transaction Types
These transaction types can be run on the device or manually entered using the emergepay UI.
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" |
Other Transaction Types
These transaction types do not interact with the device.
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 | Internal reference number for transaction |
transactionReference | String | no | Cashier handling transaction |
env | String: "production " | "sandbox" | no | Indicates which environment transaction will process through. Defaults to "sandbox" |
Adjustment
The Adjustment transaction type can be used to adjust an amount or a tip of an authorized transaction. The uniqueTransId returned from the original transaction request is passed into
the configuration builder below.
private fun adjustment() {
val config = AdjustmentConfig.Builder()
.oid(OID)
.authToken(AUTH_TOKEN)
.uniqueTransId("ce9ad61b3c984a7999677a527cb26a2a-00000000000000...")
.adjustmentType("AuthAdjust")
.cashierId("Shift lead")
.externalTransactionId(<v4 uuid>)
.transactionReference("Invoice 1234")
.env("production")
.build()
emergepay!!.adjustment(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 |
adjustmentType | String: "AuthAdjust" | yes | type of adjustment. At the moment only AuthAdjust is supported |
transactionReference | String | no | Internal reference number for transaction |
cashierId | String | yes | Cashier handling transaction |
env | String | no | Indicates which environment transaction will process through. Defaults to "sandbox" |
State Management Methods
These methods interact with the device, but are not responsible for processing transactions.
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.
Firmware Update Helper Methods
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. |