Native iOS SDK · Gravity Payments Documentation

Device Supported

	Connection Type	Card Type
iDynamo6	Lightning iAP 2	MSR, Contact, Contactless
kDynamo	Lightning iAP 2	MSR, Contact, Contactless

Xcode Build Version

12.5.1

Dependency

	What it is	Location
MagTek libMTSCRA	MagTek's device SDK	https://www.magtek.com/Content/SoftwarePackages/99510 111.zip

Minimum Targeted iOS Version

iOS 13.0

Getting Started

In order to access External Accessory, you need to add the following to info.plist

	Type	Value
UISupportedExternalAccessoryProtocols	Array or String	com.magtek.idynamo
NSBluetoothAlwaysUsageDescription	String	Allow usage of Bluetooth LE for other Bluetooth LE devices
NSBluetoothPeripheralUsageDescription	String	Allow usage of Bluetooth LE for other Bluetooth LE devices

Error Code

List of possible error codes

Code	Description
-1	Generic Error/Unknown
1	No Internet Connection
1001	Device battery too low for normal operation.
1002	Device is busy, can't respond.
3000	Unknown EMV error
3001	EMV Transaction already started.
3002	No active EMV session

Delegate callback

On Result

EventArg

property	type	description
version	String	Data structure can change in the future, version will keep the current data structure according the the number.`
event	Event	Event object
eventData	String	Event data from processing result

Event

property	type	description
domain	EventDomain	EMVTransaction , TokenizedTransaction , DeviceConfiguration , DeviceInformation , CardPresentProcessing , ManualEntryProcessing , PhysicalDeviceConnection , DeviceCommunication , DeviceState
type	EventType	EMVDisplayMessage , EMVTransactionStatus , ProcessingResult , ReaderConnection

    func onEvent(event: EventArg) {
        do {
            let jsonEncoder = JSONEncoder()
            jsonEncoder.outputFormatting = .prettyPrinted
            let jsonData = try jsonEncoder.encode(event.event)
            let json = String(data: jsonData, encoding: String.Encoding.utf8)
            
            if(event.event?.type == .EMVTransactionStatus)
            {
                let emvTransactionStatus = try JSONDecoder().decode(MagTekEMVStatus.self,
                                                                    from: event.eventData!.data(using:.utf8)!)
                if(emvTransactionStatus.currentProgressIndicator ==
                    .StartEmulatingContactlessLED)
                {
                    DispatchQueue.main.async {
                        let led = LedControl(frame: CGRect(x: 10, y: 180, width:
                                                            self.view.frame.width - 20, height: 50))
                        self.view.addSubview(led) //Add EMV led control
                    }
                }
            }
            //This is how to deserialize the json payload.
            let transactionResponse:TransactionResponse = try
            JSONDecoder().decode(TransactionResponse.self, from:
                                    event.eventData!.data(using:.utf8)!)
        }
        catch {
            print(error)
        }
    }

On Error

Error

property	type	description
errorDomain	EventDomain	EMVTransaction , TokenizedTransaction , DeviceConfiguration , DeviceInformation , CardPresentProcessing , ManualEntryProcessing , PhysicalDeviceConnection , DeviceCommunication , DeviceState
errorCode	Int	See Error Code for list.
recoverySuggestion	String	If available recoverySuggestion will suggest how to overcome the error.
errorDescription	String	Cause of error

    func onError(error: Error) {
        do {
            let jsonEncoder = JSONEncoder()
            jsonEncoder.outputFormatting = .withoutEscapingSlashes
            let jsonData = try jsonEncoder.encode(error)
            let json = String(data: jsonData, encoding: String.Encoding.utf8)
        }
        catch {
        }
    }

Device Configuration

EmergepayDeviceConfig

Allows reconfiguration of device.

Every time firmware is updated, EMV tags and CAPK will need to be updated. Total run time will be around 9 minutes.

Device LED Color:

Blue – Device is in boot loader mode, EMV transactions will not work until device finish loading firmware.
Green – Device is in normal main firmware and ready for to start transaction.

parameter	type	required	description
configType	ConfigType	yes	EMVTags , EMVCAPK , Firmware

var emergepayConfig:EmergepayDeviceConfig = EmergepayDeviceConfig();
_ = emergepayConfig.start(configType: .EMVCAPK)

Card Present Transaction

Credit Sale

EmergepayCardPresent

Main card present class

property	type	required	description
deviceType	DeviceType	yes	RealDevice or SimulatedMagTekDevice
environment	EmergepayEnvironment	yes	Production or SandBox
delegate	EmergepayAPIDelegate	yes	Controller delegate for onError and onEvent
version	String	yes	Data structure can change in the future, version will keep the current data structure according the the number.

TransactionData

Transactional data that will be use by emergepay back end

parameter	type	required	description
transactionType	String	yes	"CreditReturn", "CreditSale", "CreditAuth"
amount	String	yes	Minimum 4 character amount to charge, ex: 0.99
tipAmount	String	yes	Minimum 4 character amount to charge, ex: 0.99
transactionReference	String	yes	Can be any string to describe the transaction
externalTransactionId	String	yes	V4 UUID
cashierId	String	yes	Can be any string to describe the cashier/register

EMVOptions

EMV options to pass to reader

parameter	type	required	description
transactionTime	String	yes	EMV time during for a transaction. Range from 0-255 seconds. 0 means emv transaction will not time out.
cardType	CardInputType	yes	Swipe , Contact , SwipeContact , Contactless , ContactContactless , SwipeContactContactless
amount	String	no	EMV transaction amount, this value should match transactionData amount , it will be used to populate EMV tag 9F02

Status

The return object of function call

This status is not the processing payload but rather the return code for startTransaction to see whether startTransaction completed successfully or not

parameter	type	description
result	Bool	Whether the operation started successfully or not.
resultMessage	String	If there is an error, the message will provide a description
recoverySuggestion	String	A description of what will need to be corrected

    let auth = MerchantCredential(token: "", oid: "")
    var gpCard:EmergepayCardPresent! = nil;
    gpCard = EmergepayCardPresent(authentication: auth, deviceType: .RealDevice);
    gpCard.environment = .SandBox;
    gpCard.delegate = self;
    gpCard.version = "1.0"
    _ = gpCard.subscribeToEvent(event: .EMVTransactionStatus, eventValue: .EMVStatusAll)
    let transactionData = TransactionData()
    transactionData.transactionType = "CreditSale"
    transactionData.amount = "1.99"
    transactionData.tipAmount = "1.00"
    transactionData.transactionReference = "123456"
    transactionData.externalTransactionId = "514504e4-1bb8-470f-819b-cf2aacc5282e"
    let emvOptions = EMVOptions(transactionTime: "30", cardType: .SwipeContactContactless,
                                amount: "1.99");
    let result = gpCard.startTransaction( emvOptions: emvOptions, transactionData:
                                            transactionData)

Cancel Transaction

Cancels the current EMV transaction, this can only be done before card is inserted/tapped

gpCard.cancelTransaction()

Manual Entry Transactions

EmergepayManualEntry

property	type	required	description
endPoint	String	yes	End point set up in Dashboard to let EmergepayAPI know when transaction is complete.
environment	EmergepayEnvironment	yes	Production or SandBox
delegate	EmergepayAPIDelegate	yes	Controller delegate for onError and onEvent
version	String	yes	Data structure can change in the future, version will keep the current data structure according the the number.

Credit Sale

CreditSaleConfig

property	type	required	description
baseAmount	String	yes	Minimum 4 character amount to charge, ex: "1.99"
externalTransactionId	String	yes	V4 UUID
billingName	String	no	Name on card
billingAddress	String	no	Address on card
billingPostalCode	String	no	Zip code for billing information on card
transactionReference	String	no	Can be any string to describe the transaction
cashierId	String	no	Any string representing Register ID or Employee ID
tipAmount	String	no	Minimum 4 character amount to charge, ex: "1.99"

return object is Status

    let creditSaleConfig = CreditSaleConfig(baseAmount: "1.99",
                                            externalTransactionId: "514504e4-1bb8-
                                            470f-819b-cf2aacc5282e",
                                            billingName: "Fist and Last",
                                            billingAddress: "1234 Any St",
                                            billingPostalCode: "00000",
                                            transactionReference: "Order 12345",
                                            cashierId: "1",
                                            tipAmount: "1.00")
    
    let gp = EmergepayManualEntry(authentication: auth);
    gp.environment = .SandBox
    gp.delegate = self;
    gp.version = "1.0"
    gp.endPoint = "http://ios.test.gravitypayments.com/transactions/complete";
    let result = gp.creditSale(controller: self, config: creditSaleConfig)

Credit Auth

CreditAuthConfig

property	type	required	description
baseAmount	String	yes	Minimum 4 character amount to charge, ex: 1.99
externalTransactionId	String	yes	V4 UUID
billingName	String	no	Name on card
billingAddress	String	no	Address on card
billingPostalCode	String	no	Zip code for billing information on card
transactionReference	String	no	Can be any string to describe the transaction
cashierId	String	no	Any string representing Register ID or Employee ID
tipAmount	String	no	Minimum 4 character amount to charge, ex: 1.99

Return object is Status

    let creditAuthConfig = CreditAuthConfig(baseAmount: "1.99",
                                            externalTransactionId: "514504e4-1bb8-
                                            470f-819b-cf2aacc5282e",
                                            billingName: "Fist and Last",
                                            billingAddress: "1234 Any St",
                                            billingPostalCode: "00000",
                                            transactionReference: "Order 12345",
                                            cashierId: "1",
                                            tipAmount: "1.00")
    let gp = EmergepayManualEntry(authentication: auth);
    gp.environment = .SandBox
    gp.delegate = self;
    gp.version = "1.0"
    gp.endPoint = "http://ios.test.gravitypayments.com/transactions/complete";
    let result = gp.creditAuth(controller: self, config: creditAuthConfig)

Credit Return

CreditReturnConfig

property	type	required	description
baseAmount	String	yes	Minimum 4 character amount to charge, ex: 1.99
externalTransactionId	String	yes	V4 UUID
billingName	String	no	Name on card
billingAddress	String	no	Address on card
billingPostalCode	String	no	Zip code for billing information on card
transactionReference	String	no	Can be any string to describe the transaction
cashierId	String	no	Any string representing Register ID or Employee ID

Return object is Status

    let creditReturnConfig = CreditReturnConfig(baseAmount: "1.99",
                                                externalTransactionId: "514504e4-1bb8-
                                                470f-819b-cf2aacc5282e",
                                                billingName: "Fist and Last",
                                                billingAddress: "1234 Any St",
                                                billingPostalCode: "00000",
                                                transactionReference: "Order 12345",
                                                cashierId: "1")
    let gp = EmergepayManualEntry(authentication: auth);
    gp.environment = .SandBox
    gp.delegate = self;
    gp.version = "1.0"
    gp.endPoint = "http://ios.test.gravitypayments.com/transactions/complete";
    let result = gp.creditReturn(controller: self, config: creditReturnConfig)

Credit Save Card

CreditSaveCardConfig

property	type	required	description
externalTransactionId	String	yes	V4 UUID
billingName	String	no	Name on card
billingAddress	String	no	Address on card
billingPostalCode	String	no	Zip code for billing information on card
transactionReference	String	no	Can be any string to describe the transaction
cashierId	String	no	Any string representing Register ID or Employee ID

Return object is Status

    let creditSaveCardConfig = CreditSaveCardConfig(externalTransactionId: "514504e4-1bb8-
                                                    470f-819b-cf2aacc5282e",
                                                    billingName: "Fist and Last",
                                                    billingAddress: "1234 Any St",
                                                    billingPostalCode: "00000",
                                                    transactionReference: "Order 12345",
                                                    cashierId: "1")
    let gp = EmergepayManualEntry(authentication: auth);
    gp.environment = .SandBox
    gp.delegate = self;
    gp.version = "1.0"
    gp.endPoint = "http://ios.test.gravitypayments.com/transactions/complete";
    let result = gp.creditSaveCard(controller: self, config: CreditSaveCardConfig)

Retrieve Transaction

parameter	type	required	description
transactionId	String	yes	V4 UUID

Return object is Status

let gp = EmergepayAPI(authentication: auth)
gp.delegate = self;
gp.retreiveTransaction(transactionID: "514504e4-1bb8-470f-819b-cf2aacc5282e")

Void Transaction

parameter	type	required	description
uniqueTransId	String	yes	Unique transaction ID Generated by emergepay
externalTransactionID	String	yes	V4 UUID
cashierId	String	no	Register ID or Employee ID

Return object is Status

    let gp = EmergepayAPI.init(authentication: auth)
    gp.delegate = self;
    gp.voidTransaction(uniqueTransId: "d5601f6158cc4c76b8ed378837edb9a3-
                       00000000000000000000000000000000", externalTransactionID:
                       "514504e4-1bb8-470f-819b-cf2aacc5282e",
                       cashierId:"1")

Adjust Transaction

AdjustmentConfig

property	type	required	description
uniqueTransId	String	yes	Unique token generated by emergepay
externalTransactionId	String	no	V4 UUID
adjustmentType	String	no	Only AuthAdjust is supported
amount	String	no	Minimum 4 character amount to charge, ex: 1.99
tipAmount	String	no	Minimum 4 character amount to charge, ex: 1.99
transactionReference	String	no	Can be any string to describe the transaction

    let gp = EmergepayAPI(authentication: auth)
    gp.delegate = self;
    let adjustmentConfig = AdjustmentConfig(uniqueTransId:
                                                "c15156989dbc404aa35b990fad67ca90-58afe32181424d859736b6f5c8045f0b",
                                            
                                            externalTransactionId: "514504e4-1bb8-470f-
                                            819b-cf2aacc5282e",
                                            
                                            adjustmentType: "AuthAdjust",
                                            amount: "9.99",
                                            tipAmount: "2.00",
                                            cashierId: "1",
                                            transactionReference: "Order 12345")
    gp.adjustment(config: adjustmentConfig)

Tokenized Payment

TokenizePaymentConfig

property	type	required	description
amount	String	yes	Minimum 4 character amount to charge, ex: 1.99
externalTransactionId	String	yes	V4 UUID
uniqueTransId	String	yes	Unique token generated by emergepay
billingName	String	no	Name on card
billingAddress	String	no	Address on card
billingPostalCode	String	no	Zip code for billing information on card
transactionReference	String	no	Can be any string to describe the transaction
cashierId	String	no	Register ID or Employee ID
tipAmount	String	no	Minimum 4 character amount to charge, ex: 1.99

    let gp = EmergepayAPI(authentication: auth)
    gp.delegate = self;
    let tokenConfig = TokenizePaymentConfig(amount: "1.99",
                                            externalTransactionId: "514504e4-1bb8-
                                            470f-819b-cf2aacc5282e",
                                            uniqueTransId:
                                                "c15156989dbc404aa35b990fad67ca90-58afe32181424d859736b6f5c8045f0b",
                                            billingName: "First and Last",
                                            billingAddress: "1234 Any St",
                                            billingPostalCode: "00000",
                                            transactionReference: "Order 12345",
                                            cashierId: "1",
                                            tipAmount: "1.00")
    gp.tokenizedPayment(config: tokenConfig)

Tokenized Auth

TokenizedAuthConfig

property	type	required	description
amount	String	yes	Minimum 4 character amount to charge, ex: 1.99
externalTransactionId	String	yes	V4 UUID
uniqueTransId	String	yes	Unique token generated by emergepay
billingName	String	no	Name on card
billingAddress	String	no	Address on card
billingPostalCode	String	no	Zip code for billing information on card
transactionReference	String	no	Can be any string to describe the transaction
cashierId	String	no	Register ID or Employee ID
tipAmount	String	no	Minimum 4 character amount to charge, ex: 1.99

    let gp = EmergepayAPI(authentication: auth)
    gp.delegate = self;
    let tokenConfig = TokenizedAuthConfig(amount: "1.99",
                                          
                                          externalTransactionId: "60837d13-594e-
                                          4e04-829a-96a05e81ec4a",
                                          
                                          uniqueTransId:
                                            "c15156989dbc404aa35b990fad67ca90-58afe32181424d859736b6f5c8045f0b",
                                          billingName: "Fist and Last",
                                          billingAddress: "1234 Any St",
                                          billingPostalCode: "00000",
                                          transactionReference: "Order 12345",
                                          cashierId: "1",
                                          tipAmount: "1.00")
    gp.tokenizedAuthorization(config: tokenConfig)

Tokenized Refund

TokenizedRefundConfig

property	type	required	description
amount	String	yes	Minimum 4 character amount to charge, ex: 1.99
externalTransactionId	String	yes	V4 UUID
uniqueTransId	String	yes	Unique token generated by emergepay
billingName	String	no	Name on card
billingAddress	String	no	Address on card
billingPostalCode	String	no	Zip code for billing information on card
transactionReference	String	no	Can be any string to describe the transaction
cashierId	String	no	Register ID or Employee ID

    let gp = EmergepayAPI(authentication: auth)
    gp.delegate = self;
    let tokenConfig = TokenizedRefundConfig(amount: "1.99",
                                            
                                            externalTransactionId: "60837d13-594e-
                                            4e04-829a-96a05e81ec4a",
                                            
                                            uniqueTransId:
                                                "c15156989dbc404aa35b990fad67ca90-58afe32181424d859736b6f5c8045f0b",
                                            billingName: "Fist and Last",
                                            billingAddress: "1234 Any St",
                                            billingPostalCode: "00000",
                                            transactionReference: "Order 12345",
                                            cashierId: "1")
    gp.tokenizedRefund(config: tokenConfig)

Tokenized Force

TokenizedForceConfig

property	type	required	description
amount	String	yes	Minimum 4 character amount to charge, ex: 1.99
externalTransactionId	String	yes	V4 UUID
uniqueTransId	String	yes	Unique token generated by emergepay
transactionReference	String	no	Can be any string to describe the transaction
cashierId	String	no	Register ID or Employee ID
tipAmount	String	no	Minimum 4 character amount to charge, ex: 1.99

    let gp = EmergepayAPI(authentication: auth)
    gp.delegate = self;
    let tokenConfig = TokenizedForceConfig(amount: "1.99",
                                           
                                           externalTransactionId: "60837d13-594e-
                                           4e04-829a-96a05e81ec4a",
                                           
                                           uniqueTransId:
                                            "c15156989dbc404aa35b990fad67ca90-58afe32181424d859736b6f5c8045f0b",
                                           transactionReference: "Order 12345",
                                           cashierId: "1")
    gp.tokenizedForce(config: tokenConfig)