Native iOS SDK

Device Supported

Connection TypeCard Type
iDynamo6Lightning iAP 2MSR, Contact, Contactless
kDynamoLightning iAP 2MSR, Contact, Contactless

Xcode Build Version

12.5.1

Dependency

What it isLocation
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

TypeValue
UISupportedExternalAccessoryProtocolsArray or Stringcom.magtek.idynamo
NSBluetoothAlwaysUsageDescriptionStringAllow usage of Bluetooth LE for other Bluetooth LE devices
NSBluetoothPeripheralUsageDescriptionStringAllow usage of Bluetooth LE for other Bluetooth LE devices

Error Code

List of possible error codes

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

Delegate callback

On Result

EventArg

propertytypedescription
versionStringData structure can change in the future, version will keep the current data structure according the the number.`
eventEventEvent object
eventDataStringEvent data from processing result

Event

propertytypedescription
domainEventDomainEMVTransaction , TokenizedTransaction , DeviceConfiguration , DeviceInformation ,
CardPresentProcessing , ManualEntryProcessing , PhysicalDeviceConnection , DeviceCommunication , DeviceState
typeEventTypeEMVDisplayMessage , 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

propertytypedescription
errorDomainEventDomainEMVTransaction , TokenizedTransaction , DeviceConfiguration ,
DeviceInformation , CardPresentProcessing , ManualEntryProcessing ,
PhysicalDeviceConnection , DeviceCommunication , DeviceState
errorCodeIntSee Error Code for list.
recoverySuggestionStringIf available recoverySuggestion will suggest how to overcome the error.
errorDescriptionStringCause 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.
parametertyperequireddescription
configTypeConfigTypeyesEMVTags , EMVCAPK , Firmware
var emergepayConfig:EmergepayDeviceConfig = EmergepayDeviceConfig();
_ = emergepayConfig.start(configType: .EMVCAPK)

Card Present Transaction

Credit Sale

EmergepayCardPresent

Main card present class

propertytyperequireddescription
deviceTypeDeviceTypeyesRealDevice or SimulatedMagTekDevice
environmentEmergepayEnvironmentyesProduction or SandBox
delegateEmergepayAPIDelegateyesController delegate for onError and onEvent
versionStringyesData 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

parametertyperequireddescription
transactionTypeStringyes"CreditReturn", "CreditSale", "CreditAuth"
amountStringyesMinimum 4 character amount to charge, ex: 0.99
tipAmountStringyesMinimum 4 character amount to charge, ex: 0.99
transactionReferenceStringyesCan be any string to describe the transaction
externalTransactionIdStringyesV4 UUID
cashierIdStringyesCan be any string to describe the cashier/register

EMVOptions

EMV options to pass to reader

parametertyperequireddescription
transactionTimeStringyesEMV time during for a transaction. Range from 0-255 seconds. 0 means emv
transaction will not time out.
cardTypeCardInputTypeyesSwipe , Contact , SwipeContact , Contactless , ContactContactless ,
SwipeContactContactless
amountStringnoEMV 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

parametertypedescription
resultBoolWhether the operation started successfully or not.
resultMessageStringIf there is an error, the message will provide a description
recoverySuggestionStringA 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

propertytyperequireddescription
endPointStringyesEnd point set up in Dashboard to let EmergepayAPI know when transaction is complete.
environmentEmergepayEnvironmentyesProduction or SandBox
delegateEmergepayAPIDelegateyesController delegate for onError and onEvent
versionStringyesData structure can change in the future, version will keep the
current data structure according the the number.

Credit Sale

CreditSaleConfig

propertytyperequireddescription
baseAmountStringyesMinimum 4 character amount to charge, ex: "1.99"
externalTransactionIdStringyesV4 UUID
billingNameStringnoName on card
billingAddressStringnoAddress on card
billingPostalCodeStringnoZip code for billing information on card
transactionReferenceStringnoCan be any string to describe the transaction
cashierIdStringnoAny string representing Register ID or Employee ID
tipAmountStringnoMinimum 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

propertytyperequireddescription
baseAmountStringyesMinimum 4 character amount to charge, ex: 1.99
externalTransactionIdStringyesV4 UUID
billingNameStringnoName on card
billingAddressStringnoAddress on card
billingPostalCodeStringnoZip code for billing information on card
transactionReferenceStringnoCan be any string to describe the transaction
cashierIdStringnoAny string representing Register ID or Employee ID
tipAmountStringnoMinimum 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

propertytyperequireddescription
baseAmountStringyesMinimum 4 character amount to charge, ex: 1.99
externalTransactionIdStringyesV4 UUID
billingNameStringnoName on card
billingAddressStringnoAddress on card
billingPostalCodeStringnoZip code for billing information on card
transactionReferenceStringnoCan be any string to describe the transaction
cashierIdStringnoAny 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

propertytyperequireddescription
externalTransactionIdStringyesV4 UUID
billingNameStringnoName on card
billingAddressStringnoAddress on card
billingPostalCodeStringnoZip code for billing information on card
transactionReferenceStringnoCan be any string to describe the transaction
cashierIdStringnoAny 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

parametertyperequireddescription
transactionIdStringyesV4 UUID

Return object is Status

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

Void Transaction

parametertyperequireddescription
uniqueTransIdStringyesUnique transaction ID Generated by emergepay
externalTransactionIDStringyesV4 UUID
cashierIdStringnoRegister 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

propertytyperequireddescription
uniqueTransIdStringyesUnique token generated by emergepay
externalTransactionIdStringnoV4 UUID
adjustmentTypeStringnoOnly AuthAdjust is supported
amountStringnoMinimum 4 character amount to charge, ex: 1.99
tipAmountStringnoMinimum 4 character amount to charge, ex: 1.99
transactionReferenceStringnoCan 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

propertytyperequireddescription
amountStringyesMinimum 4 character amount to charge, ex: 1.99
externalTransactionIdStringyesV4 UUID
uniqueTransIdStringyesUnique token generated by emergepay
billingNameStringnoName on card
billingAddressStringnoAddress on card
billingPostalCodeStringnoZip code for billing information on card
transactionReferenceStringnoCan be any string to describe the transaction
cashierIdStringnoRegister ID or Employee ID
tipAmountStringnoMinimum 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

propertytyperequireddescription
amountStringyesMinimum 4 character amount to charge, ex: 1.99
externalTransactionIdStringyesV4 UUID
uniqueTransIdStringyesUnique token generated by emergepay
billingNameStringnoName on card
billingAddressStringnoAddress on card
billingPostalCodeStringnoZip code for billing information on card
transactionReferenceStringnoCan be any string to describe the transaction
cashierIdStringnoRegister ID or Employee ID
tipAmountStringnoMinimum 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

propertytyperequireddescription
amountStringyesMinimum 4 character amount to charge, ex: 1.99
externalTransactionIdStringyesV4 UUID
uniqueTransIdStringyesUnique token generated by emergepay
billingNameStringnoName on card
billingAddressStringnoAddress on card
billingPostalCodeStringnoZip code for billing information on card
transactionReferenceStringnoCan be any string to describe the transaction
cashierIdStringnoRegister 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

propertytyperequireddescription
amountStringyesMinimum 4 character amount to charge, ex: 1.99
externalTransactionIdStringyesV4 UUID
uniqueTransIdStringyesUnique token generated by emergepay
transactionReferenceStringnoCan be any string to describe the transaction
cashierIdStringnoRegister ID or Employee ID
tipAmountStringnoMinimum 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)